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

# API transacional

> Envie emails disparados por eventos a partir da sua aplicação. Ao contrário dos broadcasts, os emails transacionais vão para um contato por vez, em tempo real, e o Notifuse cria ou atualiza o contato no envio. Use-os para as notificações que os seus usuários disparam e para fluxos automatizados.

![Lista de notificações transacionais no console](https://www.notifuse.com/docs/assets/screenshots/transactional_api.png)

## Casos de uso comuns

```
- Password Reset
- Order Confirmation
- Welcome Email
- Account Deletion
- Purchase Receipt
- Shipping Notifications
- Account Verification
- Payment Confirmations
```

## Principais recursos

### Gestão automática de contatos

- O objeto `contact` da requisição cria o contato ou atualiza os campos dele antes do envio, para que as informações fiquem em dia.
- Os dados do template (`data`) não são salvos no contato. As chaves deles viram variáveis de primeiro nível do template, e o perfil salvo do contato fica disponível em `contact`.

Atualizar o contato dessa forma exige a permissão de escrita de Contatos. Sem ela, um envio só cria um contato que ainda não existe, a partir do endereço de email, e nunca altera um contato existente (veja [Permissões](#permissions)).

### Enriquecimento dos dados do template

Quando você envia um email transacional, o Notifuse:

1. Cria ou atualiza o contato e depois o busca pelo endereço de email no seu workspace
2. Coloca as chaves de `data` no primeiro nível das variáveis do template, e o perfil salvo do contato em `contact`
3. Renderiza o template com as informações completas do contato
4. Envia o email personalizado

**Exemplo**: se a sua API envia `"data": {"order_id": "12345"}` e o perfil do contato contém `{"first_name": "John", "last_name": "Doe"}`, o template pode usar `{{ order_id }}` e `{{ contact.first_name }}`.

### Deduplicação com ID externo

- Defina `external_id` para não enviar a mesma notificação duas vezes: as notificações com o mesmo `external_id` são enviadas uma vez só.
- Use os seus próprios identificadores únicos (IDs de pedido, IDs de evento etc.).

**Exemplo**: com `external_id: "order-12345"`, a confirmação do pedido é entregue uma vez, mesmo que o seu sistema a envie várias vezes.

### Opções de entrega do email

Cada envio pode definir:

- **Nome do Remetente**: substitui o nome de exibição padrão do remetente
- **Assunto**: substitui a linha de assunto do template (aceita Liquid)
- **Reply-To**: define endereços de resposta personalizados
- **CC**: adiciona destinatários em cópia
- **BCC**: inclui destinatários em cópia oculta
- **Anexos**: anexa arquivos aos emails (PDFs, imagens, documentos etc.)

### Rastreamento

As aberturas e os cliques seguem as configurações do workspace e o [consentimento de rastreamento](https://www.notifuse.com/pt/docs/features/email-tracking.md) do contato. Um `contact` na requisição pode levar `tracking_opens_consent` e `tracking_clicks_consent`, registrados com a origem `api`, a menos que você envie `tracking_consent_source`. Cada notificação também pode desativar o rastreamento:

- **Sem rastreamento de aberturas ou cliques, manter UTM** (`tracking_mode: "no_tracking"`)
- **Desativado para esta notificação** (`tracking_mode: "disabled"`): os links nunca são reescritos e não levam rastreamento nem parâmetros UTM. Use essa opção para os links que precisam ficar como estão, como os links de login

## Monitoramento no console

A página **Transacional** lista as suas notificações com as estatísticas dos últimos 7, 30 ou 60 dias, incluindo hoje:

- **Totais**: emails enviados, taxa de entrega com a variação desde o período anterior, taxas de abertura e de cliques nos emails rastreados, falhas e rejeições.
- **Uma linha por notificação**: o template, os emails enviados, as taxas de entrega, de abertura e de cliques, as falhas, a taxa de rejeição e a data do último envio bem-sucedido. Uma taxa de entrega abaixo de 97% e uma taxa de rejeição a partir de 2% ficam destacadas. Busque por nome ou por ID.
- **Ações da linha**: enviar um teste, mostrar o comando da API e, pelo menu, editar, visualizar o template, copiar o ID, abrir as mensagens da notificação nos [logs](https://www.notifuse.com/pt/docs/features/logs.md) ou excluí-la.

Clique em uma linha para abrir a visão detalhada da notificação, que tem o próprio link para compartilhar. Ela mostra as mesmas estatísticas para essa notificação, com links para as mensagens correspondentes nos logs. Também traz os envios por dia, os últimos envios (atualizados a cada 30 segundos), uma pré-visualização do template, as configurações de rastreamento e de UTM, o remetente padrão e a chamada da API em cURL, TypeScript e Python.

As teclas **K** e **J** passam para a notificação anterior ou para a seguinte.

Com um provedor SMTP, as taxas de entrega e de rejeição não ficam disponíveis, porque o SMTP não envia eventos de entrega. As estatísticas exigem a permissão de leitura de Histórico de Mensagens.

## Endpoint da API

Envie um email transacional com uma requisição POST:

### Requisição

```bash
curl -X POST \
  "https://v3.notifuse.com/api/transactional.send" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "pwd-reset-user123-20240101",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "2024-01-01T12:00:00Z"
    },
    "metadata": {
      "user_id": "12345",
      "trigger": "forgot_password",
      "source": "web_app"
    },
    "email_options": {
      "from_name": "Support Team",
      "subject": "Reset your password, {{ contact.first_name }}",
      "reply_to": "support@yourcompany.com",
      "cc": ["admin@yourcompany.com"],
      "bcc": ["logs@yourcompany.com"],
      "attachments": [
        {
          "filename": "reset-guide.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf"
        }
      ]
    }
  }
}'
```

### Parâmetros

| Parâmetro                    | Tipo   | Obrigatório | Descrição                                             |
| ---------------------------- | ------ | ----------- | ----------------------------------------------------- |
| `workspace_id`               | string | Sim         | Identificador do seu workspace                        |
| `notification.id`            | string | Sim         | Identificador do template do email                    |
| `notification.external_id`   | string | Não         | Identificador único para a deduplicação               |
| `notification.channels`      | array  | Sim         | Precisa incluir "email"                               |
| `notification.contact`       | object | Sim         | Objeto do contato com pelo menos o campo email        |
| `notification.data`          | object | Não         | Variáveis do template para o conteúdo do email        |
| `notification.metadata`      | object | Não         | Dados de rastreamento (não disponíveis nos templates) |
| `notification.email_options` | object | Não         | Configuração de roteamento do email                   |

### Opções de email

| Parâmetro     | Tipo   | Descrição                                                                                                                                                                                 |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sender_id`   | string | Envia a partir deste remetente da integração de email transacional, em vez do remetente do template. Um ID desconhecido é recusado com um 400 antes de o contato ser criado ou atualizado |
| `from_name`   | string | Substitui o nome de exibição padrão do remetente                                                                                                                                          |
| `subject`     | string | Substitui a linha de assunto do template (aceita Liquid, máximo de 255)                                                                                                                   |
| `reply_to`    | string | Define um endereço de resposta personalizado, no lugar do reply-to do template                                                                                                            |
| `cc`          | array  | Lista de destinatários em cópia                                                                                                                                                           |
| `bcc`         | array  | Lista de destinatários em cópia oculta                                                                                                                                                    |
| `attachments` | array  | Arquivos anexados (máximo de 20 arquivos, 3MB por arquivo, 10MB no total)                                                                                                                 |

## Data e metadata

### Variáveis do template (`data`)

O objeto `data` contém as variáveis que os seus templates de email podem usar:

```json
{
  "data": {
    "order_id": "ORD-12345",
    "total": "$99.99",
    "discount_code": "WELCOME20"
  }
}
```

Elas podem ser usadas nos templates assim: `{{ order_id }}`, `{{ total }}`, `{{ discount_code }}`

### Dados de rastreamento (`metadata`)

O objeto `metadata` guarda informações para análise e rastreamento e **não fica disponível** nos templates:

```json
{
  "metadata": {
    "campaign_id": "welcome-series",
    "source": "mobile_app",
    "user_segment": "premium"
  }
}
```

Use metadata para rastreamento interno, análises e relatórios.

## Anexos de email

Anexe faturas, recibos, ingressos ou outros documentos aos seus emails transacionais. Os anexos são deduplicados automaticamente no armazenamento.

### Limites dos anexos

- **Máximo de arquivos**: 20 anexos por email
- **Tamanho do arquivo**: 3MB por arquivo
- **Tamanho total**: 10MB por email
- **Formatos suportados**: todos os tipos de arquivo (PDF, PNG, JPEG, DOCX etc.)

### Parâmetros dos anexos

| Parâmetro      | Tipo   | Obrigatório | Descrição                                                                                                                                                                   |
| -------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `filename`     | string | Sim         | Nome do arquivo (máximo de 255 caracteres)                                                                                                                                  |
| `content`      | string | Sim         | Conteúdo do arquivo codificado em Base64                                                                                                                                    |
| `content_type` | string | Não         | Tipo MIME (por exemplo, "application/pdf"), detectado automaticamente se não for informado                                                                                  |
| `disposition`  | string | Não         | "attachment" (padrão) ou "inline"                                                                                                                                           |
| `content_id`   | string | Não         | Content-ID dos anexos inline, referenciado no corpo HTML como `<img src="cid:...">`. Só é permitido quando `disposition` é "inline". Quando omitido, usa o nome do arquivo. |

### Exemplo com fatura em PDF

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "contact": {
      "email": "customer@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99"
    },
    "email_options": {
      "attachments": [
        {
          "filename": "invoice-12345.pdf",
          "content": "JVBERi0xLjQKJeLjz9MKMy4uLg==",
          "content_type": "application/pdf",
          "disposition": "attachment"
        }
      ]
    }
  }
}
```

### Exemplo com vários anexos

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "invoice.pdf",
        "content": "JVBERi0xLjQKJeLjz9MK...",
        "content_type": "application/pdf"
      },
      {
        "filename": "receipt.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png"
      },
      {
        "filename": "terms.docx",
        "content": "UEsDBBQABgAIAAAAIQ...",
        "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
      }
    ]
  }
}
```

### Imagens inline (Content-ID)

Incorpore no corpo do email imagens próprias de cada destinatário, como QR codes ou gráficos personalizados, em vez de hospedá-las em uma URL. Defina `disposition` como `"inline"`, dê ao anexo um `content_id` e faça referência a ele no HTML do seu template como `<img src="cid:...">`:

```json
{
  "email_options": {
    "attachments": [
      {
        "filename": "check-in-qr.png",
        "content": "iVBORw0KGgoAAAANSUhEU...",
        "content_type": "image/png",
        "disposition": "inline",
        "content_id": "checkInQr"
      }
    ]
  }
}
```

E no template do email:

```html
<img src="cid:checkInQr" alt="Your check-in QR code" />
```

Observações:

- `content_id` só pode conter letras, dígitos e os caracteres `.` `_` `-` `@` (máximo de 255 caracteres), e só é aceito quando `disposition` é `"inline"`.
- Quando `content_id` é omitido, o nome do arquivo é usado como Content-ID, então `<img src="cid:check-in-qr.png">` também funciona.
- As imagens inline são entregues dentro de uma parte MIME `multipart/related` junto com o corpo HTML, então os clientes de email as mostram no corpo, e não como anexos para baixar.
- Como a imagem viaja dentro do corpo da mensagem, os proxies de links e os serviços de cache de imagens nunca a buscam nem a registram. Isso convém a segredos próprios de cada destinatário, como os QR codes.
- No Mailgun, o `content_id` também vira o nome do arquivo da parte entregue, então prefira um `content_id` com extensão de arquivo (por exemplo, `checkInQr.png`) ao enviar pelo Mailgun.

### Casos de uso comuns

- **Confirmações de pedido**: anexe faturas e recibos
- **Confirmações de reserva**: anexe ingressos e itinerários
- **Documentos jurídicos**: anexe contratos e acordos
- **Relatórios**: anexe relatórios de análise e resumos
- **Certificados**: anexe certificados de conclusão e selos
- **Ingressos de eventos**: incorpore QR codes de cada destinatário como imagens inline

## Ponte SMTP

O Notifuse tem um servidor de ponte SMTP integrado, então você pode enviar emails transacionais a partir de clientes SMTP comuns em vez de chamar a API HTTP. Ele serve para:

- **Sistemas legados**: integrar aplicações existentes que só suportam SMTP
- **Bibliotecas de email**: usar as bibliotecas de email comuns de qualquer linguagem de programação
- **Integração com frameworks**: trabalhar com frameworks que já têm suporte a SMTP
- **Migração gradual**: sair dos provedores de email atuais sem alterar o código da aplicação

### Como funciona

O servidor de ponte SMTP aceita emails na porta 587 (STARTTLS) ou 465 (TLS implícito). O corpo do email precisa conter um payload JSON no formato da API transacional, e você se autentica com as credenciais de API do seu workspace.

### Enviar emails por SMTP

#### Autenticação

- **Nome de Usuário**: o email de API do seu workspace (o email associado à sua chave API)
- **Senha**: a chave API do seu workspace
- **Segurança**: STARTTLS (porta 587) ou TLS implícito / SMTPS (porta 465), conforme a configuração `SMTP_BRIDGE_TLS`
- **Servidor**: o host da ponte SMTP que você configurou (por exemplo, `smtp.yourdomain.com`)

#### Formato do email

O corpo do email precisa ser um payload JSON no formato da API transacional:

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "password_reset",
    "external_id": "unique-id-123",
    "channels": ["email"],
    "contact": {
      "email": "user@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    "data": {
      "reset_token": "abc123",
      "expiry_time": "1 hour"
    }
  }
}
```

## Permissões

A permissão de escrita de **Transacional**, sozinha, basta para enviar, tanto pela API quanto pela ponte SMTP. Por isso, uma chave API só de envio é prática: dê a uma chave a escrita de Transacional e nada mais, e ela consegue enviar emails sem ler nem editar nenhum contato. Veja [Administradores e chaves API](https://www.notifuse.com/pt/docs/features/admins-api-keys.md).

Dois limites valem para uma chave com escopo tão restrito, na ponte SMTP como na API:

- **Sem escrita de Contatos**, um envio ainda cria o contato do destinatário quando ele não existe, mas só o endereço de email é salvo. Todos os outros campos do objeto `contact` são descartados, e um contato existente nunca é alterado.
- **Sem leitura de Contatos**, um envio que define `cc` ou `bcc` é recusado. Na ponte SMTP, `cc` e `bcc` vêm dos cabeçalhos `Cc:` e `Bcc:` da mensagem, então uma credencial só de envio que os define é rejeitada no momento em que a mensagem é entregue ao servidor.

Adicione a leitura e a escrita de Contatos à chave se ela precisar enriquecer os perfis dos contatos ao enviar ou copiar destinatários extras. Com as duas, a chave se comporta como antes.

A escrita de Transacional cobre todos os caminhos que enviam emails reais pelas credenciais do seu provedor: `/api/transactional.send`, `/api/transactional.testTemplate` e a ponte SMTP. Testar um provedor de email (`/api/email.testProvider`) é reservado ao proprietário do workspace, então uma chave API não pode fazer essa chamada. Um email de teste também precisa da leitura de Templates, e da leitura de Listas quando é enviado para uma lista de emails (`list_id`).

A **leitura** de Transacional cobre só as definições das notificações (listar as notificações e abrir uma delas). Ela não permite que uma chave envie.

## Integração com templates

### Estrutura de dados nos templates

Os seus templates podem usar os dados da API e o perfil do contato:

```liquid
<!-- From API data -->
Hello! Your order #{{ order_id }} has been confirmed.

<!-- From contact profile (automatically enriched) -->
Dear {{ contact.first_name }} {{ contact.last_name }},

<!-- Combining both -->
We've sent your order #{{ order_id }} to {{ contact.email }}.
```

### Blocos condicionais

Os blocos de um template visual podem ser enviados só quando uma condição sobre esses dados vale, por exemplo uma seção exibida só quando `order.total` é maior que 100. Veja [Blocos condicionais](https://www.notifuse.com/pt/docs/features/templates.md#conditional-blocks).

### Exemplo completo

**Requisição da API**:

```json
{
  "workspace_id": "your_workspace",
  "notification": {
    "id": "order_confirmation",
    "external_id": "order-12345-confirmation",
    "contact": {
      "email": "sarah@example.com"
    },
    "data": {
      "order_id": "ORD-12345",
      "total": "$99.99",
      "items": ["Product A", "Product B"]
    },
    "metadata": {
      "campaign_id": "order-confirmations",
      "source": "checkout"
    }
  }
}
```

**Perfil de contato existente**:

```json
{
  "first_name": "Sarah",
  "last_name": "Johnson",
  "email": "sarah@example.com",
  "phone": "+1234567890"
}
```

**Disponível no template**:

```liquid
Hi {{ contact.first_name }}!

Your order #{{ order_id }} totaling {{ total }} has been confirmed.

Items:
{% for item in items %}
- {{ item }}
{% endfor %}

We'll send updates to {{ contact.email }}.
```

## Referência da API

## Exemplos de deduplicação

### Confirmações de pedido

```json
{
  "external_id": "order-12345-confirmation"
}
```

### Redefinições de senha

```json
{
  "external_id": "pwd-reset-user123-20240101"
}
```

### Emails de boas-vindas

```json
{
  "external_id": "welcome-user123"
}
```

Padrões consistentes de `external_id` evitam notificações duplicadas, mesmo que a sua aplicação envie várias requisições.

Para a documentação completa da API e os parâmetros adicionais, veja a [Referência da API](https://www.notifuse.com/docs/api-reference/send-a-transactional-notification.md).
