Skip to main content

Enviar um e-mail transacional pela API

Envie um e-mail avulso (código de verificação, confirmação de pedido, aviso de troca de senha) a partir do seu sistema ou do n8n, usando um modelo de e-mail do AtendeBot. Esta receita mostra como pegar o ID do modelo e disparar o envio pela API v3.

🧩 Este recurso faz parte do módulo E-mail. Se ele não aparecer na sua conta, fale com o administrador para ativá-lo. Veja Planos e módulos.

Objetivo

Enviar um e-mail transacional a um destinatário, pela API, a partir de um modelo publicado.

Pré-requisitos

Tempo estimado

10 minutos.

Caminho de acesso

Ajustes → E-mail → Modelos, menu de três pontos do modelo, Usar pela API. O envio em si é uma chamada direta à API.

Passo a passo

  1. Em Ajustes → E-mail → Modelos, abra o menu de três pontos de um modelo transacional publicado e clique em Usar pela API. A janela mostra o ID do modelo (com botão de copiar), as variáveis divididas em Preenchidas pelo contato e Envie em template_data, e um exemplo de curl pronto.

  2. Envie o e-mail:

    curl -X POST https://api.atende.bot/public/v3/emails \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f14e45f-0b6c-4a1e-9d3a-2c5e7b1a9f00" \
  -d '{
    "template": "TEMPLATE_ID",
    "to": "cliente@exemplo.com",
    "template_data": { "codigo": "482913" }
  }'
    • template: o ID copiado no passo 1.
    • to: o endereço de destino. Em vez dele (ou junto), contact aceita o ID do contato ou phone:+5511999998888 (com código do país).
    • template_data: um objeto com chave e texto, uma chave para cada variável da lista Envie em template_data.

  3. No n8n, use o nó HTTP Request (método POST, a mesma URL, autenticação por header Authorization: Bearer) com esse corpo JSON, montando to e template_data a partir dos dados do fluxo.

  4. Para descobrir os modelos pela API em vez de copiar o ID na tela, chame GET https://api.atende.bot/public/v3/emails/templates (permissão Leitura em E-mails). Cada item traz id, name, category, sendable (só true pode ser enviado), variables (todas as chaves que o modelo publicado usa) e contact_variables (as que o AtendeBot preenche sozinho). Modelos arquivados não aparecem.

  5. Mande sempre o header Idempotency-Key (um UUID por envio): se o fluxo repetir a chamada com a mesma chave, a resposta é a mesma e nenhum segundo e-mail sai.

Onde o envio aparece

O e-mail enviado pela API fica no histórico do contato (aba E-mails e linha do tempo) com a origem API · nome do token, para você saber qual integração o disparou. Se o token for excluído depois, a origem passa a ser só API.

Como as variáveis são preenchidas

  • Variáveis do contato (nome, primeiro nome, empresa, telefone, saudação e e-mail) são preenchidas sozinhas quando o e-mail vai para o próprio contato: sem to, ou com to igual ao e-mail do contato.
  • Qualquer outra variável, criada no editor em Variável → Outra variável..., precisa vir em template_data.
  • Variável sem valor e sem Se estiver vazio, usar faz a API responder 400 listando o que falta. Nada é enviado em branco.
  • Na prévia e em Enviar teste, as variáveis personalizadas aparecem como [chave].

Resultado esperado

201 com o e-mail enviado. Em alguns casos a API responde 200 com status suppressed ou failed e um error.code: RECIPIENT_SUPPRESSED, PROVIDER_REJECTED, DELIVERY_UNCERTAIN, ENVIRONMENT_BLOCKED, RENDER_FAILED ou SEND_FAILED. A lista completa de erros (400, 403, 404, 413, 422, 429, 502) está em https://api.atende.bot/public/v3/docs.

Limites e cota

  • No máximo 5 e-mails a cada 10 minutos para o mesmo endereço e 60 por minuto por conta, além do limite diário do aquecimento do domínio. Acima disso a API responde 429 com o header Retry-After.
  • O envio consome a cota de e-mails como qualquer outro (créditos depois da cota do plano). Reservas de campanha não bloqueiam o transacional: veja Cota mensal de e-mails e créditos.
  • Em Ajustes → Registros ficam as chaves de template_data, mas os valores são ocultados.
  • Regras de bloqueio: veja Descadastro e lista de endereços bloqueados.

Erros comuns

  • Sintoma: 403. Solução: o token não tem E-mails transacionais (Escrita para enviar, Leitura para listar modelos). Edite o token e marque E-mails, mesmo que ele seja Acesso total.
  • Sintoma: 404 no modelo. Solução: confira o ID e se o modelo está publicado e é da categoria Resposta a um pedido do contato.
  • Sintoma: 400 listando variáveis. Solução: envie as chaves faltantes em template_data ou defina Se estiver vazio, usar no editor.
  • Sintoma: 200 com RECIPIENT_SUPPRESSED. Solução: o endereço está bloqueado: veja Descadastro e lista de endereços bloqueados.

Artigos relacionados

No comments to display