DocumentazioneCreare o aggiornare contatto

Creare o aggiornare contatto

PUT /contacts — upsert per email con externalId e attributi.

L'endpoint PUT /contacts crea o aggiorna un contatto in base all'email (upsert idempotente). Ideale per sincronizzare un utente alla registrazione o all'aggiornamento del profilo.

Scope richiesto: contacts:write.

PUT https://api.mailingcore.com/contacts
Authorization: Bearer mc_live_xxxx
X-Tenant-Id: clxxxxxxxx
Content-Type: application/json

Corpo della richiesta

{
  "email": "[email protected]",
  "externalId": "crm-12345",
  "locale": "it",
  "optIn": true,
  "consentVersion": "2026-01",
  "source": "signup-form",
  "projectId": "clx...",
  "attributes": { "sede": "Milano" }
}

Campi

Campo	Obbligatorio	Descrizione
`email`	Si	Email del contatto; chiave di upsert
`externalId`	No	ID nel tuo sistema per lookup e cancellazione GDPR
`locale`	No	`es`, `en`, `it`, `fr`, `ca`, `de`
`optIn`	No	Consenso newsletter (`true` / `false`)
`consentVersion`	No	Versione del testo di consenso
`source`	No	Origine (form, import, integrazione)
`projectId`	No	Segmentazione per progetto SMTP
`attributes`	No	Attributi custom (allowlist: default `sede`)

Crea la API key
Nel pannello, genera una key con scope contacts:write. Vedi API key e scope.
Invia l'upsert
Chiama PUT /contacts dal backend quando l'utente si registra o aggiorna le preferenze.
Verifica il contatto
Recupera con GET /contacts/:idOrExternalId usando l'id interno o externalId.

Esempio curl

curl -X PUT "https://api.mailingcore.com/contacts" \
  -H "Authorization: Bearer mc_live_xxxx" \
  -H "X-Tenant-Id: clxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "externalId": "crm-12345",
    "locale": "it",
    "optIn": true,
    "consentVersion": "2026-01",
    "source": "signup-form"
  }'

Aggiornamento parziale

Per modificare campi senza riscrivere l'intero record, usa PATCH /contacts/:id con l'id interno MailingCore.

Cancellazione GDPR

DELETE /contacts/:externalId esegue una cancellazione logica per externalId. Utile per il diritto all'oblio — il contatto non ricevera piu comunicazioni.