Iscritti
Aggiungi, aggiorna e rimuovi gli iscritti di una lista.
Aggiungi un iscritto
Aggiunge un contatto a una lista tramite l’indirizzo email.
/audiences/{audience_id}/subscribersRichiede 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_idstringobbligatorioaud_…) o il suo nome.Parametri del corpo
emailstringobbligatoriofirst_namestringlast_namestringcustom_fieldsobjectI 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.
{
"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"
}{
"error": "Audience not found"
}{
"error": "Contact is already subscribed to this audience",
"existing": {
"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.000Z",
"unsubscribed_at": null,
"created_at": "2026-10-01T10:20:31.000Z",
"updated_at": "2026-10-01T10:20:31.000Z"
}
}{
"error": "Pro includes 50,000 subscribers per audience.",
"usage": {
"used": 50000,
"limit": 50000,
"plan": "pro"
}
}Recupera un iscritto
Recupera l’appartenenza di un contatto a una lista.
/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_idstringobbligatorioaud_…) o il suo nome.idstringobbligatoriosub_…) o l’indirizzo email del contatto, codificato per l’URL.Restituisce
Restituisce l’oggetto iscritto.
objectstringsubscriber.idstringaudience_idstringcontact_idstringemailstringfirst_namestring | nulllast_namestring | nullcustom_fieldsobject | nullsubscribedbooleantrue se il contatto è iscritto a questa lista, false se si è disiscritto.subscribed_atstring | nullunsubscribed_atstring | nullnull.created_atstringupdated_atstring{
"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"
}{
"error": "Subscriber not found"
}Aggiorna un iscritto
Modifica lo stato di un iscritto nella lista, oppure i dati del suo contatto.
/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_idstringobbligatorioaud_…) o il suo nome.idstringobbligatoriosub_…) o l’indirizzo email del contatto, codificato per l’URL.Parametri del corpo
subscribedbooleanfalse per disiscrivere il contatto da questa lista, true per iscriverlo di nuovo. In entrambi i casi l’iscritto resta nella lista.emailstringfirst_namestringlast_namestringcustom_fieldsobjectRestituisce
Restituisce l’oggetto iscritto aggiornato. Una richiesta senza nessuno di questi campi restituisce 400.
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}'{
"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"
}{
"error": "No valid fields provided for update. Provide at least one of: email, first_name, last_name, custom_fields, subscribed"
}{
"error": "Subscriber not found"
}Elenca gli iscritti
Restituisce una pagina degli iscritti di una lista, a partire dal più recente.
/audiences/{audience_id}/subscribersRichiede 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_idstringobbligatorioaud_…) o il suo nome.Parametri di query
pageintegerpredefinito: 1limitintegerpredefinito: 25per_page.subscribedstringtrue per i soli contatti iscritti, false per i soli disiscritti.searchstringmatchstringpredefinito: allall o or. Come si combinano i filtri qui sotto.orderstringdirectionstringasc 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[]next_page_urlstring | nullnull. Mantiene subscribed ma non gli altri filtri. Vedi Paginazione.previous_page_urlstring | nullnull.usageobjectused (iscritti nella lista), limit (il massimo consentito dal piano per ogni lista, oppure null) e plan.curl -G https://api.emailit.com/v2/audiences/aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2/subscribers \
-H "Authorization: Bearer $EMAILIT_API_KEY" \
-d subscribed=true \
-d limit=100{
"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"
}
}{
"error": "Audience not found"
}Elimina un iscritto
Rimuove un contatto da una lista.
/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_idstringobbligatorioaud_…) o il suo nome.idstringobbligatoriosub_…) o l’indirizzo email del contatto, codificato per l’URL.Restituisce
objectstringsubscriber.idstringaudience_idstringcontact_idstringemailstringdeletedbooleantrue.{
"object": "subscriber",
"id": "sub_4KECYl5AwXEy8ezswYRhuddttxo",
"audience_id": "aud_4KbFmQPy1feMCGAY8F8pAhiZ1u2",
"contact_id": "con_4K9kQdrXth7am0TPKvPrR5yd2oo",
"email": "ada@example.com",
"deleted": true
}{
"error": "Subscriber not found"
}