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

• Módulo E-mail ativo, com domínio de envio verificado e remetente completo: veja Configurar o domínio de envio de e-mail.
• Um modelo da categoria Resposta a um pedido do contato, já publicado: veja Criar um modelo de e-mail no editor. A API só envia modelos transacionais.
• Token de API com a permissão E-mails transacionais: veja Gerar tokens de API para integrações. Marque Escrita para enviar e Leitura para listar os modelos pela API. Token com Acesso total não inclui e-mail: edite o token e marque E-mails.

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

• O que a API v3 faz e como começar
• Criar um modelo de e-mail no editor
• Descadastro e lista de endereços bloqueados
• Gerar tokens de API para integrações