Quando um usuário pede para redefinir a senha, seu app chama a API do Notifuse, e o Notifuse envia a ele um email com o link de redefinição gerado pelo app.
Antes de começar
- Um workspace com um provedor de email definido para Emails transacionais em Configurações › Integrações. Sem ele, a página Transacional avisa que as notificações não podem ser enviadas.
- Um backend que cria o link de redefinição (token, validade, a página que o verifica). O Notifuse só entrega o link.
- O ID do seu workspace. É o ID que você escolheu ao criar o workspace, e ele aparece na URL do console depois de
/console/workspace/. - O endereço da sua instância do Notifuse, o mesmo em que você abre o console. Os exemplos usam
https://YOUR_NOTIFUSE_HOST.
Crie o template de email
Abra Templates, clique em Novo modelo e escolha o modelo Redefinição de senha na Galeria. Ele já tem um botão e uma cópia do link em texto simples, os dois apontando para
{{ reset_url }}.Você também pode começar de um template em branco. Defina a Categoria dele como Transacional, porque uma notificação só lista templates dessa categoria.
O template pode usar dois tipos de variável:
- As chaves que você envia em
dataficam no nível mais alto. Escreva{{ reset_url }}, e não{{ data.reset_url }}. - O contato fica em
contact, por exemplo{{ contact.first_name }}ou{{ contact.email }}.
Hi {{ contact.first_name }}, <a href="{{ reset_url }}">Choose a new password</a>Defina o Assunto e o Remetente nas configurações do template e salve. Veja Templates para conhecer o editor e os dados de teste usados na visualização.
- As chaves que você envia em
Crie a notificação transacional
Abra Transacional e clique em Nova notificação. Preencha:
- Nome: o que você vai ver no console, por exemplo “Password Reset Email”.
- Identificador de API: o que o seu código envia, por exemplo
password_reset. Só letras minúsculas, números e sublinhados, com no máximo 32 caracteres. Ele não pode mudar depois que a notificação é criada. - Template de email: o template da etapa 1.
Clique em Criar notificação.
Uma notificação transacional: o nome, o identificador de API fixo password_reset e o template de email A página da notificação tem um painel Chamada de API com uma requisição pronta em cURL, TypeScript e Python, e Todas as linguagens mostra outras.
Crie uma chave API
Vá em Configurações › Equipe e chaves API e clique em Criar Chave API. Dê a ela um Nome da Chave API, como “Backend password reset”.
Em Permissões, a escrita em Transacional basta para enviar. Uma chave sem mais nada consegue enviar emails, mas não consegue ler nem editar seus contatos. Se o console disser que permissões personalizadas exigem uma licença do Notifuse Studio, a chave só pode ter acesso total, e ela funciona do mesmo jeito para este guia.
Clique em Criar Chave API e copie o token na hora: ele aparece uma única vez e não pode ser recuperado depois. Guarde-o nos segredos do seu backend, nunca em código que roda no navegador.
Envie o email pelo seu backend
Chame
POST /api/transactional.sendcom o token como bearer token. O corpo precisa de:workspace_id: o ID do seu workspace.notification.id: o identificador de API,password_reset.notification.channels:["email"]. É obrigatório ter pelo menos um canal.notification.contact: o destinatário, com pelo menos umemailválido.notification.data: as variáveis do template, aquireset_url.notification.external_id(opcional): um ID seu para este envio, usado para evitar duplicatas. Veja a próxima seção.
cURL
curl -X POST "https://YOUR_NOTIFUSE_HOST/api/transactional.send" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "workspace_id": "YOUR_WORKSPACE_ID", "notification": { "id": "password_reset", "external_id": "pwd-reset-u123-1700000000", "channels": ["email"], "contact": { "email": "user@example.com", "first_name": "Ada" }, "data": { "reset_url": "https://app.example.com/reset?token=abc123" } } }'Node.js
// Node.js 18 or later (built-in fetch) async function sendPasswordReset(user, resetRequestId, resetUrl) { const response = await fetch('https://YOUR_NOTIFUSE_HOST/api/transactional.send', { method: 'POST', headers: { Authorization: `Bearer ${process.env.NOTIFUSE_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ workspace_id: 'YOUR_WORKSPACE_ID', notification: { id: 'password_reset', external_id: `pwd-reset-${user.id}-${resetRequestId}`, channels: ['email'], contact: { email: user.email, first_name: user.firstName }, data: { reset_url: resetUrl } } }) }) const result = await response.json() if (!response.ok) { throw new Error(`Notifuse error ${response.status}: ${result.error}`) } return result.message_id }Python
import os import requests def send_password_reset(user, reset_request_id, reset_url): response = requests.post( "https://YOUR_NOTIFUSE_HOST/api/transactional.send", headers={"Authorization": f"Bearer {os.environ['NOTIFUSE_API_KEY']}"}, json={ "workspace_id": "YOUR_WORKSPACE_ID", "notification": { "id": "password_reset", "external_id": f"pwd-reset-{user['id']}-{reset_request_id}", "channels": ["email"], "contact": {"email": user["email"], "first_name": user["first_name"]}, "data": {"reset_url": reset_url}, }, }, timeout=10, ) result = response.json() if not response.ok: raise RuntimeError(f"Notifuse error {response.status_code}: {result.get('error')}") return result["message_id"]PHP
<?php function sendPasswordReset(array $user, string $resetRequestId, string $resetUrl): string { $payload = [ 'workspace_id' => 'YOUR_WORKSPACE_ID', 'notification' => [ 'id' => 'password_reset', 'external_id' => "pwd-reset-{$user['id']}-{$resetRequestId}", 'channels' => ['email'], 'contact' => ['email' => $user['email'], 'first_name' => $user['first_name']], 'data' => ['reset_url' => $resetUrl], ], ]; $ch = curl_init('https://YOUR_NOTIFUSE_HOST/api/transactional.send'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('NOTIFUSE_API_KEY'), 'Content-Type: application/json', ], CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_TIMEOUT => 10, ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); $result = json_decode($body, true); if ($status !== 200) { throw new RuntimeException("Notifuse error {$status}: " . ($result['error'] ?? $body)); } return $result['message_id']; }Go
package notify import ( "bytes" "encoding/json" "fmt" "net/http" "os" "time" ) func SendPasswordReset(userID, email, firstName, resetRequestID, resetURL string) (string, error) { payload := map[string]any{ "workspace_id": "YOUR_WORKSPACE_ID", "notification": map[string]any{ "id": "password_reset", "external_id": fmt.Sprintf("pwd-reset-%s-%s", userID, resetRequestID), "channels": []string{"email"}, "contact": map[string]string{"email": email, "first_name": firstName}, "data": map[string]string{"reset_url": resetURL}, }, } body, err := json.Marshal(payload) if err != nil { return "", err } req, err := http.NewRequest(http.MethodPost, "https://YOUR_NOTIFUSE_HOST/api/transactional.send", bytes.NewReader(body)) if err != nil { return "", err } req.Header.Set("Authorization", "Bearer "+os.Getenv("NOTIFUSE_API_KEY")) req.Header.Set("Content-Type", "application/json") client := &http.Client{Timeout: 10 * time.Second} resp, err := client.Do(req) if err != nil { return "", err } defer resp.Body.Close() var result struct { MessageID string `json:"message_id"` Error string `json:"error"` } if err := json.NewDecoder(resp.Body).Decode(&result); err != nil { return "", err } if resp.StatusCode != http.StatusOK { return "", fmt.Errorf("notifuse error %d: %s", resp.StatusCode, result.Error) } return result.MessageID, nil }Uma chamada bem-sucedida retorna
200com{"message_id": "…", "success": true}. Um erro retorna um corpo JSON com um campoerror, por exemplo400quando falta um campo ou o identificador de API não existe, e500quando o envio falha no provedor.
Evite emails duplicados com external_id
Se já existe no workspace uma mensagem com o mesmo external_id, o Notifuse não envia nada e retorna o message_id da primeira mensagem. Assim, seu código pode repetir uma chamada que expirou sem que o usuário receba dois emails.
Use um external_id por pedido de redefinição, por exemplo o ID do usuário mais o ID ou a data de criação do token de redefinição. Se o usuário pedir um novo link mais tarde, o novo pedido precisa de um novo external_id. Caso contrário, a chamada dá certo e nenhum email sai.
Campos do contato e uma chave só de envio
O Notifuse cria o contato quando o endereço de email ainda não está no workspace. Com uma chave que só tem a escrita em Transacional:
- Um contato novo é salvo só com o endereço de email. Os outros campos que você envia, como
first_name, são descartados, então{{ contact.first_name }}fica vazio nesse primeiro email. - Um contato existente nunca é modificado, e o template usa os campos que já estão gravados.
Se o email precisa cumprimentar o usuário pelo nome, adicione a escrita em Contatos à chave ou envie o nome em data e escreva {{ first_name }} no template. Veja API transacional.
Confira se funciona
Dispare uma redefinição para o seu próprio endereço pelo app, ou rode o exemplo em cURL com ele.
Abra Logs, fique na aba Mensagens e procure seu endereço de email ou o external_id que você enviou. A mensagem deve mostrar a origem Transacional. Clique nela para ver os eventos (enviado, entregue, aberto) e, em Dados, o reset_url com que ela foi enviada. Veja Logs.
Envie a mesma requisição uma segunda vez: a resposta traz o mesmo message_id, e nenhum segundo email aparece em Logs.
Próximos passos
- API transacional lista todos os campos da requisição, incluindo
email_optionspara reply-to, CC, BCC e anexos. - Monte uma sequência de boas-vindas para os emails que vêm depois de um cadastro.
- Webhooks para receber no seu app os eventos de entrega e de rejeição.
