Mudar do SendGrid

Passe para o Mailroomly uma aplicação feita para o SendGrid sem a reescrever: a biblioteca do SendGrid, o handler de eventos e o handler de Inbound Parse ficam iguais, e só mudam o host da API e a chave.

O que se mantém

O Mailroomly fala a API Mail Send do SendGrid e os seus formatos de webhook:

  • O endpoint. POST /v3/mail/send, na raiz de https://app.mailroomly.com, aceita o pedido do SendGrid: personalizations (com to, cc, bcc, subject, substitutions, headers e custom_args), from, reply_to ou reply_to_list, subject, content, attachments, headers, categories, custom_args, asm, o acompanhamento de aberturas e cliques, e o sandbox mode. Responde 202 com um X-Message-Id, e os erros na forma {"errors": [...]} do SendGrid.
  • A chave. A chave de API de uma aplicação vai em Authorization: Bearer, onde estava a chave do SendGrid.
  • O email de marketing. Um pedido com asm envia email de marketing: o destinatário pode cancelar a subscrição, e <%asm_group_unsubscribe_raw_url%> passa a ser a ligação própria de cada destinatário para o fazer. Sem ele, o email é transacional.
  • O sandbox mode. mail_settings.sandbox_mode verifica o pedido (os campos, os endereços, o domínio do remetente e a chave) e não envia nada.
  • O Event Webhook. Com o formato Compatível com SendGrid, os eventos chegam como os do SendGrid: processed, dropped, delivered, deferred, bounce, open, click, spamreport e unsubscribe, com os seus custom_args e category, e um sg_message_id que começa pelo X-Message-Id. São assinados como o SendGrid os assina, por isso a verificação da assinatura do seu handler continua a funcionar com a chave de verificação da aplicação.
  • O Inbound Parse. O email que os seus endereços recebem chega no formulário do Inbound Parse do SendGrid, com os seus campos e anexos.

Todos os campos e eventos: SendGrid compatibility (em inglês).

Antes de começar

  • Um domínio verificado. O domínio de envio da aplicação tem de estar verificado no Mailroomly (O seu próprio domínio). Os registos DNS do Mailroomly e os do SendGrid convivem, por isso ambos podem enviar pelo mesmo domínio durante a mudança.
  • Um limite diário à medida. Uma conta nova envia para um número limitado de destinatários por dia até passar a conta de confiança. Consulte o Plano antes de mudar uma aplicação com muito envio e peça um limite maior se precisar (Confiança de envio).
  • Os seus endereços bloqueados. As supressões do SendGrid (devoluções, queixas de spam, cancelamentos da subscrição, endereços inválidos) não passam sozinhas. Exporte-as do SendGrid e bloqueie-as em Atividade › Bloqueados › Bloquear um endereço, ou pela API, antes do primeiro envio (Bloqueados). Bloqueie as devoluções, as queixas e os endereços inválidos para todos os tipos de email, e os cancelamentos da subscrição para o marketing.
  • O que o Mailroomly não faz. Os modelos dinâmicos por template_id, os envios agendados (send_at, batch_id), os IP pools, as secções antigas, os rodapés e o subscription tracking são recusados com o motivo, nunca ignorados: prepare o conteúdo na aplicação e envie quando o email deve sair.

Passar uma aplicação

As aplicações mudam uma de cada vez. Aplicações › Mudar do SendGrid (também no Ctrl K) guia-o pelos três passos na aplicação web: ligar uma aplicação no formato do SendGrid, apontar a biblioteca do SendGrid para o Mailroomly e mudar os webhooks.

1. Criar a aplicação e a chave

Em Mudar do SendGrid, escolha Ligar uma aplicação em Ligue uma aplicação no formato do SendGrid. Indique o Nome da aplicação e escolha O que faz (Envio de email chega para a maioria das aplicações), depois A que emails acede esta chave? e Criar a aplicação e a chave. Os webhooks da aplicação já usam o formato Compatível com SendGrid.

A chave, que começa por mp_live_, substitui a chave de API do SendGrid. Só é mostrada uma vez: copie-a para o cofre de segredos da aplicação. Para a limitar aos domínios da aplicação ou a um tipo de email, crie outra chave na página da aplicação e revogue a primeira (Aplicações e chaves).

2. Apontar a biblioteca do SendGrid para o Mailroomly

Mude dois valores na configuração da aplicação: o host da API e a chave. O código que constrói e envia o email fica igual.

// Node
const client = require('@sendgrid/client')
const sgMail = require('@sendgrid/mail')

client.setApiKey(process.env.MAILROOMLY_API_KEY)
client.setDefaultRequest('baseUrl', 'https://app.mailroomly.com')
sgMail.setClient(client)

# Python
sg = SendGridAPIClient(api_key=os.environ["MAILROOMLY_API_KEY"], host="https://app.mailroomly.com")

As outras bibliotecas (PHP, Ruby, Go, Java e C#) têm a mesma definição: SendGrid's libraries (em inglês). Sem biblioteca, envie o mesmo pedido para https://app.mailroomly.com/v3/mail/send.

Confirme como a aplicação envia marketing: o email enviado com asm é de marketing, e o email sem ele é transacional. Uma chave limitada ao marketing envia marketing, diga o pedido o que disser.

3. Mudar os webhooks

Na página da aplicação, abra o passo Webhook:

  1. URL do webhook: o endpoint que recebia o Event Webhook do SendGrid.
  2. Formato do conteúdo: Compatível com SendGrid (o guia já o escolheu).
  3. Eventos a enviar: marque o que o endpoint trata: Aceite para envio, Não enviada (endereço inválido ou bloqueado), Entregue, Devolvida, Entrega atrasada, Aberta, Clicada, Queixa, Cancelou a subscrição e Mensagem recebida.
  4. Guardar alterações e depois Enviar um evento de teste, para ver o que o seu endpoint responde.
  5. Em Detalhes avançados, copie a Chave de verificação (Event Webhook assinado do SendGrid) para o seu handler de eventos, onde estava a chave de verificação do SendGrid.

Rodar segredo renova também a chave de verificação, de imediato: o seu handler só consegue verificar os eventos quando tiver a nova chave, por isso coloque-a lá logo depois de rodar. As entregas que recusar entretanto são repetidas.

Um único URL recebe todos os eventos que a aplicação escolhe e o email que os seus endereços recebem. O email recebido chega como formulário (multipart/form-data) e os eventos como lista JSON, por isso um só handler distingue-os. Se o seu handler de eventos e o de Inbound Parse estão em dois URLs, dê ao endereço que recebe o seu próprio URL do webhook de receção (passo 4) e desmarque aqui Mensagem recebida, para que o email recebido chegue só a esse URL. O URL não pode levar nome de utilizador e palavra-passe: confirme antes a assinatura (Webhooks).

4. Receber email, se a aplicação o fazia com o SendGrid

Para uma aplicação que recebia email pelo Inbound Parse do SendGrid:

  1. Passe o domínio a Envio e receção (O que este domínio faz, nas Definições), normalmente o mesmo subdomínio que a aplicação usava com o Inbound Parse, nunca um domínio cujo email está noutro serviço (Endereços e domínios).
  2. Crie o endereço que recebe e escolha a aplicação como Aplicação responsável. Indique um URL do webhook de receção se o seu handler de Inbound Parse tem um URL próprio. Os pedidos chegam no formulário do Inbound Parse, assinados com o segredo da aplicação em X-Messaging-Signature.
  3. Se o Inbound Parse recebia para qualquer endereço do subdomínio, torne esse endereço o Endereço geral do domínio: o endereço para onde cada email foi enviado está no campo envelope.
  4. Mude o registo MX do domínio para o valor indicado na página do domínio (Registos DNS) e espere até a página o mostrar em ordem. Baixe o tempo de vida do registo um dia antes, para poder voltar atrás depressa.

Definir a aplicação responsável ou o URL do webhook de receção de um endereço exige uma pessoa com sessão iniciada no Mailroomly: um agente não o pode fazer (Agentes de IA).

5. Testar

Envie um email a partir da aplicação com mail_settings.sandbox_mode ativo: a resposta é 200 e nada é enviado. Depois envie um a sério: a resposta é 202 com um X-Message-Id, e o email aparece na Atividade, de Enviado a Entregue. Enviar um teste como esta aplicação, na página da aplicação, envia-lhe um e mostra os eventos que o seu webhook recebeu (Enviar um email de teste). Para a receção, envie um email para o endereço: aparece na caixa de entrada, e as Entregas de webhooks mostram a entrega ao seu endpoint.

6. Acompanhar a Atividade

Nos primeiros dias, acompanhe:

  • A Atividade: cada envio, com o trajeto e os eventos (A página de um envio). Bloqueados mostra os endereços para onde o Mailroomly não envia, e porquê.
  • As Entregas de webhooks: as entregas que o seu endpoint não aceitou, para corrigir e reenviar.
  • Os Avisos: devoluções, queixas, limites diários e webhooks falhados, cada um a dizer o que fazer.

Voltar atrás

Mantenha a conta do SendGrid, os registos DNS e os webhooks até a mudança estar concluída. Para voltar, reponha os dois valores, o host da API e a chave: a aplicação volta a enviar pelo SendGrid em poucos minutos. Para a receção, aponte de novo o registo MX para o SendGrid. O email já aceite pelo Mailroomly continua a ser enviado e fica na Atividade.

O que é diferente

No Mailroomly
Modelos Os modelos dinâmicos por template_id são recusados: prepare o conteúdo na aplicação antes de enviar.
As outras APIs do SendGrid As campanhas e os contactos de marketing, as supressões e os grupos de cancelamento, as estatísticas, o activity feed, os subutilizadores, a verificação de remetentes e a autenticação de domínios não são emulados. Use a REST API e a aplicação web (Atividade, Bloqueados, Endereços, Campanhas).
Remetentes Qualquer endereço de um domínio verificado envia; não há remetentes individuais para verificar.
Cada personalization É um email no Mailroomly, com a sua própria página na Atividade. Partilham o X-Message-Id do pedido.
Grupos de cancelamento Um cancelamento da subscrição abrange todo o marketing da sua organização, não um grupo.
Ids O X-Message-Id e os ids em sg_message_id são UUID.
Destinatários bloqueados Ficam de fora do email, tal como o SendGrid os descarta, e são indicados num evento dropped.
Limites 500 personalizations por pedido, 50 destinatários e 10 MB por email, 100 pedidos por segundo por chave. Um anexo que todas as personalizations partilham conta uma vez por cada uma: as personalizations de um pedido somam no máximo 50 MB.
Recusas Um campo que o Mailroomly não suporta é 400 com o nome do campo; um domínio não verificado, uma chave fora do seu âmbito ou marketing não permitido é 403; o limite diário, ou o da própria chave, é 429 até à meia-noite UTC, tal como os emails do mês de um plano esgotados; uma chave errada ou em falta é 401.
Campos dos eventos Sem ip, tls, attempt, pool, asm_group_id nem marketing_campaign_*.
Campos do Inbound Parse Sem dkim, SPF, sender_ip nem pontuação de spam.
Repetição dos webhooks As entregas que falham são repetidas durante cerca de 45 horas, depois ficam Falhada e podem ser reenviadas (Webhooks). Cada tentativa tem de terminar em 10 segundos: responda 2xx de imediato e faça o trabalho depois.

A referência para programadores, campo a campo: SendGrid compatibility (em inglês).