API reference · 3 operations

Unsubscribe

One-click and confirmed unsubscribe from our own email.

Unsubscribe from the confirmation page

POST/v1/unsubscribe/confirm

What the button on /unsubscribe calls. Same effect as one-click; separate route so the two sources can be told apart afterwards.

Needs: Nothing. This route is public.

Request body · UnsubscribeTokenDto
FieldTypeWhat it is
token requiredstringThe token from the unsubscribe link.
Responses
StatusBodyWhen
200UnsubscribeResultDto
400—The link is not valid.
200 body · UnsubscribeResultDto
FieldTypeWhat it is
email requiredstringThe address this link unsubscribes.
alreadyUnsubscribed requiredbooleanTrue when the address was already on the suppression list.
unsubscribed requiredbooleanAlways true once the call succeeds — including when it was already done.

One-click unsubscribe (RFC 8058)

POST/v1/unsubscribe/one-click

The POST target advertised in List-Unsubscribe. Unauthenticated, immediate and without confirmation. Idempotent: a repeat call succeeds.

Needs: Nothing. This route is public.

Parameters
NameWhereTypeWhat it is
token requiredquerystring
Responses
StatusBodyWhen
200UnsubscribeResultDto
400—The link is not valid.
200 body · UnsubscribeResultDto
FieldTypeWhat it is
email requiredstringThe address this link unsubscribes.
alreadyUnsubscribed requiredbooleanTrue when the address was already on the suppression list.
unsubscribed requiredbooleanAlways true once the call succeeds — including when it was already done.

Look up an unsubscribe token without spending it

GET/v1/unsubscribe/status

Lets the confirmation page name the address before anything happens. A GET must never unsubscribe: link scanners, antivirus proxies and inbox previews fetch URLs on the recipient behalf, and an opt-out performed by a crawler is an opt-out the recipient never chose.

Needs: Nothing. This route is public.

Parameters
NameWhereTypeWhat it is
token requiredquerystring
Responses
StatusBodyWhen
200UnsubscribeStatusDto
400—The link is not valid.
200 body · UnsubscribeStatusDto
FieldTypeWhat it is
email requiredstringThe address this link unsubscribes.
alreadyUnsubscribed requiredbooleanTrue when the address was already on the suppression list.

Next groupHealth