Guia
Migrar do Mailtrap
Migre do Mailtrap Email Sending para o Emailit. Faça a correspondência de streams, tokens e sub-accounts, converta as chamadas à API e os templates Handlebars, troque o SMTP e migre webhooks, supressões e contatos.
Este guia mostra a correspondência entre os conceitos, as chamadas à API, os webhooks, as supressões, os templates e os contatos do Mailtrap Email Sending 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
| Mailtrap | Emailit |
|---|---|
| Organização e sub-accounts | Conta e workspaces. Cada workspace tem os seus próprios domínios, chaves, membros e créditos. |
| Domínios de envio | Domínios de envio |
| Transactional stream | A API de e-mail e o SMTP relay |
| Bulk stream | Campanhas, ou a API com os seus próprios cabeçalhos List-Unsubscribe |
| Tokens de API com permissões por recurso | Chaves de API: Full Access, ou Sending Only, que pode ser restrita a um domínio |
| Domínio de demonstração | Os workspaces novos ficam no modo sandbox e podem enviar para membros do workspace a partir do seu próprio domínio verificado. |
| Email Sandbox (testes) | Não disponível. Mantenha o sandbox do Mailtrap para testes, ou envie para membros do workspace enquanto desenvolve. |
| Templates | Templates com alias e versões, renderizados com o Temple |
| Webhooks por stream | Webhooks por workspace |
| Supressões por domínio e por stream | Uma lista de supressão por workspace |
| Logs de e-mail | Email APIEmails e Email APILogs |
category e custom_variables |
meta |
| Email Marketing: contatos, listas, campanhas, automações | Contatos, listas de contatos, campanhas e automações (beta) |
| Recebimento de e-mails | Recebimento de e-mails |
Para manter separadas a reputação transacional e a de marketing, como fazem os dois streams do Mailtrap, envie de domínios ou subdomínios diferentes, como mail.acme.com para recibos e news.acme.com para newsletters.
Atualizar as chamadas à API
O POST /api/send do Mailtrap 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://send.api.mailtrap.io/api/send \
-H "Authorization: Bearer $MAILTRAP_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>"
}'| Mailtrap | Emailit |
|---|---|
Authorization: Bearer <token> ou Api-Token: <token> |
Authorization: Bearer secret_… |
send.api.mailtrap.io e bulk.api.mailtrap.io |
Um único host, api.emailit.com |
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, headers |
Iguais |
attachments[] com content, filename, type, disposition e content_id |
attachments[] com content, filename, content_type e content_id, ou uma url no lugar de content |
category |
meta, por exemplo meta: { "category": "password-reset" } |
custom_variables |
meta, devolvido nos eventos de webhook |
template_uuid e template_variables |
template (um alias ou ID) e variables |
| Rastreamento definido por domínio | Rastreamento definido por domínio, ou por e-mail com tracking: { "loads": true, "clicks": true } |
POST /api/batch (até 500 mensagens) |
Não disponível. Envie uma requisição por mensagem. |
Resposta com message_ids, um por destinatário |
200 com id (em_…), status: "accepted" e, para vários destinatários, ids, com um ID para cada um |
O Emailit também oferece agendamento com scheduled_at e novas tentativas seguras com um cabeçalho Idempotency-Key, o que a API de envio do Mailtrap não oferece. Consulte Enviar um e-mail.
Mudar as configurações SMTP
| Configuração | Mailtrap | Emailit |
|---|---|---|
| Host | live.smtp.mailtrap.io, ou bulk.smtp.mailtrap.io para o bulk stream |
smtp.emailit.com |
| Porta | 587, 2525 ou 25 (STARTTLS), 465 (TLS) |
587, 2587, 2525 ou 25 (STARTTLS), 465 (TLS) |
| Usuário | api |
emailit |
| Senha | O seu token de API do Mailtrap | A sua chave de API do Emailit |
O Emailit não lê os cabeçalhos X-MT-Category nem X-MT-Custom-Variables. Remova-os e use a API quando precisar de metadados. Consulte Configurações SMTP.
Correspondência dos eventos de webhook
| Evento do Mailtrap | Evento do Emailit |
|---|---|
delivery |
email.delivered |
soft bounce |
email.attempted enquanto o Emailit faz novas tentativas, e depois email.bounced se todas as novas tentativas falharem |
bounce |
email.bounced |
reject |
email.suppressed quando o endereço tem uma supressão recipient |
suspension |
email.held |
spam |
email.complained |
open |
email.loaded |
click |
email.clicked |
unsubscribe |
email.unsubscribed, somente para e-mails de campanha |
inbound.message_received |
email.received; depois, busque o conteúdo com GET /emails/{id} |
O Emailit também envia email.accepted quando a API aceita um e-mail. Consulte Tipos de evento.
O formato da requisição muda:
- O Mailtrap envia uma lista
eventsde até 500 eventos, ou JSON Lines. O Emailit envia um array JSON de até 100 eventos como corpo da requisição. - 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 demessage_id, edata.object.toem vez deemail. Os seus valores demeta, que substituemcategoryecustom_variables, ficam 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
Mailtrap-Signaturedo Mailtrap é 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
-
Exporte as suas supressões em Suppressions no Mailtrap, ou percorra as páginas de
GET https://mailtrap.io/api/suppressions, que retorna até 1.000 entradas por chamada. -
Monte um único CSV com as colunas
email,type,reason:Tipo no Mailtrap Tipo no Emailit hard bounce,spam complaint,manual importrecipient, que bloqueia envios pela API, por SMTP e de campanhasunsubscriptionunsubscribe, que bloqueia campanhas, mas ainda deixa passar os e-mails transacionais. Userecipientpara descadastros do transactional stream.email,type,reason old-address@example.com,recipient,mailtrap hard bounce left@example.com,unsubscribe,mailtrap unsubscription -
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, então os endereços suprimidos em vários domínios ou streams do Mailtrap são adicionados uma única vez.
Consulte Gerenciar supressões.
Migrar os contatos
Se você usa o Mailtrap Email Marketing, exporte os seus contatos em Contacts com More Actions > Export, ou com POST https://mailtrap.io/api/contacts/exports filtrado por subscription_status e list_id. Antes, crie no Emailit os campos personalizados e as listas de contatos correspondentes.
Importe apenas os contatos inscritos, uma lista de contatos por vez, em Email MarketingContacts com Import. A importação adiciona todas as pessoas do arquivo como inscritas, então, em vez disso, adicione os contatos descadastrados ao seu arquivo de supressões com o tipo unsubscribe. Divida os arquivos em partes de até 2.500 linhas. Consulte Importar e exportar contatos.
Migrar os templates
Obtenha o HTML dos seus templates com GET https://mailtrap.io/api/email_templates, que retorna body_html, body_text e subject de cada template. Importe cada um em Email MarketingTemplates ou crie-o com a API de templates e dê a ele um alias, como receipt.
Os templates do Mailtrap usam Handlebars. O Temple cobre as partes mais comuns:
| Mailtrap (Handlebars) | Emailit (Temple) |
|---|---|
{{name}}, {{user.name}} |
Igual |
{{{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}} |
{{#if name}}{{name}}{{else}}Customer{{/if}} |
{{name|"Customer"}} |
{{#each items}}…{{/each}}, {{#with}} |
Não suportado. Renderize a lista no seu código e passe-a como uma única variável. |
template_variables |
variables |
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 rwmt1._domainkey e rwmt2._domainkey do Mailtrap, com o CNAME de verificação dele nem com o CNAME de rastreamento mt-link dele. Mantenha o seu registro DMARC. Consulte Registros DNS.
Depois da virada, remova os registros DKIM, de verificação e de rastreamento do Mailtrap e o include:_spf.mailtrap.io, se o seu registro SPF ainda o tiver. O recebimento do Mailtrap usa o registro MX do seu domínio raiz, e o do Emailit usa um subdomínio como inbound.acme.com, então migre os e-mails recebidos e atualize os seus endereços de recebimento antes de alterar o registro MX. Consulte Configurar o recebimento de e-mails.
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ê