Mudar do Postmark

O que se mantém

O Mailroomly fala a API de envio do Postmark e os seus formatos de webhook:

• Os endpoints. POST /email envia um email e POST /email/batch até 500, na raiz de https://app.mailroomly.com (não em /api/v1). Aceitam o pedido do Postmark (From, To, Cc, Bcc, Subject, HtmlBody, TextBody, ReplyTo, Tag, Metadata, Headers, Attachments, TrackOpens, TrackLinks, MessageStream) e respondem na forma do Postmark, com ErrorCode 0 e um MessageID quando corre bem.
• O cabeçalho do token. A chave de API de uma aplicação vai em X-Postmark-Server-Token, onde estava o server token do Postmark. Authorization: Bearer também funciona.
• Os message streams. Um MessageStream com broadcast no nome (broadcast, broadcasts, my-broadcast-stream) envia email de marketing; qualquer outro, ou nenhum, envia email transacional.
• As ligações para cancelar a subscrição. No email de marketing, {{{ pm:unsubscribe }}} passa a ser a ligação própria de cada destinatário, e cada cópia leva cabeçalhos de cancelamento com um clique.
• Os webhooks. Com o formato Compatível com Postmark, os eventos chegam como os registos do Postmark: Delivery, Bounce, SpamComplaint, Open, Click, SubscriptionChange, e o JSON de receção do Postmark para o email recebido, com os anexos.

Todos os campos e registos: Postmark 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 Postmark 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. Os endereços inativos do Postmark (devoluções permanentes, queixas de spam, cancelamentos da subscrição) não passam sozinhos. Exporte-os do Postmark e bloqueie-os em Atividade › Bloqueados › Bloquear um endereço, ou pela API, antes do primeiro envio (Bloqueados). Bloqueie as devoluções permanentes e as queixas para todos os tipos de email, e os cancelamentos da subscrição para o marketing.
• Modelos. O Mailroomly não tem modelos: uma aplicação que envia com TemplateId ou TemplateAlias prepara o HTML e o texto antes de enviar.

Passar uma aplicação

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

1. Criar a aplicação e a chave

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

A chave, que começa por mp_live_, substitui o server token do Postmark. 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 seu código para o Mailroomly

Mude dois valores na configuração da aplicação: o endereço para onde envia e o token. O pedido fica igual.

# Antes
curl https://api.postmarkapp.com/email \
  -H "X-Postmark-Server-Token: $POSTMARK_SERVER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"From": "…", "To": "…", "Subject": "…", "TextBody": "…", "MessageStream": "outbound"}'

# Depois
curl https://app.mailroomly.com/email \
  -H "X-Postmark-Server-Token: $MAILROOMLY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"From": "…", "To": "…", "Subject": "…", "TextBody": "…", "MessageStream": "outbound"}'

Com uma biblioteca do Postmark que permite mudar o endereço base, indique https://app.mailroomly.com. Os lotes vão para /email/batch no mesmo endereço.

Confirme cada MessageStream que a aplicação usa: um stream transacional com broadcast no nome, ou um stream de marketing sem ele, tem de ser renomeado na aplicação.

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 Postmark.
2. Formato do conteúdo: Compatível com Postmark (o guia já o escolheu).
3. Eventos a enviar: marque o que o endpoint trata: Entregue, Devolvida, Queixa, Aberta, Clicada, Cancelou a subscrição, Entrega atrasada e Mensagem recebida.
4. Guardar alterações e depois Enviar um evento de teste, para ver o que o seu endpoint responde.

Um único URL recebe todos os eventos que a aplicação escolhe; o Postmark permitia um URL por stream e por tipo. O URL não pode levar nome de utilizador e palavra-passe: se o seu endpoint dependia deles, confirme antes a assinatura que o Mailroomly envia com cada webhook (Webhooks).

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

Para uma aplicação que recebia email pelo webhook de receção do Postmark:

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 Postmark, nunca um domínio cujo email está noutro serviço (Endereços e domínios).
2. Crie o endereço que recebe, escolha a aplicação como Aplicação responsável e indique um URL do webhook de receção: o endpoint de receção atual da aplicação. Os pedidos chegam no JSON de receção do Postmark, assinados com o segredo da aplicação.
3. Se a aplicação usava endereços com + (resposta+pedido42@…), torne esse endereço o Endereço geral do domínio: a parte depois do + chega em MailboxHash.
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 uma mensagem a partir da aplicação. A resposta traz ErrorCode 0 e um MessageID, 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 o servidor do Postmark, os registos DNS e os webhooks até a mudança estar concluída. Para voltar, reponha os dois valores, o endereço e o token: a aplicação volta a enviar pelo Postmark em poucos minutos. Para a receção, aponte de novo o registo MX para o Postmark. 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: Postmark compatibility (em inglês).