Guia
Migrar do MailerSend
Migre do MailerSend para o Emailit. Faça a correspondência de domínios, tokens e usuários SMTP, converta as chamadas à API e a personalização, troque o SMTP e migre webhooks, supressões e templates.
Este guia mostra a correspondência entre os conceitos, as chamadas à API, os webhooks, as supressões e os templates do MailerSend 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
| MailerSend | Emailit |
|---|---|
| Conta | Conta e workspaces. Cada workspace tem os seus próprios domínios, chaves, membros e créditos. |
| Domínios | Domínios de envio |
| Sender identities | Não disponível. Todo endereço From deve estar em um domínio verificado. |
| Tokens de API com escopos | Chaves de API: Full Access, ou Sending Only, que pode ser restrita a um domínio |
| Usuários SMTP | A sua chave de API, usada como senha do SMTP |
| Domínio de teste e modo sandbox | Não há domínio de teste compartilhado. Os workspaces novos ficam no modo sandbox e só podem enviar para membros do workspace. |
| Templates | Templates com alias e versões, renderizados com o Temple |
| Webhooks por domínio | Webhooks por workspace |
| Inbound routes | Recebimento de e-mails, com o webhook email.received ou a automação Forward received email |
| Supressões por domínio: hard bounces, reclamações de spam, descadastros, lista de bloqueio | Uma lista de supressão por workspace |
| Lista on hold | Não é necessária. O Emailit faz novas tentativas para os soft bounces e informa cada tentativa como email.attempted. |
| Activity | Email APIEmails e Email APILogs |
| Tags | meta |
| Verificação de e-mails | Verificação de e-mails |
| IPs dedicados | IPs dedicados sob solicitação |
Atualizar as chamadas à API
O POST /v1/email do MailerSend passa a ser POST /v2/emails. Os dois recebem um bearer token e JSON, mas no Emailit os endereços são strings simples em vez de objetos:
curl https://api.mailersend.com/v1/email \
-H "Authorization: Bearer $MAILERSEND_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"from": { "email": "hello@acme.com", "name": "Acme" },
"to": [{ "email": "ada@example.com" }],
"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>"
}'| MailerSend | Emailit |
|---|---|
Authorization: Bearer <token> |
Authorization: Bearer secret_… |
from: { email, name } |
from: "Name <email>" |
to[], cc[], bcc[] com email e name |
to, cc, bcc como string ou array de até 50 cada |
reply_to: { email, name } |
reply_to |
subject, text, html |
Iguais |
headers: [{ "name": "…", "value": "…" }] |
headers: { "Name": "Value" } |
list_unsubscribe |
headers com List-Unsubscribe e List-Unsubscribe-Post. Consulte Cabeçalhos e metadados. |
attachments[] com content, filename, disposition e id |
attachments[] com content, filename e content_type, ou uma url no lugar de content. Use content_id para imagens inline. |
template_id |
template, um ID ou alias de template |
personalization: [{ "email": "…", "data": { … } }] |
variables, com uma requisição por destinatário quando os valores forem diferentes |
tags |
meta, devolvido nos eventos de webhook |
send_at (horário Unix ou ISO 8601) |
scheduled_at (ISO 8601 ou inglês simples). Converta os horários Unix para ISO 8601 antes. |
settings.track_opens, settings.track_clicks |
tracking: { "loads": true, "clicks": true } |
POST /v1/bulk-email |
Não disponível. Envie uma requisição por mensagem. |
202 Accepted com um cabeçalho x-message-id e um corpo vazio |
200 com um corpo JSON: id (em_…), status: "accepted" e, para vários destinatários, ids, com um ID para cada um |
Cada destinatário de uma requisição do Emailit vira um e-mail próprio, com o seu próprio ID. O MailerSend responde 202 mesmo quando todos os destinatários estão suprimidos, com um aviso no corpo. O Emailit também aceita destinatários com uma supressão recipient e dá a cada um 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 | MailerSend | Emailit |
|---|---|---|
| Host | smtp.mailersend.net |
smtp.emailit.com |
| Porta | 587 (STARTTLS) |
587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS) |
| Usuário | O nome de usuário gerado para o usuário SMTP | emailit |
| Senha | A senha do usuário SMTP | A sua chave de API do Emailit |
O Emailit não lê o cabeçalho X-MailerSend-Tags. Remova-o. Ao contrário do MailerSend, o Emailit entrega os seus outros cabeçalhos personalizados sem alterações. Consulte Configurações SMTP.
Correspondência dos eventos de webhook
| Evento do MailerSend | Evento do Emailit |
|---|---|
activity.sent |
email.accepted (somente API) |
activity.delivered |
email.delivered |
activity.deferred |
email.attempted |
activity.soft_bounced |
email.attempted enquanto o Emailit faz novas tentativas, e depois email.bounced se todas as novas tentativas falharem |
activity.hard_bounced |
email.bounced |
activity.suppressed |
email.suppressed |
activity.opened, activity.opened_unique |
email.loaded, enviado a cada carregamento |
activity.clicked, activity.clicked_unique |
email.clicked, enviado a cada clique |
activity.spam_complaint |
email.complained |
activity.unsubscribed |
email.unsubscribed, somente para e-mails de campanha |
| Inbound route que encaminha para um webhook | email.received; depois, busque o conteúdo com GET /emails/{id} |
O formato da requisição muda:
- O MailerSend envia um evento por requisição. O Emailit envia um array JSON de até 100 eventos, então percorra o corpo em um loop.
- Nos dois, o nome do evento fica em
type. No Emailit, o e-mail fica emdata.object: usedata.object.id, o IDem_da resposta do envio, em vez dedata.message_id(data.email.message.idnos webhooks da versão 1), edata.object.toem vez dedata.recipient. 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 cabeçalho
Signaturedo MailerSend é um HMAC-SHA256 do corpo bruto. OX-Emailit-Signaturedo Emailit é um HMAC-SHA256 de<timestamp>.<raw body>, com o seu segredowhsec_como chave, então leia tambémX-Emailit-Timestamp. 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
-
No MailerSend, exporte as listas Hard bounces, Spam complaints, Unsubscribes e Blocklist de cada domínio, pelas páginas de supressão ou pela API (
/v1/suppressions/hard-bounces,/spam-complaints,/unsubscribese/blocklist). A lista on hold é temporária, então você pode deixá-la de fora. -
Monte um único CSV com as colunas
email,type,reason:email,type,reason old-address@example.com,recipient,mailersend hard bounce angry@example.com,recipient,mailersend spam complaintUse o tipo
recipientpara endereços que nunca devem receber e-mails. Ele bloqueia envios pela API, por SMTP e de campanhas. Para pessoas que só se descadastraram dos e-mails de marketing, use o tipounsubscribe, que bloqueia campanhas, mas ainda deixa passar os e-mails transacionais. -
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.
O Emailit tem uma lista de supressão por workspace, então os endereços de todos os seus domínios do MailerSend vão para a mesma lista. As supressões são endereços exatos: padrões da lista de bloqueio como .*@example.com não têm equivalente. Consulte Gerenciar supressões.
Migrar os templates
Copie o HTML de cada template do editor do MailerSend e depois importe-o em Email MarketingTemplates ou crie-o com a API de templates. Dê a ele um alias, como receipt, e envie-o com "template": "receipt" e variables.
A personalização do MailerSend é uma versão limitada do Twig. O Temple cobre as partes mais comuns:
| MailerSend | Emailit (Temple) |
|---|---|
{{ name }}, {{ user.name }} |
{{name}}, {{user.name}} |
{{ name|default('there') }} |
{{name|"there"}} |
{% if plan %}…{% else %}…{% endif %} |
{{#if plan}}…{{else}}…{{/if}} |
{% if plan == "pro" %}, {% elseif %} |
Não suportado. Passe um booleano como is_pro e use {{#if is_pro}}. |
{% for item in items %}…{% endfor %} |
Não suportado. Renderize a lista no seu código e passe-a como uma única variável. |
{{ name|upper }} e outros filtros |
Não suportado. Formate o valor no seu código. |
personalization[].data |
variables |
O MailerSend remove a maior parte do HTML dos valores de personalização. O Temple nunca escapa nem remove HTML, então escape o que vier dos usuários antes de passar. Consulte Temple e Importar e exportar templates.
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 registros DKIM ms1._domainkey e ms2._domainkey do MailerSend, com o CNAME de return path mta dele nem com o CNAME de rastreamento email dele. Mantenha o seu registro DMARC. Consulte Registros DNS.
O roteamento de recebimento do MailerSend também usa um subdomínio inbound por padrão. Se o seu usar, dê outro subdomínio ao recebimento do Emailit com inbound_key, ou troque o registro MX quando migrar os e-mails recebidos. Consulte Configurar o recebimento de e-mails.
Depois da virada, remova os registros DKIM, de return path e de rastreamento do MailerSend e remova include:_spf.mailersend.net do seu registro SPF.
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ê