Contatti e audience

Modello contatto, externalId, locale e filtri audience.

I contatti sono la base della newsletter in MailingCore. Ogni tenant mantiene un'audience isolata che puoi sincronizzare dall'applicazione o dal CRM tramite API.

Scope richiesti sulla API key: contacts:read e contacts:write. Dettagli in API key e scope.

Modello contatto

Campo	Descrizione
`email`	Indirizzo univoco per tenant (chiave di upsert)
`externalId`	ID nel tuo sistema (es. `ludosafe-123`) per integrazioni B2B
`locale`	Lingua preferita: `es`, `en`, `it`, `fr`, `ca`, `de`
`optIn`	Consenso esplicito alla newsletter
`consentVersion`	Versione del testo di consenso accettato
`source`	Origine del contatto (es. `signup-form`)
`projectId`	Progetto SMTP opzionale per segmentazione
`attributes`	Attributi custom (allowlist, default: `sede`)
`suppressedAt`	Data di soppressione; sincronizzata con `/suppressions`

Endpoint principali

Azione	Endpoint	Scope
Upsert	`PUT /contacts`	`contacts:write`
Import massivo	`POST /contacts/bulk`	`contacts:write`
Elencare	`GET /contacts`	`contacts:read`
Dettaglio	`GET /contacts/:idOrExternalId`	`contacts:read`
Aggiornare parziale	`PATCH /contacts/:id`	`contacts:write`
Cancellazione GDPR	`DELETE /contacts/:externalId`	`contacts:write`

Filtri di lista

GET /contacts accetta parametri di query:

?locale=it — filtra per lingua
?optIn=true — solo iscritti attivi
?suppressed=false — esclude soppressi
Paginazione standard

Questi stessi criteri alimentano audienceFilter nelle campagne.

Integrazione B2B

Per SaaS multi-tenant (es. un gestionale che invia newsletter per conto dei clienti), usa externalId per mappare l'utente nel tuo database. L'header X-Tenant-Id isola i dati per organizzazione — vedi Multi-tenant.

Prossimi passi

Creare o aggiornare contatto — PUT /contacts
Importazione massiva — sincronizzare migliaia di contatti
Disiscrizioni e GDPR — pagine ospitate e {{unsubscribeUrl}}