Migrar do SendGrid para o Mailtrap

Checklist de Migração

1. Autentique o seu domínio
   Adicione e verifique o seu domínio antes de enviar. Siga o artigo de configuração de domínio em docs.mailtrap.io.

2. Obtenha o seu token de API
   O Mailtrap gera automaticamente um token quando adiciona um domínio. Encontre-o em “Settings” → “API Tokens”. Leia mais sobre tokens de API.
3. Atualize a sua integração
   Substitua os endpoints e as credenciais do SendGrid pelos do Mailtrap (API ou SMTP). Veja as secções de migração abaixo.
4. Migre os templates
   Ambas as plataformas usam Handlebars, pelo que o conteúdo é migrado diretamente. Veja as secções de templates abaixo.
5. Migre as supressões
   Exporte as supressões do SendGrid e importe-as para o Mailtrap via CSV ou manualmente. Clique aqui para mais informações.
6. Migre os utilizadores
   Adicione utilizadores a partir da aba “User Management” e reveja as permissões durante a migração.
7. Configure os webhooks
   Siga o guia passo a passo de webhooks do Mailtrap.
8. Segurança e conformidade
   Visite a página do Trust Center para rever as práticas de segurança e os padrões de conformidade do Mailtrap.

Conceitos

Antes de analisar os detalhes técnicos, é importante esclarecer alguns conceitos-chave.

Domínios de envio

No Mailtrap: Sending Domains

Equivalente no SendGrid: Domain Authentication

Antes de poder enviar emails com o Mailtrap, precisa de adicionar e verificar o seu domínio de envio. Para a verificação do domínio, o Mailtrap fornece registos DNS que seguem os mesmos padrões em que o SendGrid se baseia.

Os registos DKIM podem ser adicionados em conjunto com os do SendGrid (seletores diferentes, sem conflito), e um registo DMARC cobre ambos. Para o SPF, no entanto, deve intercalar o include do Mailtrap no seu registo SPF existente, em vez de adicionar um registo separado.

Para saber como verificar o seu domínio, pode ler o nosso guia passo-a-passo na documentação oficial ou ver o vídeo que preparámos para si. Todo o processo demora cerca de 15 minutos.

Fluxos de envio separados

No Mailtrap: Separate Sending Streams

Equivalente no SendGrid: N/A

O Mailtrap fornece duas infraestruturas de email separadas, ou fluxos de envio:

• Fluxo transacional – Para o envio de emails acionados pelo utilizador, como emails de boas-vindas e redefinições de palavra-passe.
• Fluxo de envio em massa – Para o envio de emails promocionais e de marketing, como newsletters e atualizações de produtos.

Ao manter as infraestruturas de envio separadas, consegue:

• Proteger a reputação dos seus emails transacionais do impacto das suas campanhas em massa
• Garantir que cada fluxo é encaminhado através dos pools de IP corretos
• Dar aos provedores de email os sinais de que precisam para categorizar e entregar os seus emails corretamente

Categorias de email

No Mailtrap: Email Categories

Equivalente no SendGrid: Categories

Tal como o SendGrid, o Mailtrap oferece uma funcionalidade de Categorias de Email que lhe permite acompanhar o desempenho de diferentes tipos de emails (ex: emails de boas-vindas, redefinições de palavra-passe, etc.).

• Utilizar as Email Categories com o Mailtrap: insira um nome de categoria no cabeçalho X-MT-Category se estiver a usar SMTP. Ou passe o nome da categoria no campo category se estiver a enviar via API.
• Utilizar as Categories com o SendGrid: Passe as categorias dentro do cabeçalho JSON X-SMTPAPI se estiver a usar SMTP. Ou passe uma série de strings no campo categories se estiver a enviar via API. O SendGrid suporta até 10 categorias por email.

Organização e subcontas

No Mailtrap: Organization & Sub-accounts

Equivalente no SendGrid: Subusers

O Mailtrap oferece a funcionalidade Organization & Sub-accounts, que lhe permite gerir configurações complexas envolvendo múltiplas equipas, clientes, ambientes ou produtos sob uma única Organização. Para começar a usar a funcionalidade, precisa primeiro de a ativar na aba “Organization”.

Nota: a funcionalidade está disponível a partir do plano Business.

Comparação de terminologia

Migração da API

Autenticação

Ambas as plataformas usam autenticação por token Bearer no cabeçalho Authorization – o mesmo padrão, chave diferente.

Não é necessária nenhuma alteração de código além da substituição do valor da chave. O formato do cabeçalho é idêntico.

Mapeamento da API

Mapeamento de campos JSON da API de envio

O SendGrid usa POST https://api.sendgrid.com/v3/mail/send; o Mailtrap usa POST https://send.api.mailtrap.io/api/send. Ambos aceitam application/json.

Trechos de código

Nota:

• Estrutura simples vs. o wrapper personalizations. O SendGrid aninha destinatários, assuntos e dados dinâmicos dentro de uma série personalizations. O Mailtrap mantém as coisas simples: to, cc, bcc, subject e template_variables vivem todos na raiz do corpo do pedido. Para chamadas transacionais de um único email (o caso mais comum), isto elimina o aninhamento e o código repetitivo (“boilerplate”).
• Campos do corpo: array content[] vs. html/text. O SendGrid envolve o conteúdo do corpo num array chamado content, onde cada elemento declara um type MIME e um value. O Mailtrap usa campos dedicados html e text na raiz. Assim, é mais direto e mais fácil de ler num diff.
• Autenticação: padrão idêntico. Ambos usam Authorization: Bearer <api_key>. Substitua a chave, atualize o URL do endpoint e ajuste a estrutura do “payload”.
• A seleção do fluxo de envio é estrutural. O SendGrid encaminha todos os emails através de um único endpoint (/v3/mail/send). O Mailtrap usa endpoints separados – send.api.mailtrap.io para emails transacionais e bulk.api.mailtrap.io para envios em massa – isolando os dois ao nível da infraestrutura.

Migração de SMTP

Notas de migração:

• O Mailtrap usa hosts SMTP separados para fluxos transacionais (live.smtp.mailtrap.io) e em massa (bulk.smtp.mailtrap.io). O SendGrid usa um único host (smtp.sendgrid.net) para todos os envios.
• O nome de utilizador SMTP é uma string literal em ambos os casos, mas diferem: o Mailtrap usa api e o SendGrid usa apikey. Ambos devem ser inseridos exatamente como demonstrado, ou seja, não substitua api ou apikey com outros dados.

Para mais informações sobre como migrar a sua configuração de SMTP, clique neste link. ⬅️

Limites de tráfego e quotas

Templates de email

Tanto o SendGrid como o Mailtrap usam a sintaxe Handlebars para templates dinâmicos. A inserção básica de variáveis ({{variable}}), condicionais ({{#if}}), iteração ({{#each}}) e HTML não escapado ({{{variable}}}) funcionam da mesma forma em ambas as plataformas. O markup do seu template será, na sua maioria, portado diretamente; as diferenças estão nas funções helper, na sintaxe do valor por defeito e na forma como as variáveis são passadas através da API.

Comparação de sintaxe

Notas de migração

• As variáveis e loops são transferidos diretamente. Ambas as plataformas usam Handlebars padrão – {{var}}, {{#if}}, {{#each}} e {{{unescaped}}} funcionam de forma idêntica. Não são necessárias alterações na formatação, ou markup, do template para estes casos.
• Os valores por defeito precisam de ser reescritos. O helper insert do SendGrid ({{insert name "default=Customer"}}) é uma extensão específica do SendGrid. No Mailtrap, pode usar um bloco standard de Handlebars {{#if}} / {{else}}, como: {{#if name}}{{name}}{{else}}Customer{{/if}}. É mais longo, mas são Handlebars padrão – sem dependência de fornecedor.
• A formatação de datas passa para a sua camada de aplicação. O helper {{formatDate timestamp "MM/DD/YYYY"}} do SendGrid formata datas dentro do template. O Mailtrap não suporta um helper de formatação de datas, pelo que deve formatar as datas no seu código antes de as passar como variáveis de template. Se tiver templates com chamadas formatDate, substitua cada uma por uma variável de string pré-formatada (ex.: {{formatted_date}}) e calcule o valor no lado do servidor.
• Os helpers lógicos e de comparação não estão disponíveis. O SendGrid suporta os helpers greaterThan, lessThan, notEquals, and, or e length para lógica interna do template. O Mailtrap usa Handlebars padrão, que não inclui estes recursos. Mova essa lógica para a sua aplicação: calcule o resultado e passe um boolean ou um valor pré-resolvido como variável de template.
• A passagem de variáveis é quase idêntica. Ambos usam um objeto JSON – dê um novo nome ao campo dynamic_template_data (dentro de personalizations[]) para template_variables (ao nível da raiz). A estrutura da própria variável permanece a mesma.
• Os IDs dos templates mudam de formato. Os templates dinâmicos do SendGrid usam uma string com o prefixo d- (ex.: d-abc123def456). O Mailtrap usa template_uuid. Terá de recriar os templates no Mailtrap e atualizar os IDs no seu código.
• Os templates sobrepõem-se ao assunto e ao conteúdo. No SendGrid, um template dinâmico com uma linha de assunto sobrepõe-se a qualquer subject definido no pedido da API. O Mailtrap comporta-se da mesma forma – se o template incluir um assunto, o campo subject no pedido da API é ignorado.