Conceptos clave

Tenant, API keys, scopes, plantillas y demas terminos del producto.

Antes de integrar conviene alinear vocabulario. Estos conceptos aparecen en la API, el panel y los webhooks.

Tenant

Espacio de trabajo aislado. Cada tenant tiene sus propios dominios, plantillas, contactos, campanas y cuota de emails. Casi todas las rutas de API requieren el header X-Tenant-Id.

API key

Credencial para integraciones server-side o SDK. Formato: mc_live_... (produccion) o mc_test_... (pruebas). Se envia como:

Authorization: Bearer mc_live_xxxx

Cada key tiene scopes (permisos granulares) y solo se muestra una vez al crearla.

Scopes

Permisos en formato recurso:accion. Ejemplos:

Scope	Permite
`email:send`	Enviar emails (`POST /emails/send`, batch, programados)
`email:read`	Leer logs de envio
`contacts:read` / `contacts:write`	Gestionar audiencia
`campaigns:read` / `campaigns:write`	Campanas newsletter
`webhooks:manage`	Endpoints de webhooks salientes

Las rutas de plantillas, dominios y analiticas del panel usan JWT de sesion, no API key.

Plantilla y version

Una plantilla agrupa versiones. Cada version puede estar en DRAFT o PUBLISHED. Al publicar se inlinea CSS. Puedes enviar con templateVersionId en lugar de htmlBody.

Supresion

Lista de emails que no deben recibir mas mensajes (hard bounce, queja, baja voluntaria). Los envios a direcciones suprimidas se bloquean.

Cola de envio

Los envios transaccionales entran en cola BullMQ (QUEUED → SENT). La API responde al instante con el id del log; el worker entrega en segundo plano.

Cuota mensual

Cada plan tiene un limite de emails/mes. La API devuelve headers X-Quota-* en cada envio. Por encima del 110 % del limite, responde 429.