Importazione massiva

POST /contacts/bulk — upsert fino a 1000 contatti per richiesta.

Quando devi sincronizzare un database esistente o importare un export CSV, usa POST /contacts/bulk per fare upsert di molti contatti in una sola chiamata.

Scope richiesto: contacts:write.

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

Limite per richiesta

Il massimo e definito da CONTACTS_BULK_MAX (default 1000 contatti). Per dataset piu grandi, suddividi in batch e ritenta con backoff in caso di errore transitorio.

Corpo della richiesta

{
  "contacts": [
    {
      "email": "[email protected]",
      "externalId": "crm-001",
      "locale": "it",
      "optIn": true,
      "source": "migration-2026"
    },
    {
      "email": "[email protected]",
      "externalId": "crm-002",
      "locale": "en",
      "optIn": true,
      "attributes": { "sede": "Roma" }
    }
  ]
}

Ogni elemento dell'array accetta gli stessi campi di PUT /contacts: email, externalId, locale, optIn, consentVersion, source, projectId, attributes.

Esempio curl

curl -X POST "https://api.mailingcore.com/contacts/bulk" \
  -H "Authorization: Bearer mc_live_xxxx" \
  -H "X-Tenant-Id: clxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "email": "[email protected]", "locale": "it", "optIn": true },
      { "email": "[email protected]", "locale": "en", "optIn": true }
    ]
  }'

Prepara i dati
Normalizza le email (minuscolo, trim) e assegna externalId per tracciabilita futura.
Suddividi in batch
Raggruppa fino a 1000 contatti per richiesta. Tieni traccia dell'offset per riprendere in caso di interruzione.
Invia e verifica
Dopo l'import, campiona con GET /contacts?locale=it&optIn=true per confermare i totali.