Migrar desde SparkPost

Usa esta guía para trasladar el correo electrónico saliente de SparkPost a Bird. Sigue la lista de verificación principal de migración, usando las correspondencias de abajo para tu integración HTTP o SMTP.

Antes de empezar

Necesitas acceso a tu cuenta y subcuentas de SparkPost, DNS de dominio de envío, configuración de la aplicación y handler de webhooks. Prepara un espacio de trabajo Bird y una clave API en la región que elijas. La importación de cancelaciones de suscripción también requiere permiso de escritura preferences en la clave.

Haz un inventario de remitentes, plantillas, snippets, listas de destinatarios, supresiones, envíos programados, pools de IP y webhooks. Incluye SDKs, adaptadores de correo del framework, trabajos en segundo plano y flujos de correo entrante. Registra los nuevos IDs de recursos a medida que los crees; los IDs y credenciales de SparkPost no funcionan en Bird. Usa los SDKs de Bird al reemplazar un cliente de SparkPost, y revisa sus reintentos, tiempos de espera y paginación.

Si usas subcuentas de SparkPost, contáctanos antes de elegir la estructura de espacios de trabajo. Confirma los espacios de trabajo disponibles, permisos, recursos compartidos y flujo de aprovisionamiento de tenants. Una clave API de espacio de trabajo no puede cambiar de tenant con X-MSYS-SUBACCOUNT. Conserva los tenants suspendidos y las restricciones de envío específicas de cada tenant durante la migración.

Confirma que las cuotas de tu plan de Bird y los límites de solicitudes cubran tu volumen de envío, cantidad de recursos y tráfico pico.

Registra tus dominios de envío con anticipación. Conserva el DNS funcional de SparkPost y elige nombres de host separados para return-path y tracking donde sea necesario. Si el registro reporta un conflicto de propiedad, contacta a soporte antes de eliminar un dominio activo.

IPs dedicadas: contáctanos o a tu equipo de cuenta antes de migrar. Pídenos confirmar si tus IPs existentes de SparkPost pueden trasladarse a Bird y acuerda la configuración de pools, el calendario y cualquier calentamiento necesario. Incluye la región de tu cuenta, direcciones IP, nombres de pool y volumen de envío. Mantén tus IPs actuales activas hasta que se confirme el plan de migración.

Confirma la selección de pool y las listas de IPs o nombres de host permitidos del destinatario antes del cambio. Comprar una IP no cambia el pool predeterminado. Las IPs recién adquiridas pueden enviar excedente a través de infraestructura compartida durante el calentamiento, lo cual importa si los destinatarios solo aceptan correo de IPs específicas.

Pasa esto a tu agente

Pega esto en tu agente de código en el repositorio de tu aplicación:

Help me migrate my SparkPost email integration to Bird.
1. Use an existing Bird MCP connection or signed-in CLI. Otherwise follow https://bird.com/docs/ai/set-up-your-agent.md. Append .md to Bird docs URLs to read Markdown.
2. Read https://bird.com/docs/guides/email/migrate/sparkpost.md and https://bird.com/docs/guides/email/migrate.md. Make a read-only inventory of my SparkPost call sites, SDKs, resource IDs, configured URLs, sending domains, and scheduled jobs before editing. Never print API keys.
3. Propose workspace and region mappings. If subaccounts, dedicated IPs, or domain ownership conflicts need a migration plan, use the available Bird tools to open a human email support ticket and return its ID. For CLI usage, read https://bird.com/docs/cli/reference/support-tickets-create.md. Wait for the agreed plan before moving those resources.
4. Follow https://bird.com/docs/guides/email/sending-domains.md; preserve working DNS and show me proposed records. Ask before DNS changes or paid provisioning.
5. Port sending, templates, and webhooks using this guide. Preserve recipient privacy, personalization, and categories. Export suppressions with scope and type; show me the handling before importing or changing preferences.
6. Test using https://bird.com/docs/guides/email/testing-sandbox.md. Show me results and unresolved differences, including tracking, signatures, and correlation.
7. Ask for explicit approval before production cutover. Keep a rollback path; get separate approval before retiring SparkPost resources or credentials.

Mapea la llamada de envío

Reemplaza POST /api/v1/transmissions con POST /v1/email/messages, o POST /v1/email/batches para mensajes independientes. La descripción general de API de SparkPost enumera sus hosts regionales y autenticación. Bird usa https://us1.platform.bird.com o https://eu1.platform.bird.com, según la región de tu clave API, con Authorization: Bearer $BIRD_API_KEY.

Una transmisión de SparkPost puede generar correos separados y personalizados para sus destinatarios. Bird comparte contenido y parámetros entre los destinatarios de un mismo envío. Usa un mensaje separado para cada personalización, opcionalmente agrupado en un lote. Los envíos solo con To siguen dirigidos individualmente; verifica los encabezados visibles al añadir copias Cc/Bcc.

Mapea los campos de transmisión de SparkPost:

Para copias To/Cc/Bcc de un mismo correo, reconstruye el grupo de destinatarios una sola vez. Las direcciones visibles de SparkPost pueden diferir de los destinatarios de entrega; to, cc y bcc de Bird añaden destinatarios de entrega cada uno. Copiar un encabezado CC de SparkPost en el cc de cada mensaje expandido puede enviar copias duplicadas. Verifica los encabezados visibles y el número de destinatarios antes de cambiar.

Revisa los límites de campos de envío, la programación y las reglas de adjuntos. Actualiza los IDs de imágenes en línea y las referencias cid: correspondientes para cumplir las reglas de Bird. Configura la ruta de retorno y el dominio de seguimiento en el dominio.

Los campos de envío HTTP de Bird no incluyen content.email_rfc822, content.amp_html ni options.inline_css de SparkPost. Reconstruye los mensajes sin procesar con los campos soportados, proporciona alternativas HTML/texto para AMP e integra el CSS en línea antes de enviar HTML. SMTP analiza y reconstruye las partes soportadas del mensaje; valida el MIME recibido si dependes de su estructura exacta. Los parámetros MIME de adjuntos como method de calendario o charset de texto no se conservan.

Para mensajes API programados, Bird fija la versión de la plantilla, el idioma y los parámetros cuando acepta la solicitud. Las ediciones posteriores a la plantilla no actualizan ese mensaje. Para cambiarlo, cancela el mensaje programado antes de que comience el procesamiento y envía uno de reemplazo. Guarda un grupo de IDs de mensaje Bird si necesitas reemplazar la cancelación basada en campaña de SparkPost.

Establece BIRD_API_KEY con tu clave Bird. Este ejemplo de sandbox no necesita un dominio verificado y no llega a ninguna bandeja de entrada real. Para una clave de la UE, usa https://eu1.platform.bird.com:

curl --fail-with-body https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "onboarding@messagebird.dev",
    "to": ["delivered@messagebird.dev"],
    "subject": "Your receipt",
    "text": "Thanks for your order, {{ first_name }}.",
    "parameters": {"first_name": "Alex"},
    "category": "transactional",
    "metadata": {"order_id": "order_123"},
    "tags": [{"name": "mailstream", "value": "receipts"}]
  }'

Espera 202 Accepted y un ID de mensaje em_. Almacena ese ID y sigue los resultados del destinatario a través de los eventos. La aceptación no confirma la entrega: un destinatario suprimido puede ser aceptado y rechazado después. Actualiza el análisis de respuestas, el manejo de errores y los reintentos idempotentes junto con la llamada de envío.

Para un lote, lee el array data y guarda el ID de cada mensaje junto con tu propio registro de envío. Bird valida el lote antes de encolarlo: un solo mensaje no válido puede rechazar toda la solicitud. Divide transmisiones grandes para que se ajusten a los límites del lote y sigue las reglas de reintento de Bird cuando una respuesta sea ambigua.

Asigna a cada solicitud distinta o fragmento de lote su propia clave de idempotencia estable. La ventana de repetición de Bird difiere de la de SparkPost; conserva tus registros de envío más allá de esa ventana para evitar duplicados durante la migración o la reversión.

Migrar remitentes SMTP

Usa los ajustes de conexión SMTP de Bird, el nombre de usuario bird y una clave API con envío de correo habilitado. Verifica la región, TLS y la configuración de la clave.

Convierte las opciones X-MSYS-API de SparkPost antes de eliminar el encabezado. Configura los valores predeterminados de categoría, etiquetas, seguimiento y pool en la configuración SMTP de Bird. Esos ajustes se aplican por clave API; usa claves configuradas por separado o HTTP cuando varíen entre mensajes. Usa HTTP para metadatos por mensaje o parámetros de plantilla.

Coloca cada destinatario de entrega en el sobre SMTP, los destinatarios visibles en los encabezados MIME To/Cc, y los destinatarios Bcc solo en el sobre. Inventaría X-MSYS-API.archive por separado: las copias de archivo de SparkPost conservan las URLs de seguimiento del destinatario original, por lo que un Bcc ordinario no es equivalente. Valida un reemplazo antes de cambiar ese flujo.

Copia tus ajustes de seguimiento efectivos de forma explícita: la clave SMTP no configurada de Bird habilita el seguimiento de aperturas y clics, mientras que los valores predeterminados de SparkPost varían según la cuenta. Configura también la categoría: Bird SMTP usa transaccional por defecto e inline HTTP usa marketing. Los remitentes de newsletters necesitan marketing en cualquiera de las dos vías.

Para los reintentos SMTP, reutiliza la clave de idempotencia, el sobre y los bytes MIME exactos. Regenerar Date, Message-ID o los límites MIME cambia el contenido y puede impedir un reintento seguro.

Convertir plantillas

Exporta las versiones que realmente envías a través de la API de plantillas API de SparkPost: lista con GET /api/v1/templates?draft=false y luego recupera el contenido con GET /api/v1/templates/{id}?draft=false. Guarda los borradores por separado si es necesario. Incluye las plantillas compartidas con subcuentas y los snippets referenciados en el inventario.

El lenguaje de plantillas de SparkPost y la sintaxis Liquid de Bird son diferentes. Convierte condicionales, bucles, valores predeterminados y valores anidados. Resuelve las sobrescrituras por destinatario y los metadatos usados para el renderizado en parámetros explícitos. Por ejemplo, {{ if ... }} se convierte en {% if ... %}. La sintaxis {{ name }} compartida por sí sola no garantiza compatibilidad.

Expande los snippets antes de publicar; el Liquid de Bird no soporta include ni render. Para plantillas almacenadas, reemplaza referencias externas como {{ user.name }} con parámetros planos como {{ user_name }}. Si insertas HTML dinámico a través de parámetros de SparkPost, renderízalo en tu aplicación y envía el cuerpo completo sin parameters inline; los valores de parámetros HTML ordinarios se escapan.

Crea, previsualiza y publica una plantilla de Bird, luego sigue enviar con una plantilla. Traslada el remitente efectivo, Reply-To y los encabezados personalizados de SparkPost a la solicitud de envío; las plantillas de Bird proporcionan el contenido.

Para Liquid en línea, incluye parameters, incluso {}; omitirlo deja los tokens sin cambios. Verifica valores faltantes, escape y URLs.

Reemplaza los marcadores de cancelación de suscripción con {{ bird.unsubscribe_url }}. Bird proporciona encabezados de cancelación de suscripción de marketing; elimina los encabezados personalizados List-Unsubscribe y List-Unsubscribe-Post de los envíos de marketing para evitar un rechazo de 422.

Los enlaces de cancelación de suscripción de Bird excluyen la dirección del email de marketing en todo el espacio de trabajo. Estos enlaces no ofrecen cancelaciones de suscripción específicas por lista. Verifica este comportamiento si tu integración con SparkPost ofrece suscripciones separadas.

Migrar listas de destinatarios

Exporta cada lista de destinatarios almacenada con GET /api/v1/recipient-lists/{id}?show_recipients=true para incluir membresía y personalización. Crea las audiencias de destino y registra las propiedades de contacto antes de importar. Revisa cada resultado de importación y reconcilia los conteos de membresía.

Las propiedades de contacto pertenecen al contacto en todas sus audiencias. Si la misma dirección tiene datos de sustitución diferentes en varias listas de SparkPost, reconcilia esos valores antes de importar para evitar sobrescribirlos. Las propiedades de contacto de Bird tienen tipos escalares; mantén la personalización específica por lista o estructurada en tu aplicación cuando no pueda representarse de forma segura.

Usa broadcasts cuando una plantilla publicada pueda completarse con propiedades de contacto. La membresía de audiencia se resuelve cuando comienza el envío, y se aplican los límites de envío y concurrencia de broadcasts. Usa mensajes en lote independientes para parámetros específicos de la solicitud o una instantánea fija de destinatarios. Valida el manejo de consentimiento y supresión antes de activar una lista migrada.

Exportar supresiones

Exporta antes de enviar en producción. Comienza con GET /api/v1/suppression-list?cursor=initial&types=transactional,non_transactional,open_tracking, luego sigue la paginación hasta completar. Guarda los registros completos, incluyendo tipo, origen, ID de lista, subcuenta y marcas de tiempo. Usa X-MSYS-SUBACCOUNT: 0 para la cuenta principal y el ID de cada subcuenta para su propia lista. Consulta la Suppression List API de SparkPost.

Clasifica los registros por tipo, origen y alcance antes de usar el bucle de importación de la guía principal. POST /v1/email/suppressions de Bird recibe un email y crea un bloqueo manual a nivel de espacio de trabajo en ambas categorías:

• Direcciones bloqueadas para recibir email: importa las que deben bloquearse en todas las categorías. Conserva la exportación original para reconciliación; los registros importados llevan el motivo manual de Bird.
• Exclusiones de marketing a nivel de cuenta: usa POST /v1/preferences con channel: "email", la dirección en handle, status: "revoked" y coverage: "non_transactional". Establece source: "sparkpost-migration" para la conciliación. Revisa primero las preferencias existentes de Bird y conserva las restricciones más estrictas; inspecciona applied y la preferencia devuelta después de cada escritura.
• Restricciones específicas de lista o solo transaccionales: conserva su alcance en la elegibilidad de envío de tu aplicación. Las preferencias de correo de Bird son a nivel de canal y no pueden representar estos alcances. Una supresión manual también puede bloquear restablecimientos de contraseña. Mantén el tráfico afectado en pausa hasta que verifiques el reemplazo.
• Exclusiones de seguimiento de apertura: establece track_opens: false para el mensaje independiente, además de cualquier restricción de envío. Para SMTP, usa una clave con el seguimiento de apertura desactivado o usa HTTP para control por mensaje.

La solicitud de preferencia anterior registra la restricción en el momento de la importación. Conserva las marcas de tiempo originales de SparkPost en tu exportación y concilia cualquier consentimiento posterior antes de escribir. Concilia los registros importados y las escrituras fallidas, y luego prueba ambas categorías. Sincroniza las nuevas exclusiones y supresiones mientras ambos proveedores envían. Sigue aplicando las exclusiones del correo de SparkPost entregado previamente en Bird después del corte. Consulta Supresiones para el manejo nativo de rebotes y quejas.

Traducir eventos de webhook

SparkPost envía eventos de webhook en lotes dentro de contenedores msys. Bird entrega un evento por solicitud con type, timestamp y data. Registra un endpoint Bird con suscripciones explícitas a eventos y verificación de firma. Mantén el handler de SparkPost activo para su tráfico restante.

Los envíos directos por API y SMTP emiten email.accepted antes del procesamiento. Los broadcasts registran la aceptación en los eventos API y en el registro de correo, pero omiten ese webhook. Los eventos policy_rejection, generation_failure y generation_rejection de SparkPost corresponden a email.rejected; inspecciona rejection_reason. Deduplica las aperturas por separado cuando cuentes interacción única.

Usa data.email_id y data.recipient_id para la correlación de Bird, y lleva tus propios identificadores en metadata. Reemplaza el manejo de batch-ID de SparkPost con las reglas de deduplicación y ordenamiento de webhooks de Bird. Lee los detalles de rebote antes de decidir si una dirección debe suprimirse; la clasificación de rebotes distingue entre fallos permanentes de dirección y fallos temporales o de política.

Conserva el historial de informes

Exporta el historial de eventos de SparkPost y los informes agregados que necesites antes de que venzan sus períodos de retención. Sigue la paginación de eventos hasta completarla y conserva los ID del proveedor, el alcance de cuenta/subcuenta, las marcas de tiempo y los filtros de informes. Sigue recopilando eventos tardíos durante la superposición y conserva el historial de SparkPost en un archivo separado.

Guarda una línea base para cada flujo de envío. Compara poblaciones de destinatarios y ventanas de informes equivalentes, y revisa las definiciones de métricas: aceptación del proveedor, entrega en el servidor del destinatario, interacción única y aperturas precargadas son medidas diferentes. Que los nombres de las métricas coincidan no significa que las tasas sean comparables.

Migra el correo entrante por separado

Si usas webhooks de retransmisión de SparkPost, sigue Recibir correo electrónico para ese flujo. El webhook email.received de Bird proporciona un inbound_message_id; obtén el cuerpo, los adjuntos o el MIME sin procesar a través de API en lugar de esperar el mensaje completo en el webhook. Prueba tu handler con una dirección de reenvío Bird, luego prepara la recepción del dominio antes de cambiar los registros MX. Verifica el enrutamiento de respuestas después del cambio de DNS y archiva el contenido que necesites más allá del periodo de retención de recepción de Bird.

Verificar y migrar

1. Verifica la capacidad de envío de cada dominio. Ejecuta la prueba de humo del sandbox y los casos de queja. Confirma que los eventos firmados llegan a tu handler, se correlacionan con el mensaje correcto y manejan entregas duplicadas. Los eventos del sandbox no demuestran entrega en bandeja de entrada, renderizado ni seguimiento.
2. Envía desde tu dominio verificado a bandejas de entrada reales controladas. Verifica la personalización, la visibilidad de To/Cc/Bcc, los adjuntos, la autenticación y el seguimiento. Prueba una cancelación de suscripción: el correo de marketing debe detenerse mientras el correo transaccional elegible continúa. Por separado, comprueba que los bloqueos de todas las categorías rechazan ambos. Mantén estas verificaciones separadas de los resultados simulados del sandbox.
3. Asigna los envíos programados pendientes a un solo proveedor. Drena o cancela el original antes de recrearlo en otro lugar. Mantén un registro en la aplicación de qué proveedor aceptó cada envío lógico para que los reintentos o la reversión no envíen una segunda copia.
4. Mueve una porción controlada del tráfico y monitorea las métricas de entrega y el procesamiento de webhooks. Para IPs dedicadas, sigue el plan de migración acordado con nuestro equipo, incluido cualquier calentamiento. Aumenta el tráfico cuando los resultados observados cumplan tus requisitos de entrega.
5. Si la validación falla, pausa el tráfico afectado de Bird y redirige los nuevos envíos por la ruta retenida de SparkPost con las cancelaciones de suscripción actuales aplicadas. Reconcilia los envíos ambiguos antes de reintentarlos. Retira las credenciales, webhooks y DNS antiguos después de que las colas y los eventos tardíos estén contabilizados; mantén los enlaces de seguimiento y cancelación de suscripción antiguos funcionales para el correo entregado previamente.

Si la autenticación falla, verifica el token bearer de Bird y la región. Si las importaciones de preferencias devuelven 403, verifica el permiso de escritura preferences de la clave antes de continuar. Si la personalización se renderiza incorrectamente, inspecciona la conversión de Liquid y los parámetros. Si el correo transaccional se rechaza inesperadamente, revisa las supresiones manuales importadas. Usa el registro de correo electrónico y los detalles de eventos para verificar cada corrección.

Próximos pasos

• Enviar correo electrónico: campos del payload, personalización y resultados asíncronos
• Plantillas de correo electrónico: vista previa, publicación y soporte de Liquid
• Supresiones: motivos de supresión y gestión
• Webhooks y eventos: firmas, reintentos y reproducción