De Postmark a Postal, y lo que no tiene equivalente

Añade el dominio en el panel (o con POST /domains), crea en tu DNS los registros que muestra Postal y solicita la verificación. Postal firma con DKIM en el selector postal y usa un subdominio postal para el Return-Path, así que comprueba que ninguno de tus registros use ya esos nombres y conserva los de Postmark hasta que termine el cambio.

• El token del servidor, que solo envía, corresponde a una clave solo de envío. Quien además gestiona plantillas, supresiones y webhooks por API necesita una clave de acceso total.
• La clave puede restringirse a un dominio, lo que ayuda a separar sistemas. El token completo aparece una única vez, al crearla.
• Región: Postal envía desde São Paulo de forma predeterminada y permite elegir us-east-1, us-east-2, eu-west-1 o ap-northeast-1 en cada dominio.

Los campos cambian de nombre y la clave cambia de encabezado. También cambia la forma de saber si salió bien: Postmark responde con ErrorCode en el cuerpo, y Postal usa el estado HTTP y un error con statusCode, name y message. La respuesta de éxito es solo {"id": "…"}. Con el encabezado Idempotency-Key, repetir una solicitud no duplica el envío.

- curl "https://api.postmarkapp.com/email" \-   -X POST \-   -H "Accept: application/json" \-   -H "Content-Type: application/json" \-   -H "X-Postmark-Server-Token: $POSTMARK_SERVER_TOKEN" \-   -d '{-     "From": "[email protected]",-     "To": "[email protected]",-     "Subject": "Tu pedido #10482 salió para la entrega",-     "HtmlBody": "<p>El pedido <b>#10482</b> está en camino.</p>",-     "Tag": "envío",-     "MessageStream": "outbound"-   }'+ curl -X POST https://api.postal.so/emails \+   -H "Authorization: Bearer $POSTAL_API_KEY" \+   -H "Content-Type: application/json" \+   -d '{+     "from": "Aurora Cosméticos <[email protected]>",+     "to": ["[email protected]"],+     "subject": "Tu pedido #10482 salió para la entrega",+     "html": "<p>El pedido <b>#10482</b> está en camino.</p>",+     "tags": [{"name": "stream", "value": "transactional"}]+   }'

- const response = await fetch('https://api.postmarkapp.com/email', {-   method: 'POST',-   headers: {-     Accept: 'application/json',-     'Content-Type': 'application/json',-     'X-Postmark-Server-Token': process.env.POSTMARK_SERVER_TOKEN,-   },-   body: JSON.stringify({-     From: '[email protected]',-     To: '[email protected]',-     Subject: 'Tu pedido #10482 salió para la entrega',-     HtmlBody: '<p>El pedido <b>#10482</b> está en camino.</p>',-     MessageStream: 'outbound',-   }),- });- const { MessageID, ErrorCode } = await response.json();+ const response = await fetch('https://api.postal.so/emails', {+   method: 'POST',+   headers: {+     Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,+     'Content-Type': 'application/json',+     'Idempotency-Key': 'order-10482-shipped',+   },+   body: JSON.stringify({+     from: 'Aurora Cosméticos <[email protected]>',+     to: ['[email protected]'],+     subject: 'Tu pedido #10482 salió para la entrega',+     html: '<p>El pedido <b>#10482</b> está en camino.</p>',+     tags: [{ name: 'stream', value: 'transactional' }],+   }),+ });+ if (!response.ok) { /* estado HTTP y cuerpo { statusCode, name, message } */ }+ const { id } = await response.json();

Las plantillas de Postmark aceptan bloques y repeticiones, como {{#each person}}, y el modelo (TemplateModel) es un objeto que puede contener otros objetos. Las de Postal solo sustituyen variables, con el formato {{{NOME}}}, con tres llaves, y cada valor debe ser texto o número. Cuando tu plantilla depende de bloques, pasa la lógica al código: elige entre plantillas o arma tú mismo el HTML y envíalo en html.

• En Postal editas un borrador y lo publicas; los envíos usan siempre la última versión publicada, y las versiones antiguas se pueden restaurar.
• Postal también tiene layouts, para reutilizar diseños de correo electrónico. No los trates como idénticos a los layouts de Postmark: recréalos y pruébalos.
• En el HTML los valores se escapan. Una variable sin valor y sin valor predeterminado (fallback_value) devuelve un error 422.

- <p>¡Hola, {{name}}!</p>- <p>Tu pedido: {{order.id}}</p>+ <p>¡Hola, {{{NAME}}}!</p>+ <p>Tu pedido: {{{ORDER}}}</p>

- "TemplateAlias": "pedido-enviado",- "TemplateModel": { "name": "Ana", "order": { "id": 10482 } }+ "template": {+   "id": "pedido-enviado",+   "variables": { "NAME": "Ana", "ORDER": "10482" }+ }

En Postmark, un servidor tiene streams: transaccional (de forma predeterminada, outbound), de broadcasts y de entrada, hasta 10 en total, y las supresiones se guardan por stream. Postal no tiene ese objeto. Los tres usos tienen un camino, pero ninguno es un campo del envío, y la separación de supresiones no existe: la lista es única para el equipo.

• Para aislar la reputación, usa dominios o subdominios distintos (uno para lo transaccional, otro para las campañas) y una clave restringida a cada dominio.
• La pausa por una tasa alta de rebotes o quejas vale para todo el equipo, no para un dominio ni una etiqueta. Consulta los límites de reputación en Límites.
• Si tu uso depende de streams separados con supresiones independientes, habla con nosotros antes de migrar.

Si algún sistema envía por SMTP, cambia servidor, usuario y contraseña y quita los encabezados X-PM-*. Los mensajes pasan por las mismas reglas de la API (dominio verificado, cuotas, lista de supresión) y aparecen en Correos y Registros.

- host: 'smtp.postmarkapp.com',- port: 587,- secure: false,- auth: { user: process.env.POSTMARK_SERVER_TOKEN, pass: process.env.POSTMARK_SERVER_TOKEN },+ host: 'smtp.postal.so',+ port: 465,+ secure: true,+ auth: { user: 'postal', pass: process.env.POSTAL_API_KEY },

Crea el endpoint en Postal (POST /webhooks, con URL HTTPS y la lista de eventos) y guarda el signing_secret. El cambio de fondo es la seguridad: Postmark no firma las entregas, y Postal firma todas. Calcula la firma sobre el cuerpo exactamente como llegó, sin leer y reescribir el JSON.

• El webhook-id es el mismo en todos los intentos: guarda los ya procesados para descartar duplicados.
• Responde 2xx enseguida y procesa después, en una cola.
• Para probar sin enviar de verdad, envía correos electrónicos a las direcciones de prueba o usa "Enviar evento de prueba" en el panel.

- if (req.body.RecordType === 'Bounce') {-   // req.body.Email, req.body.MessageID- }+ const event = verifyWebhook(req.body, req.headers, process.env.POSTAL_WEBHOOK_SECRET);+ if (event.type === 'email.bounced') {+   // event.data.to, event.data.email_id+ }

{
  "type": "email.bounced",
  "created_at": "2026-10-24T13:02:15.004Z",
  "data": {
    "email_id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
    "to": ["[email protected]"],
    "subject": "Tu pedido #10482 salió para la entrega",
    "tags": { "stream": "transactional" },
    "bounce": {
      "type": "Permanent",
      "subType": "General",
      "message": "smtp; 550 5.1.1 user unknown"
    }
  }
}

Hazlo antes del primer envío real, para no escribir a quien ya pidió la baja ni repetir rebotes. Postal pausa los envíos del equipo si los rebotes permanentes superan el límite del nivel de la reputación de la cuenta (3% en una cuenta nueva) o las quejas superan el 0,3%; por eso importa una lista limpia. El ejemplo lee la lista de un stream de Postmark y la envía a Postal en bloques de 100. Repite para cada stream y usa una clave de acceso total.

- const base = 'https://api.postmarkapp.com/message-streams';- const dump = await fetch(`${base}/${stream}/suppressions/dump`, {-   headers: {-     Accept: 'application/json',-     'X-Postmark-Server-Token': process.env.POSTMARK_SERVER_TOKEN,-   },- }).then((r) => r.json());- const emails = dump.Suppressions.map((s) => s.EmailAddress);+ for (let i = 0; i < emails.length; i += 100) {+   await fetch('https://api.postal.so/suppressions/batch/add', {+     method: 'POST',+     headers: {+       Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,+       'Content-Type': 'application/json',+     },+     body: JSON.stringify({ emails: emails.slice(i, i + 100) }),+   });+ }

Los ID son diferentes: el MessageID de un correo de Postmark no existe en Postal. Durante el cambio, guarda de qué proveedor salió cada correo y sigue recibiendo los webhooks de Postmark para lo que salió por allí. Envía cada flujo por un solo proveedor, para no duplicar ni pausar todo por culpa de correos equivocados.