Patron de integracion B2B SaaS

Esta pagina describe una arquitectura de referencia para un producto B2B SaaS que integra newsletter con MailingCore: tu app sigue siendo la fuente de verdad del consentimiento, mientras MailingCore mantiene una replica operativa para envio, baja hospedada y entregabilidad.

El patron se valido en integraciones tipo produccion (apps multi-tenant, add-ons CRM, SaaS verticales). Adapta nombres e IDs a tu dominio.

Vision general

Scopes de API key (minimos)

Opcional: suppressions:write si empujas bajas desde tu panel ademas de webhooks.

1. Sincronizacion de contactos

Objetivo: Mantener audiencia opted-in en MailingCore sin pasar listas de destinatarios en cada envio.

Reconciliacion: GET /contacts?updatedSince=<ISO>&cursor= para alinear bajas hospedadas a tu almacen de consentimiento.

Cadencia sugerida: cada 15–60 min mas hooks en tiempo real en eventos de consentimiento.

2. Receptor webhook (tu servidor)

Registra con Crear endpoint:

{
  "url": "https://tu-saas.com/webhooks/mailingcore",
  "events": [
    "contact.unsubscribed",
    "email.bounced",
    "email.complained"
  ],
  "secret": "<tu-secreto-en-env>"
}

Verifica X-MailingCore-Signature (HMAC SHA-256, tolerancia replay ±5 min). Responde 200 de inmediato; procesa async. Ver Entregas y reintentos.

3. Flujo de campana (sustituye relay batch)

Deja de usar fan-out POST /emails/batch con arrays de destinatarios. Usa la API de campanas:

1. Pre-sync audiencia

   Ejecuta sync de contactos con optIn: true actualizados.

2. Crear borrador

   POST /campaigns con templateVersionId, subject, audienceFilter: { optIn: true }.

3. Revisar cobertura locale

   GET /campaigns/:id/locale-coverage — variantes por Cobertura de idiomas.

4. Envio de prueba

   POST /campaigns/:id/test a 1–5 emails QA internos.

5. Programar o enviar

   POST /campaigns/:id/schedule o POST /campaigns/:id/send (fan-out async).

6. Poll de estado

   GET /campaigns/:id hasta SENT, FAILED o CANCELLED. Persiste mailingcoreCampaignId en tu entidad de campana.

Paso a paso completo: Crear y enviar campana.

4. Feature flag y rollback

Mantén un switch de configuracion (p. ej. NEWSLETTER_MODE=legacy_relay | mailingcore_api) para volver al camino de envio anterior sin redeploy. Ejecuta smoke tests en staging antes de cambiar trafico de produccion.

5. Checklist smoke test

Relacionado

• Contactos overview
• Importacion bulk
• Baja
• Crear endpoint webhook