O que Integração de Email com Mailtrap faz?
Padrões para adicionar envio de email transacional a uma aplicação usando a API de Email e o Sandbox do Mailtrap, cobrindo autenticação, separação de ambientes e armadilhas comuns de entrega.
Quando Ativar
- Implementação de um recurso de "enviar email" (confirmação de cadastro, redefinição de senha, notificações, recibos)
- Depuração de por que emails não estão chegando em desenvolvimento/homologação
- Configuração da primeira integração de envio de email de um projeto
- Revisão de código que chama uma API de email diretamente sem separação de sandbox
Conceitos Centrais
Separação Sandbox vs. Produção. O Mailtrap fornece uma API Sandbox que captura emails sem entregá-los, usada em desenvolvimento/homologação para que emails 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 em spam.
Exemplos de Código
// Envio via API de Email 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: "Seu App" },
to: [{ email: to }],
subject,
html,
}),
});
if (!response.ok) {
throw new Error(`Falha no envio do email: ${response.status}`);
}
return response.json();
}
// Mesma chamada, roteada para 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 envio de produção em desenvolvimento/teste | Emails 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 |
| Codificar tokens de API no código fonte | Risco de vazamento de credenciais se for enviado ao 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 | Emails falham silenciosamente ou vão para spam | Verifique 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 email de redefinição de senha) | Verifique o status da resposta, registre falhas, exiba erros acionáveis |
Melhores Práticas
- 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 email
- Registre falhas de entrega com contexto suficiente para depuração (destinatário, template, timestamp, código de resposta)
- Trate o envio de email como uma chamada de rede sujeita a falhas: envolva em try/catch, nunca presuma sucesso
Skills Relacionadas
api-and-interface-design, security-and-hardening, ci-cd-and-automation