Concetti chiave

Tenant, API key, scope, template e altri termini del prodotto.

Prima di integrare conviene allineare il vocabolario. Questi concetti compaiono nell'API, nel pannello e nei webhook.

Tenant

Spazio di lavoro isolato. Ogni tenant ha i propri domini, template, contatti, campagne e quota email. Quasi tutte le route API richiedono l'header X-Tenant-Id.

API key

Credenziale per integrazioni server-side o SDK. Formato: mc_live_... (produzione) o mc_test_... (test). Si invia come:

Authorization: Bearer mc_live_xxxx

Ogni key ha scope (permessi granulari) e viene mostrata per intero solo al momento della creazione.

Scope

Permessi in formato risorsa:azione. Esempi:

Scope	Consente
`email:send`	Inviare email (`POST /emails/send`, batch, programmati)
`email:read`	Leggere i log di invio
`contacts:read` / `contacts:write`	Gestire l'audience
`campaigns:read` / `campaigns:write`	Campagne newsletter
`webhooks:manage`	Endpoint webhook in uscita

Le route di template, domini e analytics del pannello usano JWT di sessione, non API key.

Template e versione

Un template raggruppa versioni. Ogni versione puo essere in DRAFT o PUBLISHED. Alla pubblicazione il CSS viene inlinato. Puoi inviare con templateVersionId al posto di htmlBody.

Soppressione

Lista di email che non devono ricevere altri messaggi (hard bounce, reclamo, disiscrizione volontaria). Gli invii verso indirizzi soppressi vengono bloccati.

Coda di invio

Gli invii transazionali entrano in coda BullMQ (QUEUED → SENT). L'API risponde subito con l'id del log; il worker consegna in background.

Quota mensile

Ogni piano ha un limite di email/mese. L'API restituisce header X-Quota-* a ogni invio. Oltre il 110 % del limite, risponde 429.