Documentación
Sign inGet started
Comenzar
Guías
Referencia de API
SDKs
CLI
Base de conocimientos
Registro de cambios

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 supresiones
  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 supresiones 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, devuelve en lecturas de API y repite en eventos de webhook. 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 supresiones 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.
De aquí en adelante no gestionas los rebotes tú mismo: suprimimos automáticamente los rebotes duros y las quejas, emitiendo email_suppression.created para que tus sistemas puedan replicar la lista de supresiones. Las cancelaciones de suscripción se registran como una preferencia declarada, y se replican mediante email.unsubscribed y email.list_unsubscribed, no a través del evento de supresión.

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.
La correlación se porta sin problema. Cada evento tiene los identificadores email_id, recipient_id y workspace_id. También repite tags y metadata de la solicitud de envío. Esto devuelve el contexto que tu proveedor anterior proporcionaba mediante el eco del payload, sin una consulta adicional. Pon tus IDs internos en metadata en el envío y léelos directamente de cada evento.
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 y ordena por el timestamp del payload, la misma disciplina que tu handler actual ya debería tener.

5. Verifica en el sandbox antes del corte

Antes de trasladar el tráfico de producción, ejecuta tu integración completa (la llamada de envío portada, tu handler de webhook, tu replicación de supresiones) 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.
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 supresiones, 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

  • 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 bounces/complaints/unsubscribes
  • 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

Recursos relacionados

Continúa con la documentación, guías y ejemplos sobre este tema. Los recursos están en inglés.

Ver la guíaGetting started with emailExplorar la funcionalidadEmailSeguir la ruta de aprendizajeBuild your first integrationGuía de implementaciónSend your first email
Prueba el ejercicio y obtén un resumen de implementación