Tovanix
Tovanix

API de envio de e-mail

Envie pelo seu domínio no servidor, compartilhando a mesma cota, cobrança e limites do envio de e-mail no console. O domínio remetente deve corresponder exatamente a um domínio de envio conectado e ativo.

  • Autenticação: a mesma chave de API do usuário utilizada pelas demais APIs abertas da plataforma
  • Envio: POST /api/v1/mail/send; a resposta é agrupada por destinatário, e bounced_addrs é a única base para limpar sua lista
  • Idempotência: com o cabeçalho Idempotency-Key, envios repetidos com a mesma chave enviam exatamente uma vez — sem entregas ou cobranças duplicadas
  • Conversas: informe in_reply_to e a cadeia completa de references para que as respostas entrem na conversa original do destinatário
  • Cota e domínios: consulte a cota restante de hoje e os domínios de envio utilizáveis para limitar a velocidade no seu sistema
  • Exemplos de código: exemplos mínimos funcionais em cURL / Node.js / Python / Go / PHP, todos com idempotência e tratamento de devoluções permanentes

POST / GET /api/v1/mail/*

Visão geral

Envie pelo servidor usando seus próprios domínios. A cota, a cobrança e os limites são exatamente os mesmos do console — não há um segundo conjunto de regras.

Ative o envio de e-mails no console e adicione pelo menos um domínio com status Ativo. Envios de um domínio que não esteja ativo serão rejeitados.

Autenticação

Usa a mesma chave de API da conta que o restante da plataforma. Crie uma em Ferramentas e configurações → Gerenciamento de API.

Console → Ferramentas e configurações → Gerenciamento de API → Criar chave. A mesma chave funciona nas APIs de energia, cartões virtuais, e-mail e câmbio; os endpoints disponíveis dependem dos recursos concedidos à chave.

Enviar e-mail

POST /api/v1/mail/send

O domínio de From deve corresponder exatamente a um domínio de envio adicionado e ativo.

Limites de envio

  • to + cc + bcc devem somar no máximo 50 destinatários
  • 5 MiB por mensagem, incluindo anexos (medidos após a decodificação)
  • 998 caracteres (contados como caracteres, não bytes — assuntos com caracteres não ASCII não são afetados)
  • Até 32 anexos; anexos incorporados devem incluir um content_id
  • 16 KB no total de cabeçalhos personalizados, com 2048 bytes por valor de cabeçalho

Resposta

Os resultados são agrupados por destinatário, em vez de um único indicador geral de sucesso.

Uma mensagem enviada a cinco pessoas pode resultar em 2 entregas, 1 envio na fila e 2 rejeições definitivas. bounced_addrs é sua única fonte para manter a lista limpa — não há webhook de rejeição. Se você descartar esse campo, perderá a informação e continuará enviando para um endereço inválido e pagando por isso.

Idempotência

Com o cabeçalho Idempotency-Key, reenviar a mesma chave realiza o envio apenas uma vez.

Sempre que sua chamada puder ser repetida automaticamente — por timeout, filas de tarefas ou novas tentativas do SDK. Sem isso, uma falha de rede pode fazer o destinatário receber duas cópias e gerar duas cobranças, sem possibilidade de desfazer nenhuma delas. Use uma chave de negócio, como o número do pedido.

Encadeamento de mensagens

Inclua in_reply_to e references ao responder para que a mensagem entre na conversa original; sem eles, cada resposta inicia uma nova conversa na caixa de entrada do destinatário. Envie a cadeia completa de references — usando apenas in_reply_to, alguns clientes dividem conversas com mais de duas mensagens.

Cota e domínios

Consulte o volume diário restante e os domínios de envio disponíveis para limitar a taxa do seu lado.

Exemplos de código

Exemplos mínimos funcionais por linguagem, todos com tratamento de idempotência e rejeições definitivas.

Enviar e-mails gera cobrança. Novas chaves de API exigem requisições assinadas para endpoints com cobrança por padrão; por isso, todos os exemplos abaixo usam assinatura versão 2 (envie o cabeçalho X-Sign-Version: 2). O texto a assinar contém 7 linhas unidas por \n, sem quebra de linha final: NEXCORE-HMAC-SHA256-V2, timestamp, nonce, método em maiúsculas, caminho, query string e SHA-256 do corpo em hexadecimal minúsculo. X-Signature é HMAC-SHA256(Secret Key, texto a assinar) em hexadecimal minúsculo. timestamp usa segundos Unix, nonce tem no máximo 64 bytes, a query string não tem "?" inicial e deve corresponder exatamente ao que é enviado (linha vazia se não houver), e o hash do corpo é calculado sobre os bytes exatos enviados. Se você desativar "Exigir requisições assinadas para cobranças e dados sensíveis" nas configurações da chave, somente X-API-Key + X-Secret-Key também funciona, mas não é recomendado.

Perguntas frequentes

HTTP 200 significa que todos os destinatários receberam o e-mail?

Não. Os resultados são agrupados por destinatário: uma mensagem para cinco pessoas pode ter 2 entregas, 1 envio na fila e 2 devoluções permanentes. Não há webhook de devolução; por isso, bounced_addrs é a única base para manter sua lista limpa — pare de enviar para esses endereços imediatamente.

Quando Idempotency-Key é necessário?

Sempre que sua chamada puder repetir automaticamente — novas tentativas por tempo limite, reentrega de filas de tarefas ou novas tentativas do SDK. Sem ele, uma falha de rede pode fazer o destinatário receber dois e-mails e você ser cobrado duas vezes, sem possibilidade de reversão. Use uma chave de negócio, como o ID do pedido.

Páginas relacionadas: Documentação da API · API de agregação SMTP · Usar a API de agregação SMTP

Carregando…