De Mailgun a Postal, campo a campo

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. Los registros usan nombres propios, postal._domainkey y el subdominio postal, así que puedes publicarlos junto a los de Mailgun y quitar los antiguos solo después del cambio. Antes, comprueba que ninguno de tus registros use ya esos nombres.

• Región: Mailgun tiene dos URL, US y EU. En Postal la URL es una sola y la región se elige por dominio: São Paulo (predeterminada), us-east-1, us-east-2, eu-west-1 o ap-northeast-1.
• Para sistemas que solo envían, crea una clave solo de envío, restringida al dominio. El token completo aparece una única vez, al crearla.
• Si el dominio principal ya envía por Mailgun, usa un subdominio dedicado en Postal.

En Mailgun el dominio va en la URL y los campos van en form-data. En Postal el dominio sale del from y el cuerpo es JSON. La respuesta es {"id": "…"}: guarda el ID, que vuelve en los webhooks como data.email_id y sirve para consultar el correo electrónico en GET /emails/{id}. Con el encabezado Idempotency-Key, repetir una solicitud no duplica el envío.

- curl -s --user 'api:$MAILGUN_API_KEY' \-   https://api.mailgun.net/v3/mg.exemplo.com.br/messages \-   -F from='Aurora Cosméticos <[email protected]>' \-   -F [email protected] \-   -F subject='Tu pedido #10482 salió para la entrega' \-   --form-string html='<p>El pedido <b>#10482</b> está en camino.</p>' \-   -F o:tag='envío'+ 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": "category", "value": "shipping"}]+   }'

- const form = new FormData();- form.append('from', 'Aurora Cosméticos <[email protected]>');- form.append('to', '[email protected]');- form.append('subject', 'Tu pedido #10482 salió para la entrega');- form.append('html', '<p>El pedido <b>#10482</b> está en camino.</p>');- form.append('o:tag', 'envío');- const auth = Buffer.from('api:' + process.env.MAILGUN_API_KEY).toString('base64');- await fetch('https://api.mailgun.net/v3/mg.exemplo.com.br/messages', {-   method: 'POST',-   headers: { Authorization: `Basic ${auth}` },-   body: form,- });+ 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: 'category', value: 'shipping' }],+   }),+ });+ const { id } = await response.json();

Las plantillas de Mailgun usan una versión de Handlebars, con condiciones (if, unless), bucles (each), with y equal. Las de Postal solo sustituyen variables: {{{NOME}}}, con tres llaves, y el valor debe ser texto o número. No hay condiciones, bucles ni objetos anidados. Cuando tu plantilla depende de lógica, pásala al código: elige entre dos 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.
• En el HTML los valores se escapan. Una variable sin valor y sin valor predeterminado (fallback_value) devuelve un error 422.
• Declara las variables al crear la plantilla: hasta 50, de tipo texto o número.

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

- -F template='pedido-enviado' \- -F t:variables='{"name": "Ana", "order": "10482"}'+ "template": {+   "id": "pedido-enviado",+   "variables": {"NAME": "Ana", "ORDER": "10482"}+ }

Si algún sistema envía por SMTP, cambia servidor, usuario y contraseña. El SMTP forma parte del plan. Los mensajes pasan por las mismas reglas de la API (dominio verificado, cuotas, lista de supresión) y aparecen en Correos y Registros.

• Límites de Postal por mensaje: 40 MB y 50 destinatarios. Quien los supere recibe un error; divide el envío.

- host: 'smtp.mailgun.org',- port: 587,- secure: false,- auth: { user: '[email protected]',-   pass: process.env.MAILGUN_SMTP_PASSWORD },+ host: 'smtp.postal.so',+ port: 465,+ secure: true,+ auth: { user: 'postal', pass: process.env.POSTAL_API_KEY },

Crea el endpoint en Postal y guarda el signing_secret. La firma cambia por completo: en Mailgun viene en el cuerpo y usa una clave de firma de webhooks; en Postal viene en encabezados y usa el secreto de cada endpoint. Calcúlala 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.

- const expected = crypto.createHmac('sha256', process.env.MAILGUN_SIGNING_KEY)-   .update(timestamp + token).digest('hex');- if (expected !== signature) return res.sendStatus(401);+ import { verifyWebhook } from 'postal-so';+ const event = verifyWebhook(req.body, req.headers, process.env.POSTAL_WEBHOOK_SECRET);

{
  "type": "email.delivered",
  "created_at": "2026-10-24T13:02:14.120Z",
  "data": {
    "email_id": "019a1b2c-4d5e-7f60-8a9b-0c1d2e3f4a5b",
    "from": "Aurora Cosméticos <[email protected]>",
    "to": ["[email protected]"],
    "subject": "Tu pedido #10482 salió para la entrega",
    "tags": { "category": "shipping" }
  }
}

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.

Los ID son diferentes: el ID de un correo de Mailgun no existe en Postal. Durante el cambio, guarda de qué proveedor salió cada correo y sigue recibiendo los webhooks de Mailgun 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.