# 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](/pt/docs/templates/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 API → Logs**, origem API | **Email API → Logs**, 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 API → Emails** 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](/pt/docs/templates/).
- **Novas tentativas seguras.** Envie uma `Idempotency-Key` em cada requisição e tente de novo em caso de erro de rede sem enviar duas vezes. Consulte [Idempotência](/pt/docs/email-api/idempotency/).
- **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](/pt/docs/email-api/scheduling/).
- **Correlação.** Anexe os seus próprios IDs em `meta` e associe os eventos de webhook aos seus registros. Consulte [Cabeçalhos e metadados](/pt/docs/email-api/headers-and-metadata/).
- **Erros claros.** Um `422` para um domínio não verificado ou um `402` por 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-ID` pelo próprio e remove o cabeçalho `Reply-To` quando ele é igual ao `From`.
- Sempre use TLS. A porta 587 com STARTTLS é a recomendada, e a 465 usa TLS desde o primeiro byte. Consulte [Configurações SMTP](/pt/docs/smtp/settings/).

## 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](/pt/docs/developers/api-keys/).

## Próximos passos

  - [Guia rápido da API](/pt/docs/quickstart/api/): Envie o seu primeiro e-mail com cURL ou um SDK.
  - [Guia rápido de SMTP](/pt/docs/quickstart/smtp/): Teste o relay com swaks, OpenSSL ou Python.
  - [Enviar um e-mail](/pt/docs/email-api/send-email/): Todas as opções do endpoint de envio.
  - [Configurações SMTP](/pt/docs/smtp/settings/): Hosts, portas, TLS e códigos de resposta.

---
Fonte: https://emailit.com/pt/docs/get-started/api-or-smtp/