# Migrar do Mailgun

> Migre do Mailgun para o Emailit. Faça a correspondência de domínios, chaves e routes, converta as chamadas à API com formulário para JSON e migre o SMTP, os webhooks, as supressões e os templates.

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](/pt/docs/migrate/) para conhecer a ordem geral e saber como usar os dois provedores em paralelo.

## Conceitos

| Mailgun | Emailit |
| --- | --- |
| Conta e subaccounts | Conta e [workspaces](/pt/docs/workspaces/). Cada workspace tem os seus próprios domínios, chaves, membros e créditos. |
| Domínio, com o seu próprio caminho de API `/v3/<domain>/…` | [Domínio de envio](/pt/docs/domains/). Há um único endpoint de envio, e o Emailit identifica o domínio pelo endereço `from`. |
| Private API key | [Chave de API](/pt/docs/developers/api-keys/) **Full Access** |
| Domain sending key | Chave de API **Sending Only** restrita a um domínio |
| Credenciais SMTP por domínio | A sua chave de API, usada como senha do SMTP |
| Templates por domínio, com versões | [Templates](/pt/docs/templates/) por workspace, com alias e versões |
| Webhooks por domínio | [Webhooks](/pt/docs/webhooks/) por workspace |
| Routes | [Recebimento de e-mails](/pt/docs/inbound/) com o webhook `email.received`, ou a [automação](/pt/docs/inbound/forward-with-automations/) **Forward received email** |
| Suppressions por domínio: bounces, unsubscribes, complaints | Uma [lista de supressão](/pt/docs/suppressions/) por workspace |
| Mailing lists | [Listas de contatos](/pt/docs/audiences/) |
| Tags e custom variables | `meta` |
| Logs e events | **Email API → Emails**, **Email API → Events** e **Email API → Logs** |
| Email validation | [Verificação de e-mails](/pt/docs/email-verification/) |

## 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:

```bash title="Antes: Mailgun"
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>'
```

```bash title="Depois: Emailit"
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>"
  }'
```

| Mailgun | Emailit |
| --- | --- |
| Autenticação básica `api:<key>` | `Authorization: Bearer secret_…` |
| Campos `multipart/form-data` | Um corpo JSON |
| `from`, `subject`, `text`, `html` | Os mesmos nomes |
| `to`, `cc`, `bcc` (repetidos ou separados por vírgula) | `to`, `cc`, `bcc` como string ou array de até 50 cada |
| `h:Reply-To` | `reply_to` |
| `h:X-My-Header` | `headers: { "X-My-Header": "…" }` |
| `v:order-id`, `h:X-Mailgun-Variables` | `meta: { "order-id": "…" }`, devolvido nos eventos de webhook |
| `template` e `t:variables` | `template` (um ID ou alias) e `variables` |
| `attachment`, `inline` (upload de arquivos) | `attachments[]` com `content` em base64 ou uma `url`, mais `content_type`. Adicione `content_id` para imagens inline. |
| `o:deliverytime` (data RFC 2822) | `scheduled_at` (ISO 8601, horário Unix ou inglês simples) |
| `o:tracking`, `o:tracking-opens`, `o:tracking-clicks` | `tracking: { "loads": true, "clicks": true }` |
| `o:tag` | `meta` |
| `o:testmode` | Não disponível |
| `recipient-variables` (envio em lote) | Não disponível. Envie uma requisição por destinatário, cada uma com as suas `variables`. |
| Resposta `{ "id": "<…>", "message": "Queued. Thank you." }` | `200` com `id` (`em_…`), `message_id`, `status: "accepted"` e `ids` por destinatário |

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](/pt/docs/email-api/send-email/).

## Mudar as configurações SMTP

| Configuração | Mailgun | Emailit |
| --- | --- | --- |
| Host | `smtp.mailgun.org`, ou o host da UE | `smtp.emailit.com` |
| Porta | `587`, `465`, `2525` ou `25` | `587` (STARTTLS), `465` (TLS), `2525`, `2587` ou `25` |
| Usuário | O seu login SMTP, como `postmaster@mg.acme.com` | `emailit` |
| Senha | A sua senha SMTP | A sua chave de API do Emailit |

O Emailit não lê os cabeçalhos `X-Mailgun-*`. Remova-os e configure o rastreamento no domínio. Consulte [Configurações SMTP](/pt/docs/smtp/settings/).

## Correspondência dos eventos de webhook

| Evento do Mailgun | Evento do Emailit |
| --- | --- |
| `accepted` | `email.accepted` (somente API) |
| `delivered` | `email.delivered` |
| `failed` com severidade `temporary` | `email.attempted` |
| `failed` com severidade `permanent` | `email.bounced` |
| `opened` | `email.loaded` |
| `clicked` | `email.clicked` |
| `complained` | `email.complained` |
| `unsubscribed` | `email.unsubscribed`, somente para e-mails de campanha |
| Route que encaminha para uma URL | `email.received`; depois, busque o conteúdo com [`GET /emails/{id}`](/pt/docs/api-reference/emails/get/) |

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](/pt/docs/webhooks/request-signature/).

```javascript
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](/pt/docs/suppressions/manage/).

## 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](/pt/docs/api-reference/templates/create/). 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:

| Mailgun (Handlebars) | Emailit (Temple) |
| --- | --- |
| `{{first_name}}` | `{{first_name}}` |
| `{{{html_block}}}` | `{{html_block}}`. O Temple nunca escapa HTML, então escape você mesmo o que vier dos usuários. |
| `{{#if plan}}…{{else}}…{{/if}}` | Igual |
| `{{#unless plan}}…{{/unless}}` | `{{#if plan}}{{else}}…{{/if}}` |
| `{{#each items}}…{{/each}}` | Não suportado. Renderize a lista no seu código e passe-a como uma única variável. |
| `{{#equal plan "pro"}}…{{/equal}}` | Não suportado. Passe um booleano como `is_pro` e use `{{#if is_pro}}`. |
| Sem valor padrão embutido | `{{first_name\|"there"}}` adiciona um valor alternativo |

Consulte [Temple](/pt/docs/templates/temple/) e [Importar e exportar templates](/pt/docs/templates/import-export/).

## 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](/pt/docs/domains/dns-records/).

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](/pt/docs/inbound/set-up/), que recebe em um subdomínio como `inbound.acme.com`.

## Próximos passos

- [Checklist para entrar em produção](/pt/docs/get-started/go-live/)
- [Configurar webhooks](/pt/docs/webhooks/set-up/)
- [Migração prioritária](/pt/docs/programs/priority-migration/): deixe os engenheiros do Emailit fazerem a migração com você

---
Fonte: https://emailit.com/pt/docs/migrate/mailgun/