De Brevo a Postal, sin llevarte lo que no es correo electrónico

Antes de cambiar cualquier cosa, enumera lo que tu sistema usa en Brevo. Cada elemento tiene un lugar en Postal, o no lo tiene, y es mejor descubrirlo ahora.

En Dominios, Postal muestra pocos registros para que quien se ocupa del DNS los copie, y los verifica sola hasta por 72 horas. El dominio puede seguir autenticado en Brevo al mismo tiempo: los nombres de los registros son diferentes.

• Copia los valores de la pantalla de tu Brevo: los de la tabla son ejemplos de la documentación, y tu código de verificación es único.
• Como los nombres son diferentes (mail._domainkey en el ejemplo de Brevo, postal._domainkey en Postal), los dos siguen siendo válidos durante el cambio. Verifica si algún nombre de tu cuenta es igual antes de publicar.
• Postal avisa por el webhook domain.updated cuando el dominio pasa a verified. Consulta Dominios y DNS.

Postal no acepta el formato de Brevo. La llamada pasa a ser POST /emails, con la clave en Authorization: Bearer en lugar del encabezado api-key, y los campos cambian de nombre. Abajo, el mismo correo electrónico en los dos formatos.

POST https://api.brevo.com/v3/smtp/email
api-key: <clave de Brevo>
Content-Type: application/json

{
  "sender": { "name": "Aurora Cosméticos", "email": "[email protected]" },
  "to": [{ "email": "[email protected]", "name": "Ana" }],
  "subject": "Tu pedido #10482 salió para la entrega",
  "htmlContent": "<p>El pedido <b>#10482</b> está en camino.</p>",
  "textContent": "El pedido #10482 está en camino.",
  "tags": ["entrega"]
}

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

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

• Sin templateId, Brevo exige sender, subject y htmlContent. Postal exige from, subject y html o text.
• Postal añade el encabezado Idempotency-Key: repetir la llamada con la misma clave y el mismo cuerpo, en un plazo de 24 horas, devuelve la respuesta de la primera y no envía de nuevo. Consulta Idempotencia.
• La documentación de Postal no trata la IP dedicada. Si usas el campo sender.ip en Brevo, habla con nosotros por el formulario de contacto antes de migrar.
• ¿Prefieres un SDK? Los de Postal (Node.js, PHP y Laravel) usan esta misma API. Consulta SDKs y CLI y la referencia de correos.

Los sistemas que hablan SMTP, como WordPress, los ERP y las plataformas de tienda, cambian cuatro campos: servidor, puerto, usuario y contraseña. En Brevo la contraseña es una clave SMTP, y no la clave de API. En Postal es una clave de API.

- MAIL_HOST=smtp-relay.brevo.com- MAIL_PORT=587- MAIL_USERNAME=<login SMTP do Brevo>- MAIL_PASSWORD=<chave SMTP do Brevo>+ MAIL_SCHEME=smtps+ MAIL_HOST=smtp.postal.so+ MAIL_PORT=465+ MAIL_USERNAME=postal+ MAIL_PASSWORD=ps_sua_chave

• En Postal, la autenticación (AUTH PLAIN o AUTH LOGIN) viene siempre después de TLS.
• El SMTP de Postal no tiene etiquetas, programación ni plantillas: para eso, usa la API. Si tu sistema manda encabezados propios de Brevo para esas funciones, Postal no los interpreta y siguen como encabezados comunes.
• Los envíos por SMTP siguen las mismas reglas de la API (dominio verificado, cuotas y supresión) y aparecen en Correos y Registros. Consulta la guía de SMTP.

Postal no convierte plantillas de otra plataforma, pero el HTML viene por la API de Brevo. El script de abajo lista las plantillas activas, cambia {{params.nome}} por {{{nome}}} y crea cada una como plantilla, con el alias brevo-<id>. Es un punto de partida: revisa el resultado antes de publicar la tuya.

const brevoHeaders = { 'api-key': process.env.BREVO_API_KEY }
const postalHeaders = {
  Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  'Content-Type': 'application/json',
}

// {{params.nome}} de Brevo pasa a ser {{{nome}}} en Postal
const convert = (text) => text.replace(/\{\{\s*params\.(\w+)\s*\}\}/g, '{{{$1}}}')

const url = 'https://api.brevo.com/v3/smtp/templates?templateStatus=true&limit=100'
const response = await fetch(url, { headers: brevoHeaders })
const { templates } = await response.json()

for (const template of templates) {
  const created = await fetch('https://api.postal.so/templates', {
    method: 'POST',
    headers: postalHeaders,
    body: JSON.stringify({
      name: template.name,
      alias: `brevo-${template.id}`,
      subject: convert(template.subject),
      html: convert(template.htmlContent),
    }),
  })
  if (!created.ok) throw new Error(await created.text())

  const { id } = await created.json()
  await fetch(`https://api.postal.so/templates/${id}/publish`, { method: 'POST', headers: postalHeaders })
}

• Brevo solo acepta params en las plantillas del “nuevo lenguaje de plantillas” (New Template Language). Las plantillas más antiguas deben revisarse a mano.
• Los valores de params que son listas u objetos no pasan: en Postal, cada variable es texto o número, y una variable sin valor y sin valor predeterminado devuelve 422. Declara las opcionales con fallback_value.
• La respuesta de Brevo trae el remitente (sender) de cada plantilla. En Postal, viene de from en el envío, o del remitente predeterminado que guardes en la plantilla.
• El envío usa siempre la última versión publicada. Consulta la referencia de plantillas; el plan define cuántas plantillas tiene el equipo.

Los eventos principales existen en ambos lados, con otros nombres y otro cuerpo. En Brevo, la documentación que consultamos no describe firma: autentica con usuario y contraseña en la URL, token Bearer, encabezados propios o lista de IP. En Postal, cada entrega viene firmada con el secreto del endpoint.

• Crea el endpoint en Webhooks (panel o POST /webhooks) y guarda el signing_secret. Manda un evento de prueba desde el panel antes de pasar el tráfico.
• Las direcciones de prueba ([email protected], [email protected] y otras) generan webhooks reales, sin usar la cuota. Dependen del plan.
• Quita los webhooks de Brevo solo después de pasar todo el tráfico: los correos electrónicos que aún salen por allí siguen generando eventos.

Haz esto antes de importar contactos: una dirección que está en la lista de supresión nunca se convierte en contacto. Brevo lista, por API, los contactos bloqueados o dados de baja de los correos electrónicos transaccionales, con el motivo de cada uno.

const reasonsToSuppress = new Set(['hardBounce', 'contactFlaggedAsSpam'])
const emails = []

for (let offset = 0; ; offset += 100) {
  const url = `https://api.brevo.com/v3/smtp/blockedContacts?limit=100&offset=${offset}`
  const response = await fetch(url, { headers: { 'api-key': process.env.BREVO_API_KEY } })
  const { contacts = [] } = await response.json()
  if (contacts.length === 0) break

  for (const contact of contacts) {
    if (reasonsToSuppress.has(contact.reason?.code)) emails.push(contact.email.toLowerCase())
  }
}

for (let i = 0; i < emails.length; i += 100) {
  const response = 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) }),
  })
  if (!response.ok) throw new Error(await response.text())
  await new Promise((resolve) => setTimeout(resolve, 250)) // respeita o limite do plano
}

• La ruta es GET /v3/smtp/blockedContacts, con hasta 100 por página. Cada elemento trae email, blockedAt y reason.code. El script lleva solo los dos motivos de entrega y deja los demás para que tú decidas.
• En Postal, las direcciones entran con el origen manual: la diferencia entre rebote y queja no se guarda. La clave debe ser de acceso total. Consulta la referencia de supresiones.
• Brevo también tiene una lista de dominios bloqueados. La lista de supresión de Postal guarda direcciones, y no dominios enteros: si necesitas eso, rechaza el dominio en tu formulario o en tu sistema.

El panel de Brevo exporta contactos en CSV, y la API también. En CRM, Contacts, selecciona los contactos y usa More actions, Export, eligiendo los atributos. Por la API, la solicitud de abajo genera el archivo y avisa a tu notifyUrl cuando esté listo.

POST https://api.brevo.com/v3/contacts/export
api-key: <chave do Brevo>
Content-Type: application/json

{
  "customContactFilter": { "actionForContacts": "subscribed", "listId": 12 },
  "exportAttributes": ["FIRSTNAME", "LASTNAME"],
  "notifyUrl": "https://exemplo.com.br/hooks/brevo-export"
}

• En actionForContacts, la API acepta allContacts, subscribed, unsubscribed y unsubscribedPerList. También hay que indicar listId, segmentId, modifiedSince o createdSince (fecha completa, con zona horaria). Exporta suscritos y dados de baja en archivos separados.
• Sin CSV, GET /v3/contacts (hasta 1.000 por página) y GET /v3/contacts/lists/{id}/contacts (hasta 500) devuelven JSON con attributes, listIds, listUnsubscribed y emailBlacklisted.
• Dados de baja: en su archivo, deja una columna Dado de baja con sim en todas las filas y apunta esa columna al campo Dado de baja (sí/no). Quien tenía emailBlacklisted verdadero entra aquí, y nunca como suscrito.
• Listas: exporta una lista por archivo e importa cada uno eligiendo el segmento. Solo los segmentos estáticos reciben contactos importados. Quien salió de una sola lista (listUnsubscribed) merece cuidado: si la lista pasó a ser un tema, registra la elección opt_out de esas personas con PATCH /contacts/{id}/topics.
• Crea antes las Propiedades de los atributos que quieres mantener: la importación no crea propiedades nuevas. Si usas un ID propio (ext_id) y viene en el archivo, apúntalo al campo de ID externo.
• Deja desactivada la opción Disparar automatizaciones. Los contactos que ya existen se actualizan por el correo electrónico, y cada archivo puede tener hasta 20 MB. El límite de contactos del plan está en Precios: en Gratis son 1.000, en Profesional 5.000 y en Escala 50.000.
• Antes de enviar, pasa la lista por la Verificación de correos.

Las campañas y automatizaciones no pasan solas. No encontramos en la documentación de Brevo una exportación de ellas a otra plataforma, así que trata cada una como nueva y aprovecha para revisar lo que aún tiene sentido.

• Las importaciones no inician automatizaciones, a menos que actives esa opción. Revisa quién entraría antes de activar.
• Cada plan tiene un límite de ejecuciones de automatizaciones por mes.

Pasa un flujo a la vez, con Brevo aún activo. Empieza por las direcciones de prueba y por ti mismo, compara entregas y rebotes en los primeros días y solo entonces pasa el resto.