List newsletter subscribers
The store’s newsletter list: the address, its consent state, where it joined and when that state last moved. THERE IS NO id FIELD AND THERE WILL NOT BE ONE. The address is the identity: the underlying row is keyed on (store, email) and carries no surrogate, so key your own records on email. It comes back lowercased and trimmed whatever you sent. updated_at is what a suppression sync reconciles on. It is the moment the consent state moved, so a nightly job reads only the rows that changed instead of the whole list.
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Query Parameters
Filter by consent state. Omit it to receive all three. An unrecognised value is a 400 rather than an empty page: a client filtering on "active" would otherwise conclude the store has no subscribers at all. pending exists only where the store runs double opt-in and those addresses receive no broadcasts, so counting them as reachable overstates the list.
pending, subscribed, unsubscribed EXACT match on one address, normalised the same way stored addresses are, so casing and surrounding whitespace do not matter. This is how you ask "is this address on the list, and what is its consent state": there is no per-address route, because a subscriber has no id and putting an address in a path would write it into every proxy and access log verbatim. A malformed address is a 400 rather than an empty page.
Rows per page. Out of range is a 400 rather than a silent clamp, so a client asking for more than 100 learns it did not get it.
1 <= x <= 100The next_cursor from the previous page. Opaque: decode nothing from it and construct nothing by hand, since its encoding is not part of this contract. Omit it to read the first page.