These URLs are public and are not protected by an API key. They could not be: the person
clicking is a recipient in their mail client, not a caller of your integration. What protects them
is the token in the URL — long, opaque, tied to one contact and one send. Anyone holding the
token can act, which is exactly what a recipient must be able to do from an email, in one click,
without logging in.
The links
| URL | Method | Who opens it | Answer |
|---|---|---|---|
/api/o/{token} | GET | The recipient's mail client, on open | A 1×1 transparent GIF |
/api/t/{token} | GET | The recipient, on a click | A 302 to the real destination |
/api/unsubscribe/{token} | POST | The mail client (RFC 8058 one-click) | Neutral, whatever the token is worth |
/unsubscribe/{token} | page | The recipient, from the email footer | The unsubscribe page |
/subscribe/confirm/{token} | page | A new contact, from the opt-in email | The confirmation page |
Open tracking — GET /api/o/{token}
The pixel records the open and returns the GIF. Every failure is swallowed: an unknown token, a
database that is down, anything — the answer is still a 200 and a valid image. An email already in
an inbox must never display a broken picture because of an incident on our side.
Click tracking — GET /api/t/{token}
Records the click, then redirects to the target URL. Any failure path — unknown token, malformed
URL, database down — redirects to a neutral page instead. Same principle: never a 500 in a mail
that has already left.
One-click unsubscribe — POST /api/unsubscribe/{token}
The target of the List-Unsubscribe-Post header (RFC 8058), called by Gmail and friends when the
recipient uses their client's own unsubscribe button. Rate-limited by IP.
The answer is always neutral: an unknown token gets the same response as a valid one. Confirming
that a token exists would confirm that an address is in a list.
Double opt-in confirmation — /subscribe/confirm/{token}
A contact created through the double opt-in flow lands in pending and receives a confirmation
mail. Opening the link moves it to subscribed. Until then it is in the audience but receives
nothing.
There is no public "subscribe" endpoint. A contact enters an audience through
POST /api/v1/lists/{listId}/contacts, with an API key — see the
Audience API. Confirmation is the only public half of the flow, and it is a page,
not an API. Nobody can push contacts into your lists from the outside.What this means for the API
The status of a contact is the meeting point between these public links and the API, and the API deliberately gives way:PATCH /api/v1/contacts/{contactId}ignores astatussent in the body. Subscription state changes through explicit acts only.- An upsert never silently resurrects an unsubscribed contact.
- A recipient who unsubscribed from their mail client is unsubscribed for good; only
POST /api/v1/contacts/{contactId}/resubscribecan undo it, and never for abouncedaddress.
/api/v1. It exists only inside the
emails that were sent to that contact.