Unsubscribe API (Public)
Every commercial email Synapse sends carries a one-click unsubscribe link and a matching List-Unsubscribe header. Both point at this public, unauthenticated endpoint. The recipient — not your application — is the caller: they either click the link in the email footer or use their mail client's one-click "Unsubscribe" affordance (Gmail, Yahoo, Apple Mail).
You do not normally call this endpoint yourself. It is documented here so you understand the destination of the unsubscribe links in your commercial emails and can verify the flow end to end.
This is the only public, unauthenticated endpoint in the Synapse API. There is no API key or JWT. The signed token embedded in the URL is the authorization, and it is scoped to a single contact in a single workspace. A token minted for one workspace can never affect another workspace's contacts.
Endpoints
| Method | Path | Mutates? | Description |
|---|---|---|---|
GET | /v1/public/unsubscribe?token=… | No | Renders a confirmation page. Never unsubscribes on its own. |
POST | /v1/public/unsubscribe?token=… | Yes | Unsubscribes the contact (idempotent). Serves both the confirmation form and RFC 8058 one-click. |
Both return an HTML page (Content-Type: text/html), not JSON — the caller is a mail client or a browser, not code.
The token
The token query parameter is an opaque, signed string that Synapse generates when it sends a commercial email. It encodes which contact to unsubscribe and which workspace they belong to, and it is signed so it cannot be forged or tampered with. Treat it as a black box:
- Do not construct tokens yourself. They are minted per recipient, per send, inside Synapse.
- Do not parse or modify them. Any alteration invalidates the signature.
- They do not expire. A one-click unsubscribe link in a two-year-old email thread still works — CAN-SPAM requires this.
Because tokens never expire, they remain valid until the recipient unsubscribes. There is no need to refresh or reissue them.
GET — Confirmation page
Returns a minimal HTML page with a Confirm unsubscribe button. The button submits a POST to the same URL. A GET never changes the contact's subscription status — this is deliberate: corporate mail-security scanners pre-fetch links in inbound email, and a mutating GET would silently unsubscribe recipients whose IT department scanned the message.
| Status | When |
|---|---|
200 | Valid token — renders the confirmation page. |
400 | Malformed or invalid token — renders a generic "link no longer valid" page. |
422 | The token query parameter is absent entirely. |
429 | Too many requests from the same IP in a short window — renders a "try again shortly" page. |
The 400 page is intentionally generic. It never reveals why a token was rejected, so it cannot be used as an oracle to probe the token space.
POST — Unsubscribe
Verifies the token and sets the contact's subscription_status to unsubscribed, then returns a success page. The operation is idempotent — posting the same token again is a no-op and still returns the success page.
The token is read from the query string first (this is where RFC 8058 one-click puts it), falling back to a form-body token field (this is what the confirmation page's form submits). Either works.
| Status | When |
|---|---|
200 | Valid token — the contact is now unsubscribed (or already was). Renders the success page. |
400 | Token missing from both the query string and the form body, or malformed, or invalid. |
429 | Per-IP rate limit exceeded. |
Once a contact is unsubscribed, Synapse suppresses all future commercial email to them. Transactional email (for example password resets and receipts) is unaffected — an unsubscribe is an opt-out of marketing, not of service messages.
One-click unsubscribe (RFC 8058)
Every commercial email Synapse sends includes two headers alongside the footer link:
Together these satisfy the one-click unsubscribe requirement that Gmail, Yahoo, and Apple Mail enforce for bulk senders. When a recipient uses the mail client's built-in "Unsubscribe" control, the client issues a POST to the URL in the List-Unsubscribe header with the body List-Unsubscribe=One-Click. Synapse honors it exactly like a form submit — the presence of a valid token is all that matters.
See Email Delivery for how these headers fit into overall deliverability.
What you do — and don't — need to do
| You are responsible for | Synapse handles automatically |
|---|---|
| Adding your workspace's complete company address in Settings → General (required before any commercial send). | Generating the per-recipient unsubscribe token. |
Marking service emails as transactional on the Direct Send API so they stay exempt. | Injecting the footer link and List-Unsubscribe headers on every commercial send. |
| — | Rendering the confirmation and success pages. |
| — | Suppressing future commercial email to unsubscribed contacts. |
A commercial send from a workspace with no complete company address is suppressed — no email is sent — because a commercial email without a physical mailing address is itself a CAN-SPAM violation. Complete your company information in Settings → General before sending commercial email. See Direct Send API and Email Delivery.