Pular para o conteúdo

E-mails de produto

Envie emails de redefinição de senha pelo seu app

Crie uma notificação transacional para redefinição de senha e envie-a pelo seu backend com uma única chamada de API.

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.
  1. 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 data ficam 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.

  2. 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
    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.

  3. 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.

  4. Envie o email pelo seu backend

    Chame POST /api/transactional.send com 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 um email válido.
    • notification.data: as variáveis do template, aqui reset_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 200 com {"message_id": "…", "success": true}. Um erro retorna um corpo JSON com um campo error, por exemplo 400 quando falta um campo ou o identificador de API não existe, e 500 quando 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.

Uma mensagem aberta em Logs, com os eventos de entrega e os dados com que foi enviada
Uma mensagem aberta em Logs, com os eventos de entrega e os dados com que foi enviada

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