Guia
Migrar do Mandrill
Migre do Mandrill (Mailchimp Transactional) para o Emailit. Faça a correspondência de chaves de API e subaccounts, converta as chamadas a messages/send, troque o SMTP e os cabeçalhos X-MC, verifique os webhooks e migre os rejects.
Este guia mostra a correspondência entre os conceitos, as chamadas à API, os webhooks, a rejection denylist e os templates do Mandrill (Mailchimp Transactional Email) 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. Se você também envia campanhas pelo Mailchimp, consulte Migrar do Mailchimp.
Conceitos
| Mandrill | Emailit |
|---|---|
| Um plano Standard ou Premium do Mailchimp com blocos transacionais | Uma conta do Emailit. Você não precisa de um plano de marketing para enviar e-mails transacionais. |
| Subaccounts | Workspaces, cada um com os seus próprios domínios, chaves, limites e créditos |
| API keys | Chaves de API: Full Access, ou Sending Only, que pode ser restrita a um domínio |
| Test API keys | Não há modo de teste. Os workspaces novos ficam no modo sandbox e só podem enviar para membros do workspace. |
| Sending domains e verificação DKIM/SPF | Domínios de envio |
| Tracking domains | Subdomínio de rastreamento, como go.acme.com |
Templates com regiões mc:edit |
Templates com alias e versões, renderizados com o Temple |
| Webhooks | Webhooks |
| Inbound domains e routes | Recebimento de e-mails |
| Rejection denylist | Supressões |
| Rejection allowlist | Não disponível |
| Merge languages: Mailchimp e Handlebars | Temple |
| Tags e metadata | meta |
| Outbound activity | Email APIEmails e Email APILogs |
| IPs dedicados e IP pools | IPs dedicados sob solicitação |
Atualizar as chamadas à API
O POST /messages/send do Mandrill recebe a chave de API no corpo JSON e aninha o e-mail em message. O POST /v2/emails do Emailit recebe um bearer token e um corpo sem aninhamento:
curl https://mandrillapp.com/api/1.0/messages/send \
-H "Content-Type: application/json" \
-d '{
"key": "'"$MANDRILL_API_KEY"'",
"message": {
"from_email": "hello@acme.com",
"from_name": "Acme",
"to": [{ "email": "ada@example.com", "type": "to" }],
"subject": "Your receipt",
"text": "Thanks for your order.",
"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@acme.com>",
"to": "ada@example.com",
"subject": "Your receipt",
"text": "Thanks for your order.",
"html": "<p>Thanks for your order.</p>"
}'| Mandrill | Emailit |
|---|---|
key no corpo da requisição |
Cabeçalho Authorization: Bearer secret_… |
message.from_email e from_name |
from: "Name <email>" |
message.to[] com type to, cc ou bcc |
to, cc, bcc, até 50 cada |
message.headers["Reply-To"] |
reply_to |
message.subject, html, text |
subject, html, text |
message.headers |
headers |
message.attachments[] com type, name, content |
attachments[] com content_type, filename, content |
message.images[] para imagens inline |
attachments[] com um content_id, referenciado como cid: no HTML |
message.metadata, message.tags |
meta, um objeto com valores em string, devolvido nos eventos de webhook |
message.track_opens, track_clicks |
tracking: { "loads": true, "clicks": true } |
message.global_merge_vars |
variables |
message.merge_vars (por destinatário) |
Uma requisição por destinatário, cada uma com as suas variables |
message.subaccount |
Use uma chave de API do workspace correspondente |
send_at |
scheduled_at (ISO 8601 ou inglês simples) |
async |
Não é necessário. O Emailit coloca todos os e-mails na fila de entrega e responde sem esperar pela entrega. |
POST /messages/send-template com template_name |
O mesmo POST /v2/emails com template (um alias ou ID) e variables |
Resposta: um array com email, status e _id para cada destinatário |
200 com id (em_…), status: "accepted" e, para vários destinatários, ids, com um ID para cada um |
O Mandrill informa os problemas por destinatário na resposta, com status como rejected ou invalid. O Emailit valida a requisição inteira e retorna um erro HTTP para dados inválidos. Os destinatários com uma supressão recipient são aceitos e depois recebem o status suppressed. Adicione um cabeçalho Idempotency-Key para que as novas tentativas sejam seguras. Consulte Enviar um e-mail.
Mudar as configurações SMTP
| Configuração | Mandrill | Emailit |
|---|---|---|
| Host | smtp.mandrillapp.com |
smtp.emailit.com |
| Porta | 587, 2525 ou 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS) |
| Usuário | Qualquer valor | emailit |
| Senha | Uma chave de API do Mandrill | A sua chave de API do Emailit |
O Emailit não lê cabeçalhos X-MC-*, como X-MC-Template, X-MC-MergeVars, X-MC-Tags, X-MC-Metadata ou X-MC-Track. Remova-os. Configure o rastreamento no domínio e use a API quando precisar de templates ou metadados. Consulte Configurações SMTP.
Correspondência dos eventos de webhook
| Evento do Mandrill | Evento do Emailit |
|---|---|
send |
email.accepted (somente API) |
delivered |
email.delivered |
deferral |
email.attempted |
hard_bounce |
email.bounced |
soft_bounce |
email.attempted enquanto o Emailit faz novas tentativas, e depois email.bounced se todas as novas tentativas falharem |
open |
email.loaded |
click |
email.clicked |
spam |
email.complained |
unsub |
email.unsubscribed, somente para e-mails de campanha |
reject |
email.suppressed, quando o endereço tem uma supressão recipient. Outros motivos de rejeição, como unsigned, são erros da API no Emailit. |
| Eventos de sincronização da rejection denylist | suppression.created, suppression.deleted, para as supressões que você adiciona ou remove |
inbound |
email.received; depois, busque o conteúdo com GET /emails/{id} |
O formato da requisição muda:
- O Mandrill envia um campo de formulário,
mandrill_events, que contém um array JSON de até 1.000 eventos. O Emailit envia o array JSON como corpo da requisição, com até 100 eventos. - O nome do evento fica em
type, e o e-mail fica emdata.object. Usedata.object.id, o IDem_da resposta do envio, em vez de_id, edata.object.toem vez demsg.email. Os seus valores demetaficam emdata.object.meta. - Em
email.loadedeemail.clicked,data.objecté o carregamento ou o clique. Usedata.object.email_idpara obter o ID do e-mail, edata.object.email.rcpt_toedata.object.email.metapara obter o destinatário e os seus valores demeta. - O Mandrill assina a URL e os campos do formulário com HMAC-SHA1, codificado em base64, em
X-Mandrill-Signature. O Emailit assina<timestamp>.<raw body>com HMAC-SHA256: verifiqueX-Emailit-SignaturecomX-Emailit-Timestampe o seu segredowhsec_. 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
-
Exporte a rejection denylist inteira com Export Full Denylist na página Rejection Denylist do Mandrill, ou com a chamada de API
/exports/rejects. A/rejects/listretorna no máximo 1.000 entradas, então não a use para isso. A exportação é um arquivo ZIP comrejects.csve abrange todas as subaccounts. -
Monte um único CSV com as colunas
email,type,reason. Ignore as entradas que já expiraram e use a colunareasonpara escolher o tipo:Motivo no Mandrill Tipo no Emailit hard-bounce,spam,customrecipientunsubunsubscribe, que bloqueia campanhas, mas ainda deixa passar os e-mails transacionais. Userecipientpara bloquear todos os e-mails, como o Mandrill fazia.soft-bounceDeixe de fora. Essas entradas expiram depois de um dia. email,type,reason old-address@example.com,recipient,mandrill hard-bounce angry@example.com,recipient,mandrill spamO tipo
recipientbloqueia envios pela API, por SMTP e de campanhas. Se você usava subaccounts, divida o arquivo pela coluna de subaccount e importe cada parte no workspace correspondente. -
Em Email APISuppressions, 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.
A rejection allowlist do Mandrill não tem equivalente. Consulte Gerenciar supressões.
Migrar os templates
Obtenha o código dos seus templates no Mandrill: uma única chamada a /templates/list retorna todos os templates, cada um com o slug e o HTML publicado em publish_code. Depois, importe cada um em Email MarketingTemplates ou crie-o com a API de templates. Use o slug do Mandrill como alias, se ele se encaixar no formato de alias: letras minúsculas, números, - e _.
Nos templates que usavam regiões mc:edit preenchidas por template_content, essas regiões precisam virar variáveis. Os nomes das variáveis de mesclagem do Mandrill não diferenciam maiúsculas de minúsculas, mas os do Temple diferenciam: {{FNAME}} só corresponde a uma variável chamada FNAME. Converta as tags de mesclagem para o Temple:
| Mandrill | Emailit (Temple) |
|---|---|
*|FNAME|* (linguagem de mesclagem do Mailchimp) |
{{FNAME}}, ou renomeie para {{first_name}} |
{{fname}} (linguagem de mesclagem Handlebars) |
{{fname}} |
*|IF:FNAME|*…*|ELSE:|*…*|END:IF|* |
{{#if FNAME}}…{{else}}…{{/if}} |
*|IF:PLAN=pro|*, ou uma comparação dentro de um {{#if}} do Handlebars |
Não suportado. Passe um booleano como is_pro e use {{#if is_pro}}. |
*|DATE:d/m/y|*, *|CURRENT_YEAR|*, helpers como {{upper name}} |
Não suportado. Formate o valor no seu código e passe-o. |
*|UNSUB:https://…|*, {{unsub "…"}} |
O seu próprio link de descadastro. Consulte Descadastros. |
{{#if plan}}…{{else}}…{{/if}} |
Igual |
{{#each items}}…{{/each}} |
Não suportado. Renderize a lista no seu código e passe-a como uma única variável. |
<div mc:edit="body">…</div> com template_content |
{{body}}, passado em variables |
global_merge_vars |
variables |
O Temple nunca escapa HTML, então escape o que vier dos usuários antes de passar. Um valor ausente é renderizado como string vazia, a menos que você adicione um valor padrão, como {{name|"there"}}. Consulte Temple.
Alterar o DNS
Adicione o seu domínio em Email APIDomains 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 os CNAMEs mte1._domainkey e mte2._domainkey do Mandrill nem com o registro TXT mandrill_verify dele. Mantenha o seu registro DMARC. Consulte Registros DNS.
Depois da virada, remova os registros DKIM e de verificação do Mandrill, os CNAMEs personalizados de rastreamento ou de return path que houver e include:spf.mandrillapp.com, se o seu registro SPF tiver essa entrada. Se você recebe e-mails com as inbound routes do Mandrill, mude antes para um subdomínio de recebimento do Emailit.
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ê