Newsletter

GET /admin/newsletter/subscribers

Visibilité back-office sur la liste de diffusion (jusqu’ici aucune). Renvoie un bloc counts (répartition par statut, toujours présent) et un export paginé (keyset) filtrable par status. Pour récupérer la liste de diffusion réelle, filtrer ?status=confirmed.

Sécurité : les hash de tokens (confirm / unsubscribe) ne sont jamais exposés — ce sont des secrets serveur qui ouvriraient une surface sur les liens un-clic. Lecture seule, via un service dédié (NewsletterSubscriberDirectory).

Query params

Param	Valeurs	Défaut	Notes
status	pending | confirmed | unsubscribed	tous	valeur invalide = 400 (pas d’ignore silencieux)
limit	1..500	100	orienté export, borné en dur
cursorAt	ISO-8601	aucun	created_at du dernier item de la page précédente. À fournir avec cursorId (les deux ou aucun).
cursorId	hex (32 chars)	aucun	id du dernier item — discriminant pour les created_at identiques.

Tri implicite : created_at DESC, id DESC (inscriptions les plus récentes). Index dédié idx_status_created (status, created_at).

Réponse (200)

{
  "counts": { "pending": 3, "confirmed": 42, "unsubscribed": 5, "total": 50 },
  "items": [
    {
      "id":             "d26d1600cde54bd095e09f8b68ace05f",
      "email":          "jane@example.com",
      "status":         "confirmed",
      "locale":         "fr",
      "source":         "footer",
      "userId":         "ab…",          // hex ou null (inscrit relié à un compte)
      "ipAddress":      "203.0.113.7",   // ou null
      "userAgent":      "Mozilla/5.0 …", // ou null
      "confirmedAt":    "2026-06-18T10:05:00+00:00",
      "unsubscribedAt": null,
      "createdAt":      "2026-06-18T10:00:00+00:00",
      "updatedAt":      "2026-06-18T10:05:00+00:00"
    }
  ],
  "nextCursor": { "at": "2026-06-18T10:00:00+00:00", "id": "d26d…" }
  // `null` quand la page courante contient < `limit` items (= dernière page)
}

counts reflète toute la table (non filtré par status), items reflète le filtre courant : un export ?status=confirmed montre 42 items même si counts.total vaut 50.

Erreurs

Status	Body	Sens
400	{ "error": "Query parameter 'status' must be one of: pending, confirmed, unsubscribed." }	statut inconnu
400	{ "error": "Both cursorAt and cursorId must be supplied together." }	demi-curseur
400	{ "error": "cursorAt is not a valid datetime." }	parsing Carbon KO
400	{ "error": "cursorId is not a valid hex UUID." }	hex malformé
403	{ "error": "..." }	auth KO

Exemple curl

# Compteurs + export de la liste de diffusion confirmée
curl -s -H "Authorization: Bearer $ADMIN_API_TOKEN" \
  "http://hydrogen.dev.com/admin/newsletter/subscribers?status=confirmed&limit=500"

# Page suivante
curl -s -H "Authorization: Bearer $ADMIN_API_TOKEN" \
  "http://hydrogen.dev.com/admin/newsletter/subscribers?status=confirmed&limit=500&cursorAt=2026-06-18T10:00:00%2B00:00&cursorId=d26d1600cde54bd095e09f8b68ace05f"

---