O que Integração de E-mail com Mailtrap faz?
Padrões para adicionar envio de e-mails transacionais a uma aplicação usando a API de E-mail e o Sandbox do Mailtrap, abordando autenticação, separação de ambientes e armadilhas comuns de entrega.
Quando Ativar
- Implementando um recurso de "enviar e-mail" (confirmação de cadastro, redefinição de senha, notificações, recibos)
- Depurando por que e-mails não estão chegando em dev/staging
- Configurando a primeira integração de envio de e-mail de um projeto
- Revisando código que chama uma API de e-mail diretamente sem separação de sandbox
Conceitos Principais
Separação Sandbox vs. Produção. O Mailtrap fornece uma API Sandbox que captura e-mails sem entregá-los, usada em dev/staging para que e-mails de teste nunca cheguem a caixas de entrada reais. O envio em produção usa um endpoint separado com domínio verificado. Nunca aponte um ambiente de desenvolvimento para o endpoint de envio de produção.
Autenticação. As requisições usam um token Bearer no cabeçalho Authorization. Os tokens têm escopo por projeto; sandbox e produção geralmente usam tokens diferentes.
Verificação de domínio. O envio em produção requer a verificação de um domínio remetente por meio de registros DNS (SPF, DKIM, DMARC) antes que o Mailtrap entregue a destinatários reais. Pular isso causa falhas silenciosas de entrega ou colocação na pasta de spam.
Exemplos de Código
// Envio via API de E-mail do Mailtrap (produção)
async function sendEmail(to: string, subject: string, html: string) {
const response = await fetch("https://send.api.mailtrap.io/api/send", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.MAILTRAP_API_TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
from: { email: "[email protected]", name: "Your App" },
to: [{ email: to }],
subject,
html,
}),
});
if (!response.ok) {
throw new Error(`Falha no envio do e-mail: ${response.status}`);
}
return response.json();
}
// Mesma chamada, roteada para o Sandbox em ambientes não produtivos
const MAILTRAP_ENDPOINT = process.env.NODE_ENV === "production"
? "https://send.api.mailtrap.io/api/send"
: `https://sandbox.api.mailtrap.io/api/send/${process.env.MAILTRAP_INBOX_ID}`;
Anti-Padrões
| Anti-Padrão | Por Que é um Problema | Em Vez Disso |
|---|---|---|
| Usar o endpoint de produção em dev/teste | E-mails de teste reais chegam a caixas de entrada reais, arriscando reclamações de spam e vazamento de dados de teste | Roteie ambientes não produtivos para o endpoint Sandbox |
| Hardcodar tokens de API no código fonte | Risco de vazamento de credenciais se for commitado no controle de versão | Carregue tokens de variáveis de ambiente / gerenciador de segredos |
| Enviar antes da verificação do domínio ser concluída | E-mails falham silenciosamente ou vão para spam | Verifique os registros SPF/DKIM/DMARC antes de habilitar o envio em produção |
| Sem tratamento de retry/erro em falhas de envio | Falhas silenciosas de notificação (ex.: usuário nunca recebe e-mail de redefinição de senha) | Verifique o status da resposta, registre falhas, exiba erros acionáveis |
Práticas Recomendadas
- Mantenha tokens de sandbox e produção em variáveis de ambiente separadas; nunca compartilhe um token entre ambientes
- Verifique os registros DNS do domínio remetente antes de qualquer lançamento em produção que envolva e-mail
- Registre falhas de entrega com contexto suficiente para depuração (destinatário, template, timestamp, código de resposta)
- Trate o envio de e-mail como uma chamada de rede sujeita a falhas: envolva em try/catch, nunca assuma sucesso
Skills Relacionadas
api-and-interface-design, security-and-hardening, ci-cd-and-automation