Mudar do Mailgun

O que se mantém

O Mailroomly fala a API de mensagens do Mailgun e os seus formatos de webhook:

• Os endpoints. POST /v3/{domain}/messages e POST /v3/{domain}/messages.mime, na raiz de https://app.mailroomly.com, aceitam o formulário do Mailgun: from, to, cc, bcc, subject, text, html, attachment, inline, recipient-variables para o envio em lote, o:tag, o acompanhamento de aberturas e cliques, o test mode, os cabeçalhos h: e as variáveis v:. Respondem {"id": "<…>", "message": "Queued. Thank you."}, e os erros na forma {"message": "…"} do Mailgun.
• A chave. A chave de API de uma aplicação vai onde estava a chave do Mailgun: o SDK envia-a como a do Mailgun, com o utilizador api.
• O envio em lote. Com recipient-variables, cada destinatário recebe o seu próprio email, com %recipient.name% substituído pelos seus valores. Um lote é verificado por inteiro antes de se enviar alguma coisa.
• O test mode. o:testmode=yes verifica o pedido (os campos, os endereços, o domínio do remetente e a chave) e não envia nada.
• Os webhooks. Com o formato Compatível com Mailgun, os eventos chegam como os do Mailgun: accepted, delivered, failed, opened, clicked, complained e unsubscribed, com as suas variáveis v: em user-variables e o id da resposta em message.headers.message-id. São assinados como o Mailgun os assina, por isso a verificação da assinatura do seu handler continua a funcionar com o segredo de assinatura da aplicação.
• As routes. O email que os seus endereços recebem chega tal como uma route do Mailgun o reencaminha, com os seus campos e anexos.

Todos os campos e eventos: Mailgun 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 Mailgun convivem, por isso ambos podem enviar pelo mesmo domínio durante a mudança. O Mailroomly envia a partir do endereço De: o domínio no caminho do pedido continua a ser o seu, e é o domínio do endereço De que tem de estar verificado.
• 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 Mailgun (devoluções, queixas, cancelamentos da subscrição) não passam sozinhas. Exporte-as do Mailgun e bloqueie-as em Atividade › Bloqueados › Bloquear um endereço, ou pela API, antes do primeiro envio (Bloqueados). Bloqueie as devoluções e as queixas para todos os tipos de email, e os cancelamentos da subscrição para o marketing.
• O que o Mailroomly não faz. Os templates guardados (template, opções t:), os envios agendados (o:deliverytime), o AMP, os IP de envio e o:archive-to 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 Mailgun (também no Ctrl K) guia-o pelos três passos na aplicação web: ligar uma aplicação no formato do Mailgun, apontar o SDK do Mailgun para o Mailroomly e mudar os webhooks.

1. Criar a aplicação e a chave

Em Mudar do Mailgun, escolha Ligar uma aplicação em Ligue uma aplicação no formato do Mailgun. 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 Mailgun.

A chave, que começa por mp_live_, substitui a chave de API do Mailgun. 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 o SDK do Mailgun para o Mailroomly

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

// Node
const Mailgun = require('mailgun.js')
const FormData = require('form-data')

const mg = new Mailgun(FormData).client({
  username: 'api',
  key: process.env.MAILROOMLY_API_KEY,
  url: 'https://app.mailroomly.com',
})

// PHP
$mg = Mailgun::create(getenv('MAILROOMLY_API_KEY'), 'https://app.mailroomly.com');

Os outros SDK têm a mesma definição, o URL base da API, onde estava https://api.mailgun.net (ou https://api.eu.mailgun.net). Sem SDK, envie o mesmo pedido para https://app.mailroomly.com/v3/{domain}/messages, com a chave como palavra-passe do utilizador api.

O email segue como email transacional. Para enviar email de marketing, use uma chave limitada ao marketing: os destinatários podem então cancelar a subscrição, e %unsubscribe_url% passa a ser a ligação própria de cada destinatário para o fazer (Aplicações e chaves).

3. Mudar os webhooks

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

1. URL do webhook: o endpoint que recebia os webhooks do Mailgun. O Mailgun define um URL por evento; aqui, um único URL recebe todos os eventos que a aplicação escolhe, por isso escolha o endpoint cujo handler lê o campo event, ou dê a cada handler a sua própria aplicação.
2. Formato do conteúdo: Compatível com Mailgun (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. Uma devolução, um atraso e um destinatário deixado de fora chegam como o evento failed do Mailgun.
4. Guardar alterações e depois Enviar um evento de teste, para ver o que o seu endpoint responde.
5. Em Detalhes avançados, escolha Mostrar segredo e copie o Segredo de assinatura (para verificar os webhooks que recebe) para o seu handler de webhooks, onde estava a webhook signing key do Mailgun.

Rodar segredo substitui o segredo de imediato: o seu handler só consegue verificar os webhooks quando tiver o novo, por isso coloque-o lá logo depois de rodar. As entregas que recusar entretanto são repetidas.

O email recebido chega como formulário (multipart/form-data com anexos, application/x-www-form-urlencoded sem, como o Mailgun o envia) e os eventos como JSON, por isso um só handler distingue-os. Se o seu handler de webhooks e o de routes 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 Mailgun

Para uma aplicação que recebia email por uma route do Mailgun que o reencaminhava para um URL:

1. Passe o domínio a Envio e receção (O que este domínio faz, nas Definições), normalmente o mesmo subdomínio a que a route correspondia, 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 routes tem um URL próprio. Os pedidos chegam tal como a route os reencaminhava, assinados como o Mailgun os assina, com o segredo de assinatura da aplicação.
3. Se a route correspondia a 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 recipient.
4. Mude os registos 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 dos registos 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 o:testmode=yes: a resposta é Queued. Thank you. e nada é enviado. Depois envie um a sério: 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 Mailgun, os registos DNS, os webhooks e as routes até a mudança estar concluída. Para voltar, reponha os dois valores, o URL da API e a chave: a aplicação volta a enviar pelo Mailgun em poucos minutos. Para a receção, aponte de novo os registos MX para o Mailgun. O email já aceite pelo Mailroomly continua a ser enviado e fica na Atividade.

O que é diferente

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