POST
Add an address to the newsletter list

Authorizations

Authorization
string
header
required

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.

Headers

Idempotency-Key
string
required

A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.

Body

application/json

AN UPSERT. An address already on the list is re-armed rather than duplicated, so re-running an import is safe and 201 does not mean the address was new. THE RESPONSE IS DELIBERATELY THIN: the address as stored, and whether this store runs double opt-in. It is not the subscriber resource, because a write scope does not imply its read on this API and the row would say whether the address was already here, when it joined and whether it had confirmed. Read GET /api/v1/newsletter-subscribers with read_newsletter for that. WHEN confirmation_required IS TRUE THE ADDRESS IS NOT REACHABLE YET. It is pending, this platform has emailed it a confirmation link, and every broadcast skips it until the recipient clicks. Queue a welcome series on this response and you are mailing an unconfirmed address.

email
string
required

The subscriber's identity on this list; there is no other key and no id. It is stored lowercased and trimmed, and the response carries the stored form rather than what you sent, so key your own records on what comes back.

source
string

Where the signup came from, free text (a form name, a channel, an import label). Recorded at signup only and never rewritten, so sending it again on a re-subscribe does not change it. Omit it when nothing recorded an origin; the read then serves null.

Response

Created

data
object