Vai al contenuto
Docs

Aggiungi, aggiorna e rimuovi gli iscritti di una lista.

URL di basehttps://api.emailit.com/v2AutenticazioneErroriLimiti di frequenza

Aggiungi un iscritto

Aggiunge un contatto a una lista tramite l’indirizzo email.

POST/audiences/{audience_id}/subscribers

Richiede una chiave API full. Se nessun contatto ha ancora questo indirizzo email, Emailit ne crea uno. Se il contatto esiste, i nomi e i campi personalizzati che invii sovrascrivono i valori attuali. Un contatto che si era disiscritto dalla lista viene iscritto di nuovo e la risposta è 200; per un contatto già iscritto la risposta è 409.

Ogni lista può contenere tanti iscritti quanti ne consente il piano; oltre questo limite, la richiesta restituisce 422 con il tuo usage. Genera subscriber.created, oppure subscriber.updated e subscriber.resubscribed in caso di reiscrizione.

Parametri di percorso

audience_idstringobbligatorio
L’ID della lista (aud_…) o il suo nome.

Parametri del corpo

emailstringobbligatorio
L’indirizzo email da iscrivere. Viene salvato in minuscolo.
first_namestring
Il nome del contatto.
last_namestring
Il cognome del contatto.
custom_fieldsobject

I valori dei campi personalizzati per chiave, ad esempio {"company": "Analytical Engines"}. Sostituisce i campi personalizzati esistenti del contatto.

Restituisce

Restituisce 201 con l’oggetto iscritto, oppure 200 quando un contatto disiscritto è stato iscritto di nuovo.

POST/audiences/{audience_id}/subscribers
Terminal
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "custom_fields": { "company": "Analytical Engines" }
  }'
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "subscribed": true,
  "subscribed_at": "2026-10-01T10:20:31.000000Z",
  "unsubscribed_at": null,
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-01T10:20:31.000000Z"
}

Recupera un iscritto

Recupera l’appartenenza di un contatto a una lista.

GET/audiences/{audience_id}/subscribers/{id}

Richiede una chiave API full. Un iscritto collega un contatto a una lista. L’email, i nomi e i campi personalizzati appartengono al contatto, mentre subscribed riguarda solo questa lista.

Parametri di percorso

audience_idstringobbligatorio
L’ID della lista (aud_…) o il suo nome.
idstringobbligatorio
L’ID dell’iscritto (sub_…) o l’indirizzo email del contatto, codificato per l’URL.

Restituisce

Restituisce l’oggetto iscritto.

objectstring
Sempre subscriber.
idstring
L’ID dell’iscritto.
audience_idstring
L’ID della lista.
contact_idstring
L’ID del contatto.
emailstring
L’indirizzo email del contatto.
first_namestring | null
Il nome del contatto.
last_namestring | null
Il cognome del contatto.
custom_fieldsobject | null
I valori dei campi personalizzati del contatto.
subscribedboolean
true se il contatto è iscritto a questa lista, false se si è disiscritto.
subscribed_atstring | null
Quando il contatto si è iscritto l’ultima volta.
unsubscribed_atstring | null
Quando il contatto si è disiscritto, oppure null.
created_atstring
Quando il contatto è entrato nella lista.
updated_atstring
Quando è cambiata l’ultima volta l’appartenenza alla lista.
GET/audiences/{audience_id}/subscribers/{id}
Terminal
curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "subscribed": true,
  "subscribed_at": "2026-10-01T10:20:31.000000Z",
  "unsubscribed_at": null,
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-01T10:20:31.000000Z"
}

Aggiorna un iscritto

Modifica lo stato di un iscritto nella lista, oppure i dati del suo contatto.

POST/audiences/{audience_id}/subscribers/{id}

Richiede una chiave API full. Invia solo i campi che vuoi modificare. subscribed vale solo per questa lista. email, first_name, last_name e custom_fields modificano il contatto stesso, quindi la modifica compare in ogni lista a cui il contatto appartiene. Genera un evento subscriber.updated.

Parametri di percorso

audience_idstringobbligatorio
L’ID della lista (aud_…) o il suo nome.
idstringobbligatorio
L’ID dell’iscritto (sub_…) o l’indirizzo email del contatto, codificato per l’URL.

Parametri del corpo

subscribedboolean
false per disiscrivere il contatto da questa lista, true per iscriverlo di nuovo. In entrambi i casi l’iscritto resta nella lista.
emailstring
Un nuovo indirizzo email per il contatto. Viene salvato in minuscolo.
first_namestring
Il nome del contatto.
last_namestring
Il cognome del contatto.
custom_fieldsobject
Valori dei campi personalizzati per chiave. Sostituiscono i campi personalizzati esistenti del contatto.

Restituisce

Restituisce l’oggetto iscritto aggiornato. Una richiesta senza nessuno di questi campi restituisce 400.

POST/audiences/{audience_id}/subscribers/{id}
Terminal
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Augusta"}'
Terminal
curl -X POST https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/ada%40example.com \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subscribed": false}'
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "first_name": "Ada",
  "last_name": "Lovelace",
  "custom_fields": {
    "company": "Analytical Engines"
  },
  "subscribed": false,
  "subscribed_at": "2026-10-01T10:20:31.000000Z",
  "unsubscribed_at": "2026-10-02T08:14:55.000000Z",
  "created_at": "2026-10-01T10:20:31.000000Z",
  "updated_at": "2026-10-02T08:14:55.000000Z"
}

Elenca gli iscritti

Restituisce una pagina degli iscritti di una lista, a partire dal più recente.

GET/audiences/{audience_id}/subscribers

Richiede una chiave API full. L’elenco include i contatti che si sono disiscritti dalla lista, a meno che non li escludi con subscribed=true.

Parametri di percorso

audience_idstringobbligatorio
L’ID della lista (aud_…) o il suo nome.

Parametri di query

pageintegerpredefinito: 1
La pagina da restituire.
limitintegerpredefinito: 25
Iscritti per pagina, da 1 a 100. Funziona anche per_page.
subscribedstring
true per i soli contatti iscritti, false per i soli disiscritti.
matchstringpredefinito: all
all o or. Come si combinano i filtri qui sotto.
orderstring
Una chiave di filtro per cui ordinare.
directionstring
asc o desc.

Filtri

Aggiungi i filtri nella forma key.condition=value, ad esempio email.ends_with=@acme.com. Vedi Filtri e ordinamento.

Chiave Tipo Note
email string
first_name string
last_name string
subscribed boolean
created_at date Quando il contatto è entrato nella lista.

Ogni chiave è anche una chiave di ordinamento.

Restituisce

dataobject[]
Gli oggetti iscritto di questa pagina.
next_page_urlstring | null
Percorso della pagina successiva, oppure null. Mantiene subscribed ma non gli altri filtri. Vedi Paginazione.
previous_page_urlstring | null
Percorso della pagina precedente, oppure null.
usageobject
used (iscritti nella lista), limit (il massimo consentito dal piano per ogni lista, oppure null) e plan.
GET/audiences/{audience_id}/subscribers
Terminal
curl https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
Terminal
curl -G https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -d subscribed=true \
  -d limit=100
JSON
{
  "data": [
    {
      "object": "subscriber",
      "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
      "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
      "email": "ada@example.com",
      "first_name": "Ada",
      "last_name": "Lovelace",
      "custom_fields": {
        "company": "Analytical Engines"
      },
      "subscribed": true,
      "subscribed_at": "2026-10-01T10:20:31.000000Z",
      "unsubscribed_at": null,
      "created_at": "2026-10-01T10:20:31.000000Z",
      "updated_at": "2026-10-01T10:20:31.000000Z"
    },
    {
      "object": "subscriber",
      "id": "sub_4KnmYprkoMRytdkm3tAHIfPW0Vh",
      "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
      "contact_id": "con_4KiXIs4xLTcJIAHnKJaLcnMZYh7",
      "email": "grace@example.com",
      "first_name": "Grace",
      "last_name": "Hopper",
      "custom_fields": null,
      "subscribed": false,
      "subscribed_at": "2026-09-28T07:55:02.000000Z",
      "unsubscribed_at": "2026-09-30T18:11:40.000000Z",
      "created_at": "2026-09-28T07:55:02.000000Z",
      "updated_at": "2026-09-30T18:11:40.000000Z"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null,
  "usage": {
    "used": 2,
    "limit": 50000,
    "plan": "pro"
  }
}

Elimina un iscritto

Rimuove un contatto da una lista.

DELETE/audiences/{audience_id}/subscribers/{id}

Richiede una chiave API full. Il contatto in sé non viene eliminato e resta nelle sue altre liste. Per conservare traccia del fatto che qualcuno ha scelto l’opt-out, disiscrivilo invece con subscribed: false. Genera un evento subscriber.deleted.

Parametri di percorso

audience_idstringobbligatorio
L’ID della lista (aud_…) o il suo nome.
idstringobbligatorio
L’ID dell’iscritto (sub_…) o l’indirizzo email del contatto, codificato per l’URL.

Restituisce

objectstring
Sempre subscriber.
idstring
L’ID dell’iscritto eliminato.
audience_idstring
L’ID della lista.
contact_idstring
L’ID del contatto.
emailstring
L’indirizzo email del contatto.
deletedboolean
Sempre true.
DELETE/audiences/{audience_id}/subscribers/{id}
Terminal
curl -X DELETE https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers/sub_4KECYl5AwXEy8ezswYRhuddttxo \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
JSON
{
  "object": "subscriber",
  "id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
  "audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
  "contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
  "email": "ada@example.com",
  "deleted": true
}

Questa pagina ti è stata utile?

Grazie del feedback.

Grazie, leggiamo ogni messaggio.