POST
Mint this contact's preference and unsubscribe links

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.

Path Parameters

contactId
string
required

Body

application/json

Takes no parameters, and an empty body is expected. Use this when you send marketing mail through your own provider: the unsubscribe_url is the functional CAN-SPAM link and belongs both in the mail body and in the List-Unsubscribe header. A WRITE DESPITE STORING NOTHING. The response is a CAPABILITY: the token in these URLs is what authorises a consent change from an inbox, so anyone who holds one can unsubscribe this contact. Treat a minted link as a secret belonging to that one recipient, and mint per recipient rather than reusing one. THE BODY IS NOT REPLAYABLE. This route is exempt from the idempotency ledger's response storage, because storing a capability there would keep it readable long after the send; a replayed Idempotency-Key answers 201 with an empty body. Use a fresh key, or mint again, rather than replaying. THE LINKS DO NOT EXPIRE by default, which is deliberate: a recipient may act on a months-old email, and a link that quietly expired into a failure is itself a compliance breach. 409 preference_center_disabled when the merchant has the surface switched off, and 409 preference_center_not_configured when the platform cannot sign a link at all. Both mean the same thing to a sender: there is no working unsubscribe link, so HOLD the send rather than mailing without one. GET /api/v1/marketing-preferences/settings answers that ahead of time without spending a write.

Response

Created

data
object