Pular para o conteúdo

Recursos

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

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

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 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âmetroTipoObrigatórioDescrição
workspace_idstringSimIdentificador do seu workspace
notification.idstringSimIdentificador do template do email
notification.external_idstringNãoIdentificador único para a deduplicação
notification.channelsarraySimPrecisa incluir “email”
notification.contactobjectSimObjeto do contato com pelo menos o campo email
notification.dataobjectNãoVariáveis do template para o conteúdo do email
notification.metadataobjectNãoDados de rastreamento (não disponíveis nos templates)
notification.email_optionsobjectNãoConfiguração de roteamento do email

Opções de email

ParâmetroTipoDescrição
sender_idstringEnvia 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_namestringSubstitui o nome de exibição padrão do remetente
subjectstringSubstitui a linha de assunto do template (aceita Liquid, máximo de 255)
reply_tostringDefine um endereço de resposta personalizado, no lugar do reply-to do template
ccarrayLista de destinatários em cópia
bccarrayLista de destinatários em cópia oculta
attachmentsarrayArquivos 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âmetroTipoObrigatórioDescrição
filenamestringSimNome do arquivo (máximo de 255 caracteres)
contentstringSimConteúdo do arquivo codificado em Base64
content_typestringNãoTipo MIME (por exemplo, “application/pdf”), detectado automaticamente se não for informado
dispositionstringNão“attachment” (padrão) ou “inline”
content_idstringNãoContent-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_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:

{
  "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 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:

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