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
contactda 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 emcontact.
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).
Enriquecimento dos dados do template
Quando você envia um email transacional, o Notifuse:
- Cria ou atualiza o contato e depois o busca pelo endereço de email no seu workspace
- Coloca as chaves de
datano primeiro nível das variáveis do template, e o perfil salvo do contato emcontact - Renderiza o template com as informações completas do contato
- 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_idpara não enviar a mesma notificação duas vezes: as notificações com o mesmoexternal_idsã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 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 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
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:
{
"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:
{
"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
{
"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
{
"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:...">:
{
"email_options": {
"attachments": [
{
"filename": "check-in-qr.png",
"content": "iVBORw0KGgoAAAANSUhEU...",
"content_type": "image/png",
"disposition": "inline",
"content_id": "checkInQr"
}
]
}
}
E no template do email:
<img src="cid:checkInQr" alt="Your check-in QR code" />
Observações:
content_idsó pode conter letras, dígitos e os caracteres._-@(máximo de 255 caracteres), e só é aceito quandodispositioné"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/relatedjunto 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_idtambém vira o nome do arquivo da parte entregue, então prefira umcontent_idcom 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:
{
"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.
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
contactsão descartados, e um contato existente nunca é alterado. - Sem leitura de Contatos, um envio que define
ccoubccé recusado. Na ponte SMTP,ccebccvêm dos cabeçalhosCc:eBcc: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:
<!-- 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.
Exemplo completo
Requisição da API:
{
"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:
{
"first_name": "Sarah",
"last_name": "Johnson",
"email": "sarah@example.com",
"phone": "+1234567890"
}
Disponível no template:
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
{
"external_id": "order-12345-confirmation"
}
Redefinições de senha
{
"external_id": "pwd-reset-user123-20240101"
}
Emails de boas-vindas
{
"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.
