> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 }}`.

```liquid
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](https://www.notifuse.com/pt/docs/features/templates.md) 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](https://www.notifuse.com/docs/assets/screenshots/transactional_notification_edit.png)

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**

```bash
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**

```javascript
// 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**

```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
<?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**

```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](https://www.notifuse.com/pt/docs/features/transactional-api.md#permissions).

## 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](https://www.notifuse.com/pt/docs/features/logs.md).

![Uma mensagem aberta em Logs, com os eventos de entrega e os dados com que foi enviada](https://www.notifuse.com/docs/assets/screenshots/logs_message_detail.png)

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](https://www.notifuse.com/pt/docs/features/transactional-api.md) lista todos os campos da requisição, incluindo `email_options` para reply-to, CC, BCC e anexos.
- [Monte uma sequência de boas-vindas](https://www.notifuse.com/pt/docs/guides/welcome-sequence.md) para os emails que vêm depois de um cadastro.
- [Webhooks](https://www.notifuse.com/pt/docs/features/webhooks.md) para receber no seu app os eventos de entrega e de rejeição.
