Guia
Escolher entre a API e o SMTP
Compare a API REST do Emailit com o SMTP relay recurso por recurso, de templates e agendamento a idempotência e webhooks, e escolha a opção certa.
O Emailit aceita e-mails transacionais de duas formas: pela API REST e pelo SMTP relay. Este guia compara as duas para que você escolha uma ou use ambas no mesmo workspace.
A resposta curta
- Use a API em código novo. Ela faz mais: templates, agendamento, novas tentativas idempotentes, metadados, configurações de rastreamento por e-mail e uma resposta JSON com um ID para cada destinatário.
- Use o SMTP quando o software que você usa já tem configurações SMTP, como um CMS, o mailer de um framework, um help desk, um dispositivo ou uma aplicação legada. Você altera quatro configurações e pronto.
As duas usam as mesmas chaves de API, domínios verificados, lista de supressão, limites de envio, logs e webhooks. Você pode trocar depois sem mexer no DNS.
Comparação de recursos
| Recurso | API REST | SMTP relay |
|---|---|---|
| Endpoint | POST https://api.emailit.com/v2/emails |
smtp.emailit.com, portas 587, 465, 2525, 2587 e 25 |
| Autenticação | Authorization: Bearer secret_… |
AUTH PLAIN ou LOGIN, usuário emailit, senha = chave de API |
| Conteúdo | html, text ou um template armazenado |
Uma mensagem MIME completa, enviada como está |
| Templates e variáveis | template (ID ou alias) mais variables, renderizados com o Temple |
Não disponível. Renderize a mensagem antes de enviá-la. |
| Agendamento | scheduled_at com ISO 8601, um timestamp Unix ou inglês simples, como tomorrow at 9am |
Não disponível. O e-mail entra na fila imediatamente. |
| Anexos | content em Base64 ou uma url que o Emailit baixa (até 25 MB cada). content_id torna uma imagem inline. |
Partes MIME padrão |
| Tamanho da mensagem | 40 MB | 40 MB |
| Destinatários por mensagem | Até 50 em cada um de to, cc e bcc |
Sem limite fixo por transação |
| Idempotência | Cabeçalho Idempotency-Key, reaproveitado por 24 horas |
Não disponível. Uma transação repetida pode enviar duas vezes. |
| Metadados | Objeto meta, retornado nos payloads de webhook |
Não disponível |
| Cabeçalhos personalizados | Objeto headers |
Qualquer cabeçalho na mensagem |
| Rastreamento de aberturas e cliques | Por e-mail com tracking, ou o padrão do domínio |
Apenas o padrão do domínio |
Webhooks email.accepted e email.scheduled |
Sim | Não. Os eventos posteriores, como email.delivered e email.bounced, funcionam da mesma forma. |
| IDs de e-mail | A resposta tem id e ids, com um ID por destinatário |
Resposta final 250 2.0.0 OK: queued as em_… |
| Erros | Códigos de status HTTP com um corpo JSON | Códigos de resposta SMTP, por exemplo 535 ou 550 |
| Limites de envio | Compartilhados por workspace. 429 com os cabeçalhos ratelimit-* e retry-after. |
Compartilhados por workspace. Respostas 452. |
| Créditos | 1 por destinatário | 1 por destinatário |
| Log de requisições | Email APILogs, origem API | Email APILogs, origem SMTP |
Depois que um e-mail é aceito, os dois canais se comportam da mesma forma. Cada destinatário recebe um ID em_, aparece em Email APIEmails e pode ser cancelado, tentado de novo ou encaminhado pelo painel ou pela API.
Quando usar a API
Escolha a API quando você mesmo escreve o código de envio, principalmente se precisar de algum destes recursos:
- Templates. Os designers editam um template no painel e o seu código o envia pelo alias com
variables. Consulte Templates. - Novas tentativas seguras. Envie uma
Idempotency-Keyem cada requisição e tente de novo em caso de erro de rede sem enviar duas vezes. Consulte Idempotência. - Agendamento. Envie um lembrete para amanhã de manhã sem a sua própria fila de jobs, e reagende-o ou cancele-o até 3 minutos antes do envio. Consulte Agendamento.
- Correlação. Anexe os seus próprios IDs em
metae associe os eventos de webhook aos seus registros. Consulte Cabeçalhos e metadados. - Erros claros. Um
422para um domínio não verificado ou um402por falta de créditos é mais fácil de tratar do que uma string de resposta SMTP.
Quando usar o SMTP
Escolha o SMTP quando você não pode ou não quer alterar código:
- Softwares prontos, como o WordPress, um help desk ou uma ferramenta de monitoramento com uma página de configurações SMTP.
- Mailers de frameworks que já funcionam por SMTP, como Laravel, Rails, Django ou Nodemailer. Você pode passar para a API depois.
- Migrações rápidas de outro provedor. Troque o host, a porta, o usuário e a senha e teste.
- Dispositivos e scripts que só falam SMTP, como impressoras, scanners ou jobs de cron.
O que saber antes de depender do SMTP:
- O Emailit não lê cabeçalhos específicos de outros provedores pelo SMTP. O rastreamento segue as configurações Track loads e Track clicks do domínio de envio.
- O Emailit substitui o seu cabeçalho
Message-IDpelo próprio e remove o cabeçalhoReply-Toquando ele é igual aoFrom. - Sempre use TLS. A porta 587 com STARTTLS é a recomendada, e a 465 usa TLS desde o primeiro byte. Consulte Configurações SMTP.
Usar as duas
Muitas equipes usam as duas: a API para os e-mails da aplicação e o SMTP para um CMS ou ferramentas internas. Use uma chave de API separada para cada uma, para distingui-las nos logs e regenerar uma sem quebrar a outra. Uma chave Sending Only restrita a um domínio é uma boa escolha para credenciais SMTP guardadas em softwares de terceiros. Consulte Chaves de API.