Gestione degli iscritti alla newsletter tramite l'API REST di xoPort. Supporta il double opt-in, la sincronizzazione con i provider (Cleverreach, Mailchimp, Optimizely) e la registrazione dei dati relativi alla privacy conforme al GDPR. Disponibile a partire dalla versione 2.8.0.
Punto finale per gli iscritti alla newsletter
v2.8.0 · CRUD · Abbonati alla newsletter
Abbonati alla newsletter
Gestione degli iscritti alla newsletter con double opt-in (DOI), sincronizzazione automatica con i provider e registrazione dei dati sulla privacy conforme al GDPR.
GET /Export/JSON/newsletter_subscribers
GET /Export/JSON/newsletter_subscriber/{id}
POST /Import/JSON/newsletter_subscribers
PUT /Import/JSON/newsletter_subscribers
DELETE /Delete/JSON/newsletter_subscriber/{id}Endpoint
| Metodo | Endpoint | Ambito | Descrizione |
|---|---|---|---|
| GET | /Export/JSON/newsletter_subscribers | newsletter:read | Elenca tutti gli abbonati (con filtri) |
| GET | /Export/JSON/newsletter_subscriber/{id} | newsletter:read | Recupera un singolo abbonato |
| POST | /Import/JSON/newsletter_subscribers | newsletter:write | Crea un nuovo abbonato (supporto DOI) |
| PUT | /Import/JSON/newsletter_subscribers | newsletter:write | Aggiornare un abbonato esistente |
| DELETE | /Delete/JSON/newsletter_subscriber/{id} | newsletter:delete | Elimina abbonato (cascata GDPR) |
| DELETE | /Delete/JSON/newsletter_subscribers | newsletter:delete | Elimina più abbonati (corpo JSON) |
Filtri di query (esportazione)
| Parametri | Descrizione | Esempio |
|---|---|---|
?status=confirmed | Filtra in base allo stato di conferma | confirmed oppure unconfirmed |
?email=example.com | Parte dell'indirizzo e-mail; % e _ sono considerati caratteri | contiene |
?customer_id=42 | Solo gli iscritti di questi clienti | ID cliente, a partire dalla versione API 2.122.10 anche come elenco separato da virgole |
?language_id=1 | Filtra per lingua | ID lingua, a partire dalla versione API 2.122.10 anche come elenco separato da virgole |
?last_modified=2026-01-01 | Delta a partire dal momento: modificato, confermato tramite double opt-in o trasferimento al fornitore della newsletter ancora in sospeso (a partire dalla versione API 2.122.10) | YYYY-MM-DD, YYYY-MM-DD HH:MM o YYYY-MM-DD HH:MM:SS, facoltativamente con fuso orario |
A partire dalla versione API 2.122.10: valori non validi, valori di elenco come ?status[]= e date al di fuori dei formati prestabiliti generano un errore HTTP 400 INVALID_FILTER_VALUE senza dati; un valore vuoto è considerato non impostato. L'elenco scorre il database con ?limit= e ?offset=, mentre stats.total indica il numero di risultati. Gli indirizzi cancellati e quelli disattivati non sono presenti in nessun delta, pertanto è necessario eseguire regolarmente una sincronizzazione completa.
Funzionalità
Double-Opt-In
Rispetta la configurazione del negozio SHOP_NEWSLETTER_DOUBLE_OPT_IN. Se il DOI è attivato, viene inviata automaticamente un’e-mail di conferma.
Sincronizzazione con i provider
Sincronizzazione automatica con provider di newsletter esterni (Cleverreach, Mailchimp, Optimizely) tramite xoNewsletter.
Conformità al GDPR
Registrazione dei dati relativi alla privacy in caso di importazione ed eliminazione. La cancellazione a cascata documenta tutte le fasi in conformità con la normativa sulla protezione dei dati.
Iscrizione, conferma e blocco
A partire dalla versione API 2.122.9 (Shop 4.9.168), l’importazione non revoca l’opposizione alla pubblicità né il blocco delle newsletter.
| Caso | Comportamento |
|---|---|
| Indirizzo con blocco delle newsletter o opposizione | POST rifiuta il record: NEWSLETTER_LOCKED o OPTED_OUT per i client con customers:read, altrimenti NOT_SUBSCRIBABLE. Un indirizzo disiscritto può essere reiscritto solo tramite send_doi. A partire dalla versione API 2.122.11 (Shop 4.9.171), il messaggio relativo a NEWSLETTER_LOCKED indica la procedura per sbloccare l’indirizzo: PUT /customers con customers_nl_lock = 0. Questo serve solo a sbloccare l’indirizzo, non a revocare l’opposizione: se il blocco ha comportato la cancellazione di un abbonamento, l’indirizzo dovrà successivamente utilizzare send_doi. |
| Double-opt-in attivo nel negozio | Un POST senza subscribe_confirm invia autonomamente l’e-mail di conferma, al massimo una per indirizzo ogni 24 ore. Una lista senza data di consenso genera quindi un’e-mail per ogni nuovo indirizzo. |
subscribe_confirm | Solo un momento fisso o sì/no. Data nulla, indicazioni relative o future generano INVALID_FIELD_VALUE. |
send_doi | Invia espressamente l’e-mail di conferma. Risposta per ogni record in records[].confirmed e records[].doi_mail; codici DOI_UNAVAILABLE e DOI_MAIL_THROTTLED, avvisi CONFIRMED_WITHOUT_DOI, DOI_MAIL_FAILED e SUBSCRIBE_CID_MISMATCH. |
PUT | Non conferma più nulla (FIELD_IGNORED_ON_UPDATE). subscribe_cid solo su un account con lo stesso indirizzo oppure 0. |
?_strict=true | Un campo sconosciuto genera un errore HTTP 400 prima che venga scritto qualcosa. |
I negozi con versione API precedente alla 2.122.9 non riconoscono send_doi e creano comunque il record: in tal caso, verificare prima api_version tramite GET /me.
Esempio: creazione di un abbonato
# POST - Neuen Abonnenten mit DOI anlegen
curl -X POST "https://shop.de/xpanel/xoport/Import/JSON/newsletter_subscribers" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "newsletter_subscribers",
"data": [{
"subscribe_email": "kunde@example.com",
"subscribe_firstname": "Max",
"subscribe_lastname": "Mustermann",
"subscribe_language_id": 1
}]
}'Nota: se il DOI è attivato, l’abbonato viene inizialmente creato come “unconfirmed” e riceve un’e-mail di conferma. Il campo subscribe_status_key (token di sicurezza) non viene restituito nell’esportazione.
Eliminazione in blocco
# Mehrere Abonnenten per JSON-Body löschen
curl -X DELETE "https://shop.de/xpanel/xoport/Delete/JSON/newsletter_subscribers" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"type": "newsletter_subscribers",
"data": [
{"subscribe_id": 5},
{"subscribe_email": "abmelden@example.com"}
]
}'Gli iscritti possono essere identificati tramite subscribe_id o subscribe_email. Ogni cancellazione viene registrata come evento relativo alla privacy ai sensi del GDPR.
A partire dalla versione 2.122.9 dell’API, la funzione di cancellazione verifica il risultato presso il fornitore della newsletter. Se la cancellazione non va a buon fine, il percorso singolo risponde con un codice HTTP 502 NEWSLETTER_UNSUBSCRIBE_FAILED, mentre il batch indica l’errore in errors[]; un codice HTTP 404 presso il fornitore è considerato come cancellazione avvenuta. In assenza di un fornitore di newsletter, il negozio elimina tutte le righe relative all’indirizzo e registra un’opposizione alla pubblicità.
