Migrar de SendGrid a Postal

Registra el dominio en el panel y crea los registros que muestra. Por sus nombres, los registros de Postal no chocan con los de SendGrid, y los dos quedan verificados al mismo tiempo durante el cambio. Si ya tienes un _dmarc, conserva el tuyo.

• Postal comprueba los registros por sí sola durante hasta 72 horas y avisa por webhook (domain.updated)
• Crea una clave de API (empieza con ps_). Para sistemas que solo envían, usa una clave solo de envío, restringida al dominio

Postal no acepta el formato /v3/mail/send: la llamada pasa a ser POST /emails, con los campos en el primer nivel. A continuación, el mismo correo electrónico en los dos formatos. Quien usa el SDK de SendGrid cambia el envío por el SDK de Postal (Node.js, PHP y Laravel) o por HTTP, que es JSON con la clave en el encabezado Authorization.

• SendGrid responde 202 Accepted; Postal responde 200 con el id del correo electrónico. Guarda el id: es el que aparece en los webhooks y en GET /emails/{id}
• Varios destinatarios en el mismo to forman un único correo electrónico en el que todos se ven. Para un correo por persona, usa el envío por lotes
• Repetir la llamada con la misma Idempotency-Key no duplica el envío

Antes: SendGrid

POST https://api.sendgrid.com/v3/mail/send
Authorization: Bearer <clave de SendGrid>

{
  "personalizations": [{
    "to": [{ "email": "[email protected]", "name": "Ana" }],
    "custom_args": { "order_id": "10482" }
  }],
  "from": { "email": "[email protected]", "name": "Loja Exemplo" },
  "subject": "Tu pedido #10482 salió para la entrega",
  "content": [
    { "type": "text/plain", "value": "El pedido #10482 está en camino." },
    { "type": "text/html", "value": "<p>El pedido <b>#10482</b> está en camino.</p>" }
  ],
  "categories": ["entrega"]
}

Después: Postal

POST https://api.postal.so/emails
Authorization: Bearer ps_sua_chave
Idempotency-Key: pedido-10482-saiu

{
  "from": "Loja Exemplo <[email protected]>",
  "to": ["Ana <[email protected]>"],
  "subject": "Tu pedido #10482 salió para la entrega",
  "text": "El pedido #10482 está en camino.",
  "html": "<p>El pedido <b>#10482</b> está en camino.</p>",
  "tags": [
    { "name": "category", "value": "entrega" },
    { "name": "order_id", "value": "10482" }
  ]
}

En el código

- const sgMail = require('@sendgrid/mail');- sgMail.setApiKey(process.env.SENDGRID_API_KEY);- await sgMail.send({-   to: '[email protected]',-   from: '[email protected]',-   subject, html,- });+ import { Postal } from 'postal-so';+ const postal = new Postal(); // lee POSTAL_API_KEY+ await postal.emails.send({+   from: 'Loja Exemplo <[email protected]>',+   to: '[email protected]',+   subject, html,+ });

La tabla sirve para el código nuevo y como lista de comprobación de lo que usa hoy tu sistema. Las filas que cambian la forma de armar el correo electrónico son las de destinatarios por lotes, categorías y argumentos personalizados.

Quien envía por SMTP no reescribe nada: cambia el servidor, el usuario y la contraseña. El usuario fijo es postal, y no apikey. Postal también acepta 2465 (TLS) y 2587 (STARTTLS) para redes que bloquean los puertos habituales.

• El encabezado X-SMTPAPI (category, unique_args, sub, send_at, filters…) no lo interpreta Postal: sigue como un encabezado común. Lo que uses de él tiene que pasar a la API
• Los destinatarios son los del sobre (RCPT TO), hasta 50 por mensaje. Quien no aparece en To ni en Cc se trata como Bcc
• El SMTP de Postal no tiene etiquetas, programación ni plantillas. Cuotas, lista de supresión, eventos y webhooks son los mismos de la API
• Mensajes de hasta 40 MB; Postal responde 250 2.0.0 OK queued as <id>, y el id es el del correo electrónico en la API

- Servidor: smtp.sendgrid.net- Puerto: 587 (o 25, 2525, 465)- Usuario: apikey- Contraseña: la clave de API de SendGrid+ Servidor: smtp.postal.so+ Puerto: 465 (TLS directo) o 587 (STARTTLS)+ Usuario: postal+ Contraseña: la clave de API de Postal (ps_…)

SendGrid envía el Event Webhook firmado con una clave pública (ECDSA); Postal firma con un secreto por endpoint, en el estándar Standard Webhooks. El cuerpo también cambia: un evento por solicitud, con el correo electrónico dentro de data.

import express from 'express';
import { verifyWebhook, PostalWebhookVerificationError } from 'postal-so';

const app = express();
// El cuerpo debe llegar crudo (Buffer) para que la firma coincida.
app.post('/webhooks/postal', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = verifyWebhook(req.body, req.headers, process.env.POSTAL_WEBHOOK_SECRET);
    if (event.type === 'email.bounced') {
      // descarta la dirección
    }
    res.sendStatus(200);
  } catch (error) {
    if (error instanceof PostalWebhookVerificationError) {
      return res.sendStatus(400);
    }
    throw error;
  }
});

Primero la lista de supresión, para no escribir a quien no debe recibir. Después los contactos, si usas la audiencia de marketing. SendGrid exporta cada tipo de supresión por una ruta propia; Postal tiene una sola lista.

• Haz la importación de contactos después de la supresión: las direcciones que ya están en la lista de supresión se ignoran y no usan el límite de contactos del plan
• Las campañas y automatizaciones de marketing hay que recrearlas en Postal; lo que llevas son los contactos y el contenido

curl -X POST https://api.postal.so/suppressions/batch/add \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["[email protected]", "[email protected]"]}'

Con el dominio verificado en las dos, pasa un flujo cada vez. Invitaciones, restablecimientos de contraseña y códigos deben salir por un solo camino cada vez.

• Los IDs son de cada plataforma: guarda de qué proveedor salió cada correo electrónico y sigue recibiendo eventos de SendGrid de lo que salió por allí
• Usa tags (por ejemplo, provider: postal) para separar los correos nuevos en los webhooks
• Las cuentas nuevas empiezan con un tope de 500 correos por día, que crece con la reputación de la cuenta, y los envíos se pausan con rebotes permanentes por encima del 3% al 5%, según el nivel, o quejas por encima del 0,3%: sube el volumen por etapas