Unsubscribe links and one-click unsubscribe
Releva puts unsubscribe links into every message it sends, so you do not have to build them. This page explains where each link goes, and documents the endpoints behind them for when you test or debug them.
When to use it
Section titled “When to use it”Read it when you design email templates, test unsubscribes, or debug a “the link did not work” report. You never call these endpoints from your own code: Releva builds the encrypted {payload} in each link when it renders the message, and the links need no authorization header. To unsubscribe a customer from your own system, use Unsubscribe a customer with the API.
Where each link goes
Section titled “Where each link goes”| Link | Internal mode | External mode |
|---|---|---|
{{unsubscribeLink}} merge tag |
The subscription preferences page | The customer’s own unsubscribeLink, or your Email Unsubscribe URL with encodedEmail, encodedPhoneNumber and url added (see External mode) |
{{subscriptionManagementLink}} merge tag |
The subscription preferences page | Same as {{unsubscribeLink}} |
List-Unsubscribe email header |
POST /api/v0/unsubscribe/oneclick/{payload}, the one-click endpoint below |
Same as {{unsubscribeLink}} |
{{subscribeLink}} merge tag |
The double opt-in confirmation, see Set up double opt-in | Empty |
In Internal mode all links are served from your shop’s click-tracking host.
The subscription preferences page
Section titled “The subscription preferences page”In Internal mode, {{unsubscribeLink}} and {{subscriptionManagementLink}} open a page titled Subscription preferences. It shows your shop’s user-visible subscriptions with the ones the customer holds switched on (all off for a customer who is not subscribed), in your shop’s language when that is Bulgarian, German, Greek or Romanian, and in English otherwise.
- Save preferences subscribes the customer with the subscriptions they switched on and removes the ones they switched off. Subscriptions that are not user-visible are left alone.
- Unsubscribe from all lists, or saving with every subscription switched off, unsubscribes the customer shop-wide, the same as
POST /api/v0/unsubscribe.
You choose which subscriptions appear, and their captions, under User Visible Subscriptions in Settings › Messaging; see Choose how Releva manages subscriptions.
The page reads and saves through GET and POST /api/v0/profiles/subscriptions. Both take the encrypted values from the link, not your keys, so they are for the page only.
One-click unsubscribe (RFC 8058)
Section titled “One-click unsubscribe (RFC 8058)”Releva adds two headers to every email it sends:
List-Unsubscribe-Post: List-Unsubscribe=One-ClickList-Unsubscribe: <https://click-tracking-host/api/v0/unsubscribe/oneclick/PAYLOAD>When the customer selects the unsubscribe option of their mail client, the mail client posts to that URL. Releva unsubscribes the customer shop-wide, the same as POST /api/v0/unsubscribe. In External mode the header carries the same link as {{unsubscribeLink}}, so your page receives the request.
Request
Section titled “Request”POST /api/v0/unsubscribe/oneclick/{payload}. No authorization header. The body must be List-Unsubscribe=One-Click, either form-encoded (as mail clients send it) or as JSON.
| Field | Type | Notes |
|---|---|---|
List-Unsubscribe |
string | Must be exactly One-Click. |
To test it, copy the URL from the List-Unsubscribe header of an email you received:
curl -X POST "$LIST_UNSUBSCRIBE_URL" \ -H 'content-type: application/json' \ -d '{ "List-Unsubscribe": "One-Click" }'Response
Section titled “Response”200 with an empty body. The customer has been unsubscribed when the response arrives.
Errors
Section titled “Errors”Errors are plain text, not JSON.
| Status | When | Body |
|---|---|---|
400 |
The body is missing, or List-Unsubscribe is not One-Click |
Bad Request |
400 |
The payload is broken or changed | Bad Request |
500 |
The opt-out could not be saved | Internal Server Error |
The same URL opened in a browser
Section titled “The same URL opened in a browser”GET /api/v0/unsubscribe/oneclick/{payload} unsubscribes as well, and shows a page that redirects to your shop after 10 seconds. The page is in Bulgarian or Greek when that is your shop’s language, and in English otherwise.
| Status | Page title (English) | Text |
|---|---|---|
200 |
Unsubscribe Successful | Email address "maria@example.com" has been successfully unsubscribed. (or Phone number "..." for a phone link) |
400 |
Unsubscribe Failed | The unsubscribe link you followed seems to be invalid. |
500 |
Unsubscribe Failed | We encountered an internal error and were unable to unsubscribe you. |
Because a plain GET changes state, security scanners that open every link in an email can unsubscribe a customer this way.
Limits
Section titled “Limits”- No rate limits on these endpoints.
- One customer per link.