Migrar do Mailgun

Este guia mostra a correspondência entre os conceitos, as chamadas à API, os webhooks, as supressões e os templates do Mailgun e os equivalentes no Emailit. Leia antes Migrar para o Emailit para conhecer a ordem geral e saber como usar os dois provedores em paralelo.

Conceitos

Atualizar as chamadas à API

O POST /v3/<domain>/messages do Mailgun recebe campos de formulário com autenticação básica. O POST /v2/emails do Emailit recebe JSON com um bearer token:

curl -s --user "api:$MAILGUN_API_KEY" \
  https://api.mailgun.net/v3/mg.acme.com/messages \
  -F from='Acme <hello@mg.acme.com>' \
  -F to='ada@example.com' \
  -F subject='Your receipt' \
  -F text='Thanks for your order.' \
  --form-string html='<p>Thanks for your order.</p>'

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@mg.acme.com>",
    "to": "ada@example.com",
    "subject": "Your receipt",
    "text": "Thanks for your order.",
    "html": "<p>Thanks for your order.</p>"
  }'

Se você enviava de um subdomínio como mg.acme.com, adicione exatamente esse subdomínio no Emailit. Os subdomínios são verificados separadamente do domínio pai. Os hosts de API do Mailgun na UE e nos EUA correspondem ao único endpoint do Emailit. Consulte Enviar um e-mail.

Mudar as configurações SMTP

O Emailit não lê os cabeçalhos X-Mailgun-*. Remova-os e configure o rastreamento no domínio. Consulte Configurações SMTP.

Correspondência dos eventos de webhook

O formato da requisição muda:

• O Mailgun envia um evento por requisição, com os detalhes em event-data. O Emailit envia um array JSON de até 100 eventos. Percorra o array em um loop.
• O nome do evento fica em type, e o e-mail fica em data.object. Use data.object.id, o ID em_ da resposta do envio, para associar os eventos às mensagens. Os seus valores de meta ficam em data.object.meta.
• O Mailgun assina um timestamp e um token dentro do corpo. O Emailit assina o corpo bruto inteiro: verifique X-Emailit-Signature com X-Emailit-Timestamp e o seu segredo whsec_. Consulte Assinatura das requisições.

for (const event of req.body) {
  const email = event.data.object;
  if (event.type === 'email.bounced') markBounced(email.to, email.id);
  if (event.type === 'email.complained') unsubscribe(email.to);
}

Migrar as supressões

1. Exporte as listas Bounces, Complaints e Unsubscribes de cada domínio do Mailgun de onde você envia, pelo painel de controle ou pela API de supressões (/v3/<domain>/bounces, /complaints e /unsubscribes).

2. Monte um único CSV com as colunas email,type,reason:

   CSV

   email,type,reason
   old-address@example.com,recipient,mailgun bounce
   angry@example.com,recipient,mailgun complaint

   Use o tipo recipient para endereços que nunca devem receber e-mails. Ele bloqueia envios pela API, por SMTP e de campanhas. Os tipos bounce, complaint e unsubscribe só bloqueiam campanhas.

3. Em Email API›Suppressions, selecione Import e envie o arquivo. Cada arquivo pode ter até 10.000 linhas e no máximo 8 MB. Os duplicados são ignorados.

O Emailit tem uma lista de supressão por workspace, então os endereços de todos os seus domínios do Mailgun vão para a mesma lista. Não há lista de permissão (allowlist). Consulte Gerenciar supressões.

Migrar os templates

Copie o HTML de cada template do Mailgun e depois importe-o em Email Marketing›Templates ou crie-o com a API de templates. Dê a ele um alias e envie-o com "template": "<alias>" e variables.

Os templates do Mailgun usam Handlebars. O Temple cobre as partes mais comuns:

Consulte Temple e Importar e exportar templates.

Alterar o DNS

Adicione cada domínio em Email API›Domains e publique os registros do Emailit. Eles usam nomes próprios (emailit._domainkey, emailit.<domain> e, opcionalmente, go e inbound), então não entram em conflito com o registro DKIM do Mailgun nem com o CNAME de rastreamento email.<domain> dele. Você não precisa alterar o registro SPF do domínio raiz por causa do Emailit. Mantenha o seu registro DMARC. Consulte Registros DNS.

Depois da virada, remova os registros DKIM e de rastreamento do Mailgun e remova include:mailgun.org do seu registro SPF. Se você recebe e-mails pelas routes do Mailgun, mantenha os registros MX dele até ter levado esse tráfego para o recebimento de e-mails do Emailit, que recebe em um subdomínio como inbound.acme.com.

Próximos passos

• Checklist para entrar em produção
• Configurar webhooks
• Migração prioritária: deixe os engenheiros do Emailit fazerem a migração com você