Skip to content

Area: Developers

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.

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.

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.

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.

Releva adds two headers to every email it sends:

List-Unsubscribe-Post: List-Unsubscribe=One-Click
List-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.

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" }'

200 with an empty body. The customer has been unsubscribed when the response arrives.

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

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.

  • No rate limits on these endpoints.
  • One customer per link.