Sign inGet Started

Migrar desde otro proveedor

Usa esta guía para trasladar el email de producción desde otro proveedor. Adapta la solicitud de envío, publica los registros DNS, importa las supresiones, traduce los eventos de webhook y prueba la integración antes de dirigir el tráfico de producción a Bird.

Lista de verificación de la migración:

  1. Adapta tu llamada de envío a POST /v1/email/messages
  2. Redirige tus dominios de envío y DNS
  3. Importa tu lista de supresión
  4. Cambia los webhooks a nuestro vocabulario de eventos
  5. Verifica contra el sandbox de correo antes del corte

Los pasos 1, 3 y 4 dependen de qué proveedor estás dejando. Tu guía del proveedor tiene el mapeo campo por campo del payload, dónde exportar tu lista de supresión y la tabla de traducción de nombres de eventos de webhook.

1. Adapta la llamada de envío

Tenemos un solo endpoint de envío, POST /v1/email/messages. Construyes un payload JSON plano (sin wrapper personalizations, sin ensamblaje MIME) con from, arrays to/cc/bcc, subject, html y/o text, una lista opcional de reply_to y headers para encabezados de email personalizados. Un envío exitoso devuelve 202 Accepted con un ID de mensaje con prefijo em_. Los resultados de entrega llegan de forma asíncrona a través de webhooks y los endpoints de lectura. El payload completo, con cada límite de campo y valor por defecto, está en Envío de email. El mapeo campo por campo desde tu payload actual está en tu guía del proveedor. Si tu aplicación envía por SMTP hoy, puede que no necesites portar la llamada: aceptamos envío por SMTP en el mismo pipeline, lo que convierte este paso en un cambio de credenciales.

Usa tags para dimensiones de filtrado en listas de mensajes, analíticas y resúmenes del dashboard. Usa metadata para contexto estructurado que Bird almacena en el mensaje y devuelve en lecturas de API. Los eventos de webhook también pueden incluir este contexto, pero los eventos de cancelación de suscripción pueden devolver valores nulos. Consulta Tags vs metadata para los límites.

Antes de portar el código, ten en cuenta estas diferencias:

  • La programación, las plantillas almacenadas y los adjuntos se portan. Usa scheduled_at para envío programado. Usa template en lugar de contenido inline para plantillas almacenadas. Mapea los archivos al array de adjuntos.
  • Los destinatarios suprimidos se rechazan de forma visible. Una dirección suprimida recibe igualmente un recipient_id y aparece en la lista de destinatarios del mensaje con estado rejected y un evento email.rejected (rejection_reason: recipient_suppressed), nunca como una eliminación silenciosa. Incluso cuando todos los destinatarios están suprimidos, la solicitud se acepta con un 202. Cada destinatario vuelve rechazado. Consulta Supresiones.
  • Establece category: "transactional" para correo operativo. Un envío usa por defecto marketing, y la categoría controla la política de supresión: marketing bloquea ante quejas y cancelaciones de suscripción, transactional entrega a pesar de ellas. Los newsletters y las campañas se gestionan correctamente con el valor por defecto. Marca los recibos, restablecimientos de contraseña y correo operativo similar como transactional para que no queden bloqueados por una cancelación de suscripción.

2. Redirige dominios y DNS

Registra cada dominio de envío con POST /v1/email/domains o en Email > Domains, y después publica los registros de dns_records. DKIM, el CNAME de return-path y una política DMARC habilitan el envío. Un registro DMARC existente, incluso en un dominio padre, cuenta. El CNAME de tracking habilita solo el seguimiento de aperturas y clics con marca. Dominios de envío cubre los registros, el ciclo de vida de verificación y el modelo regional. Usa el divisor de registros DNS si tu proveedor requiere un valor DKIM dividido, y el generador de política DMARC si necesitas una política.

Un registro con el que la mayoría de los proveedores te hacen empezar está deliberadamente ausente: no publicas ningún registro SPF en el apex de tu dominio. SPF se evalúa contra el dominio de envelope-from, al que el CNAME de return-path apunta hacia nosotros, así que SPF pasa y se alinea sin tocar tu apex. Si tu proveedor anterior te hizo añadir un include: a tu registro SPF del apex, déjalo durante la transición y elimínalo después del corte. No ayuda ni perjudica al correo enviado a través de nosotros, y eliminarlo libera una de las 10 consultas DNS que SPF del apex permite. La explicación completa está en DKIM, SPF & DMARC.

Puedes publicar nuestros registros mientras los de tu proveedor anterior siguen activos. El registro DKIM usa un selector nuestro. Los CNAMEs de return-path y tracking son hostnames nuevos que tú eliges, y tu registro DMARC existente cumple el requisito tal cual. Ambos proveedores autentican en paralelo hasta que estés listo para cambiar el tráfico. El estado del dominio es regional, así que registra el dominio en cada región desde la que envíes.

3. Importa las supresiones

Traslada tu lista de supresión antes de enviar tráfico de producción a través de nosotros. De lo contrario, tus primeros envíos irán a direcciones que ya rebotaron o generaron quejas en tu proveedor anterior, lo que daña la reputación que intentas proteger.

Exporta la lista de tu proveedor actual (tu guía del proveedor tiene los endpoints exactos) y luego añade cada dirección aquí con POST /v1/email/suppressions:

Ejemplo de código
while read -r address; do
  curl -s -X POST https://us1.platform.bird.com/v1/email/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$address\"}"
done < suppressions.txt

Dos cosas que debes saber sobre esta ruta de importación:

  • Importas una dirección por solicitud. El API de supresiones es CRUD de una sola entrada, así que una lista grande implica iterar sobre las direcciones exportadas. La llamada es idempotente (201 para un registro nuevo, 200 con el registro existente si la dirección ya está suprimida manualmente), así que volver a ejecutar una importación parcial es seguro.
  • Las direcciones importadas obtienen reason: manual, applies_to: all, lo que bloquea todas las categorías, incluida la transaccional. Eso es más estricto que un registro nativo de queja, que bloquea solo envíos no transaccionales, así que si necesitas el comportamiento por categoría para direcciones específicas, consulta la taxonomía de razones en Supresiones.

A partir de ahora, los rebotes duros crean supresiones en el espacio de trabajo y emiten email_suppression.created, independientemente de la atribución a una Brand. Las quejas sin una atribución fiable a una Brand también crean supresiones en el espacio de trabajo y emiten email_suppression.created. Las quejas atribuidas a una Brand registran preferencias protegidas. Las cancelaciones de suscripción registran preferencias. Suscríbete también a los eventos de preferencia, incluso en un espacio de trabajo con una sola Brand, para que tu sistema replique estas bajas y los consentimientos posteriores. Los eventos email.complained, email.unsubscribed y email.list_unsubscribed a nivel de mensaje siguen disponibles. Consulta Eventos de email para ver la diferencia.

4. Cambia los webhooks

Registra un endpoint con POST /v1/webhooks y suscríbelo a una lista explícita de tipos de evento. Nuestros nombres de evento siguen resource.action: email.accepted → email.processed → email.delivered en el flujo exitoso, con email.deferred, email.bounced, email.complained, email.rejected, email.opened, email.clicked y el par de cancelación de suscripción cubriendo el resto. La traducción de nombres de evento desde el vocabulario de tu proveedor actual está en tu guía del proveedor. Los schemas de payload por evento están en la referencia de eventos.

Correlaciona los eventos de mensajes salientes con email_id y workspace_id; los eventos del ciclo de vida del destinatario también incluyen recipient_id. Guarda esa relación entre mensaje y cliente cuando envíes. Trata tags y metadata como contexto adicional cuando estén presentes: email.unsubscribed y email.list_unsubscribed procedentes de enlaces de cancelación de suscripción de Bird devuelven valores nulos en los envíos individuales, aunque el envío los incluyera. Los eventos de cancelación de suscripción de broadcasts también pueden devolver null cuando ese contexto no está disponible.

Usa preference.revoked, preference.granted y preference.deleted como señales para actualizar tu réplica de preferencias. Estos eventos identifican preference_id y transition_id, con el alcance de canal, handle, Brand, remitente y tema; no incluyen IDs de mensaje ni metadata del envío. Su timestamp es el momento en que la declaración entra en vigor, no una versión del registro. Una queja tardía puede revocar un consentimiento masivo posterior, y cambios distintos pueden compartir marca de tiempo. No determines el estado o la cobertura actuales ordenando eventos ni tratando transition_id como una secuencia de orden.

Inicializa y mantén una réplica completa de preferencias en este orden:

  1. Suscríbete a los eventos de preferencia y conserva de forma duradera las notificaciones entrantes antes de empezar la lectura inicial.
  2. Llena la réplica con todas las páginas de la lista de preferencias del espacio de trabajo, sin filtros de canal, handle ni Brand. Así descubres las bajas existentes que nunca han generado una notificación para tu endpoint. Guarda el ID, el canal, el handle, la Brand, el remitente y el alcance de tema de cada registro.
  3. Procesa las notificaciones conservadas y las nuevas: obtén la preferencia actual y lista todas las páginas del canal y el handle afectados. Compara los alcances para detectar una eliminación y una recreación con un ID distinto. Concilia también periódicamente la lista completa del espacio de trabajo sin filtros, incluidos los destinatarios que no aparecen en las notificaciones ni en tu réplica local.

Las lecturas pueden ir por detrás de un cambio: reintenta ante errores transitorios y ante un estado ausente o más antiguo de lo esperado. Una lectura fallida o incompleta no debe borrar un bloqueo local. Elimina un registro borrado solo después de confirmar que ya no existe; conserva las preferencias y supresiones independientes. Esta réplica converge con el tiempo y no sustituye las comprobaciones de Bird en el momento del envío.

email_suppression.created identifica las altas por suppression_id, workspace_id y email. No existe un evento de eliminación de supresión para clientes. Para detectar las eliminaciones hechas en el dashboard o con API, lee periódicamente todas las páginas de la lista de supresión del espacio de trabajo y concilia por ID de supresión. No elimines registros tras un recorrido fallido o parcial; confirma los registros ausentes en una lectura posterior antes de eliminarlos. Mantén los registros de supresión separados de las preferencias para que quitar un bloqueo no pueda borrar otro.

Firmamos las entregas según la especificación de Standard Webhooks, usando tres encabezados: webhook-id, webhook-timestamp y webhook-signature, con un HMAC-SHA256 sobre {id}.{timestamp}.{raw body}. Si ya verificas entregas de Standard Webhooks de otra plataforma, el mismo código de verificación funciona aquí. De lo contrario, la receta de verificación, el calendario de reintentos y las herramientas de reproducción están en Webhooks & events. Las entregas son at-least-once y sin orden, así que deduplica por webhook-id. Usa las marcas de tiempo de los eventos de mensaje para mostrar la cronología de los mensajes; para preferencias y supresiones, usa la conciliación del estado actual descrita arriba.

5. Verifica en el sandbox antes del corte

Antes de trasladar el tráfico de producción, prueba la llamada de envío portada y el handler de eventos de mensaje contra el sandbox de correo. Los envíos del sandbox van a direcciones mágicas en messagebird.dev y pasan por el pipeline de producción real: mismo 202, misma secuencia de eventos, mismas entregas de webhook firmadas, sin llegar jamás a una bandeja de entrada ni afectar tu reputación.

Las señales del sandbox no escriben registros de supresión ni de preferencias por queja. Prueba tu réplica por separado con payloads representativos de email_suppression.created, preference.revoked, preference.granted y preference.deleted tomados de los contratos de eventos de webhook, incluidas dos Brands que comparten el mismo destinatario. Incluye estos casos:

  • Una baja sin cambios es anterior al registro del webhook. El inventario inicial sin filtros la descubre sin notificación; el inventario periódico también descubre un registro que falta en tu réplica local.
  • Una cancelación de suscripción de un envío individual tiene tags y metadata nulos; la relación de mensajes que guardaste sigue identificando al cliente.
  • Llega una queja después de un consentimiento masivo más reciente, o una baja más antigua de todas las categorías amplía la protección por queja sin adelantar su marca de tiempo de vigencia. Entrega los eventos en orden inverso y verifica que la conciliación conserva el estado revocado y la cobertura actuales.
  • Se elimina y se vuelve a crear una preferencia, o se quita una supresión manual en el dashboard. La conciliación elimina solo los registros cuya ausencia se ha confirmado y conserva los bloqueos no relacionados.
  • Una actualización falla o devuelve temporalmente un estado más antiguo. Tu handler reintenta y la conciliación periódica repara la réplica sin borrar bloqueos por la lectura fallida.

Una prueba de humo mínima antes del corte:

  1. Envía a delivered@messagebird.dev y verifica que tu handler procesa email.accepted → email.processed → email.delivered.
  2. Envía a bounce@messagebird.dev y verifica que tu manejo de rebotes se activa con email.bounced (los rebotes simulados no escriben en tu lista de supresión, así que la dirección sigue siendo reutilizable).
  3. Envía a suppressed@messagebird.dev y verifica que manejas email.accepted seguido de email.rejected, sin email.processed ni eventos de entrega después. Esa es la forma que todo destinatario suprimido produce en producción; el detalle de rejection_reason: recipient_suppressed está en el registro del destinatario y en los eventos API.
  4. Envía un mensaje category: "marketing" y confirma que la categoría aparece donde esperas en la lectura del mensaje.

Usa subdireccionamiento +label (bounce+cutover-test@messagebird.dev) para correlacionar casos de prueba. La dirección completa aparece en tus eventos. Una vez que la prueba de humo pase, cambia el tráfico. Apunta tu aplicación hacia nosotros y mantén el DNS del proveedor anterior hasta que tus dominios aquí muestren capabilities.sending verificado. Vigila las primeras horas de entregas reales en el dashboard y en tu flujo de webhooks.

Migrar desde un proveedor específico

  • SparkPost: transmisiones y SMTP, conversión de plantillas, supresiones con alcance y eventos de webhook
  • SendGrid: personalizations → payload plano, categories/custom_args → tags/metadata, la equivalencia dropped ↔ email.rejected
  • Mailgun: parámetros o:*/v:*/h:* → campos de primer nivel, exportación de rebotes, quejas y cancelaciones de suscripción
  • Amazon SES: SendEmail v2 → un solo endpoint, configuration sets → flags de tracking por mensaje, SNS → webhooks firmados
  • Resend: forma de payload casi idéntica, webhooks firmados por Svix → Standard Webhooks
  • Postmark: destinatarios separados por comas → arrays, volcados de supresión por stream, webhooks sin firma → firmados
  • Brevo: objetos de dirección → direcciones planas, dos blocklists separadas para exportar, params → template.parameters
  • MailerSend: cinco listas de supresión de las cuales la temporal se queda atrás, personalization → parámetros por envío
  • Mailjet: el array Messages → un payload plano, EventPayload → metadata, exportación de blocklist
  • Mandrill: el wrapper message y autenticación en el body → payload plano y autenticación bearer, exportación de rejection blacklist

Próximos pasos

  • Envío de email: el payload de envío completo, tags vs metadata, el modelo asíncrono 202
  • Dominios de envío: registro, ciclo de vida de verificación, configuración multirregión
  • DKIM, SPF & DMARC: qué demuestra cada registro y por qué no se requiere SPF en el apex
  • Supresiones: razones, categorías y el API de gestión
  • Webhooks & events: configuración de endpoints, verificación de Standard Webhooks, reintentos y reproducción
  • Eventos: schemas de payload por evento
  • Sandbox de pruebas: la lista completa de direcciones mágicas y guías paso a paso
  • Referencia de API: schemas de solicitud y respuesta para el endpoint de envío