Gérer les abonnés à la newsletter via l'API REST xoPort. Prend en charge le double opt-in, la synchronisation avec les fournisseurs (Cleverreach, Mailchimp, Optimizely) et la journalisation de la confidentialité conforme au RGPD. Disponible depuis la version 2.8.0.
Point d'accès pour les abonnés à la newsletter
v2.8.0 · CRUD · Abonnés à la newsletter
Abonnés à la newsletter
Gérer les abonnés à la newsletter grâce au double opt-in (DOI), à la synchronisation automatique avec les fournisseurs d'accès et à la journalisation de la confidentialité conforme au RGPD.
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}Points de terminaison
| Méthode | Point de terminaison | Portée | Description |
|---|---|---|---|
| GET | /Export/JSON/newsletter_subscribers | newsletter:read | Lister tous les abonnés (avec filtres) |
| GET | /Export/JSON/newsletter_subscriber/{id} | newsletter:read | Récupérer un abonné spécifique |
| POST | /Import/JSON/newsletter_subscribers | newsletter:write | Créer un nouvel abonné (prise en charge du DOI) |
| PUT | /Import/JSON/newsletter_subscribers | newsletter:write | Mettre à jour un abonné existant |
| DELETE | /Delete/JSON/newsletter_subscriber/{id} | newsletter:delete | Supprimer un abonné (cascade RGPD) |
| DELETE | /Delete/JSON/newsletter_subscribers | newsletter:delete | Supprimer plusieurs abonnés (corps JSON) |
Filtres de requête (exportation)
| Paramètres | Description | Exemple |
|---|---|---|
?status=confirmed | Filtrer par statut de confirmation | confirmed ou unconfirmed |
?email=example.com | Partie de l'adresse e-mail ; % et _ sont considérés comme des caractères | contient |
?customer_id=42 | Uniquement les abonnés de ces clients | ID client, également sous forme de liste séparée par des virgules à partir de la version 2.122.10 de l'API |
?language_id=1 | Filtrer par langue | ID de langue, à partir de la version 2.122.10 de l'API, également sous forme de liste séparée par des virgules |
?last_modified=2026-01-01 | Delta à partir de la date : modifié, confirmé par double opt-in ou transfert vers le fournisseur de newsletter encore en attente (à partir de la version 2.122.10 de l'API) | YYYY-MM-DD, YYYY-MM-DD HH:MM ou YYYY-MM-DD HH:MM:SS, avec fuseau horaire en option |
À partir de la version 2.122.10 de l’API : les valeurs non valides, les valeurs de liste telles que ?status[]= et les dates/heures ne respectant pas les formats fixes génèrent une erreur HTTP 400 INVALID_FILTER_VALUE sans données ; une valeur vide est considérée comme non définie. La liste permet de parcourir la base de données avec ?limit= et ?offset=; stats.total indique le nombre de résultats. Les adresses supprimées et désabonnées ne figurent dans aucun delta ; il est donc recommandé de procéder régulièrement à une synchronisation complète.
Fonctionnalités
Double opt-in
Respecte la configuration de la boutique SHOP_NEWSLETTER_DOUBLE_OPT_IN. Lorsque le DOI est activé, un e-mail de confirmation est automatiquement envoyé.
Synchronisation avec les fournisseurs
Synchronisation automatique avec des fournisseurs de newsletters externes (Cleverreach, Mailchimp, Optimizely) via xoNewsletter.
Conformité au RGPD
Journalisation de la confidentialité lors de l'importation et de la suppression. La suppression en cascade documente toutes les étapes conformément à la réglementation sur la protection des données.
Inscription, confirmation et désabonnement
À partir de la version 2.122.9 de l'API (Shop 4.9.168), l'importation ne lève ni l'opposition à la publicité ni le blocage des newsletters.
| Cas | Comportement |
|---|---|
| Adresse avec blocage des newsletters ou opposition | POST refuse l'enregistrement : NEWSLETTER_LOCKED ou OPTED_OUT pour les clients utilisant customers:read, sinon NOT_SUBSCRIBABLE. Une adresse désabonnée ne peut être réabonnée qu'avec send_doi. À partir de la version 2.122.11 de l’API (boutique 4.9.171), le message concernant NEWSLETTER_LOCKED indique la marche à suivre pour lever le blocage : PUT /customers avec customers_nl_lock = 0. Cela ne fait que lever le blocage, et non pas annuler une désinscription : si le blocage a entraîné la désinscription d’un abonnement, l’adresse doit ensuite être réactivée via send_doi. |
| Double opt-in activé dans la boutique | Un « POST » sans « subscribe_confirm » envoie lui-même l'e-mail de confirmation, à raison d'un seul par adresse toutes les 24 heures au maximum. Une liste sans date de consentement déclenche donc l'envoi d'un e-mail pour chaque nouvelle adresse. |
subscribe_confirm | Uniquement une date fixe ou oui/non. Une date nulle, des indications relatives ou futures donnent lieu à INVALID_FIELD_VALUE. |
send_doi | Envoie expressément l’e-mail de confirmation. Réponse par enregistrement dans records[].confirmed et records[].doi_mail; codes DOI_UNAVAILABLE et DOI_MAIL_THROTTLED, avertissements CONFIRMED_WITHOUT_DOI, DOI_MAIL_FAILED et SUBSCRIBE_CID_MISMATCH. |
PUT | Ne confirme plus rien (FIELD_IGNORED_ON_UPDATE). subscribe_cid uniquement vers un compte ayant la même adresse ou 0. |
?_strict=true | Un champ inconnu génère une erreur HTTP 400 avant que quoi que ce soit ne soit écrit. |
Les boutiques utilisant une version de l’API antérieure à la version 2.122.9 ne reconnaissent pas send_doi et créent tout de même l’enregistrement : vérifiez au préalable api_version via GET /me.
Exemple : création d’un abonné
# 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
}]
}'Remarque : lorsque le DOI est activé, l’abonné est d’abord créé en tant que « non confirmé » et reçoit un e-mail de confirmation. Le champ subscribe_status_key (jeton de sécurité) n’est pas renvoyé dans l’exportation.
Suppression en masse
# 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"}
]
}'Les abonnés peuvent être identifiés via subscribe_id ou subscribe_email. Chaque suppression est consignée en tant qu’événement de confidentialité RGPD.
À partir de la version 2.122.9 de l’API, la suppression vérifie le résultat auprès du prestataire de newsletter. Si la désinscription échoue chez ce dernier, le chemin individuel renvoie un code HTTP 502 avec NEWSLETTER_UNSUBSCRIBE_FAILED, tandis que le traitement par lots indique l’erreur via errors[]; un code HTTP 404 chez le prestataire est considéré comme une désinscription réussie. En l'absence de prestataire de newsletter, la boutique supprime toutes les lignes correspondant à cette adresse et enregistre une opposition à la publicité.
