Tovanix
Tovanix

API de e-mail SMTP

Uma API de envio de e-mails transacionais — verificação de cadastro, notificações de pedidos e redefinição de senha — disponível por SMTP padrão e API HTTP.

  • Duas formas de acesso: mantenha seu cliente SMTP existente sem alterações no código ou use a API HTTP para obter confirmações mais detalhadas
  • Modelos: gerencie os modelos de forma centralizada e envie apenas as variáveis no momento do envio
  • Envio em lote: vários destinatários por solicitação, cada um com sua própria confirmação
  • Webhooks de entrega e devolução: eventos de entrega / devolução / reclamação em tempo real para proteger a reputação do remetente

POST / GET /api/v1/smtp/*

Visão geral

A API de agregação SMTP oferece envio de e-mails. Adicione suas contas SMTP e envie por uma API unificada. Suporta rotação inteligente entre contas, alternativas automáticas em falhas e gestão de cotas.

Comprar assinatura → Adicionar contas SMTP → Criar chave de API → Chamar API de envio

Autenticação

A API SMTP usa chaves próprias do módulo (prefixo smk_), com dois métodos:

Entre no console do usuário → API de agregação SMTP → Gerenciamento de chaves. Salve imediatamente após criar; a chave completa não aparece após fechar.

Enviar e-mail

POST /api/v1/smtp/send

Envie um e-mail. O sistema escolhe a melhor conta SMTP (por prioridade, uso e saúde).

Campos da resposta

Envie Idempotency-Key para repetir com segurança: o primeiro sucesso fica em cache, e requisições com a mesma chave retornam o original, sem reenviar ou consumir cota duas vezes.

Resposta de envio agendado

Com send_at futuro, cria tarefa agendada em vez de enviar agora e retorna a estrutura abaixo (cota cobrada no envio real):

Retorna code: 429 ao exceder limite diário ou mensal. Amplie o plano ou aguarde o reinício.

Envio em lote

POST /api/v1/smtp/send/batch

Campos da resposta

Limite de destinatários por requisição = max_batch_size do plano (padrão 10); exceder falha imediatamente. A cota diária/mensal é cobrada por mensagem, não por requisição; destinatários que cancelaram inscrição são marcados como falha. Lotes grandes demoram e a solicitação pode expirar antes de responder: envie o cabeçalho Idempotency-Key; ao repetir com o mesmo valor você recebe o primeiro resultado em vez de reenviar o lote inteiro.

Envio por modelo

POST /api/v1/smtp/send/template

Campos da resposta

Envio por modelo suporta idempotência durável: adicione Idempotency-Key: <unique-string> aos cabeçalhos. A intenção é persistida por (usuário + API Key + chave) e resiste a reinício ou perda de Redis. Regras: (1) mesma chave e corpo retornam o resultado original, sem reenviar ou consumir cota; (2) mesma chave e corpo diferente retornam 409 — use nova chave; (3) primeira requisição ainda pendente: nova tentativa retorna 409 — tente depois com a mesma chave; (4) intenção falha não pode ser reaberta e retorna 409 — recomece com nova chave. Sem cabeçalho, não há idempotência (envio comum).

Consultar cota

GET /api/v1/smtp/quota

Consulte a cota restante da assinatura atual.

Consultar status de envio

GET /api/v1/smtp/status/:message_id

Consulte pelo message_id retornado pela API de envio.

Relatório de falha de entrega/reclamação

POST /api/v1/smtp/inbound

Informe falha de entrega ou reclamação: o endereço entra automaticamente na supressão e o registro é marcado; envios futuros o ignoram para proteger a reputação. Informe pelo menos email ou message_id.

Perguntas frequentes

Já usamos SMTP — precisamos reescrever alguma coisa?

Não. Configure seu cliente SMTP existente com o host, a porta e as credenciais fornecidas pela Tovanix e pronto. Use a API HTTP apenas quando precisar de confirmações de entrega e devolução mais detalhadas.

Como devo tratar devoluções e reclamações?

Ambas são enviadas em tempo real por webhooks. Adicione o endereço à lista de supressão e interrompa os envios imediatamente — isso ajuda a impedir que seu domínio de envio vá para as pastas de spam.

Páginas relacionadas: API de agregação SMTP · Documentação da API · Verificação por SMS

Carregando…