Integração de E-mail com Mailtrap

Padrões para adicionar envio de e-mail transacional a um aplicativo usando a API de E-mail e o Sandbox do Mailtrap, cobrindo 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 os e-mails não estão chegando em desenvolvimento/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 para desenvolvimento/staging para que e-mails de teste nunca cheguem a caixas de entrada reais. O envio em produção usa um endpoint separado e de 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 são escopados 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 de envio via registros DNS (SPF, DKIM, DMARC) antes que o Mailtrap entregue a destinatários reais. Pular isso causa falhas silenciosas na entrega ou colocação na pasta de spam.

Exemplos de Código

// Sending via Mailtrap's Email API (production)
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: "no-reply@yourverifieddomain.com", name: "Your App" },
      to: [{ email: to }],
      subject,
      html,
    }),
  });

  if (!response.ok) {
    throw new Error(`Email send failed: ${response.status}`);
  }
  return response.json();
}

// Same call, routed to Sandbox in non-production environments
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

Melhores Práticas

• Mantenha os 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 de envio antes de qualquer lançamento de produção envolvendo 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 falível: envolva em try/catch, nunca assuma sucesso

Habilidades Relacionadas

api-and-interface-design, security-and-hardening, ci-cd-and-automation