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…