Skip to content

Area: Developers

Choose a consent call

A customer’s consent in Releva changes through several doors: your server, your storefront, the admin and the links in Releva’s messages. Use this page to pick the call for your case. What subscribed, unsubscribed and subscriptions mean on a profile is in How consent works in Releva.

You want to Call Key Page
Subscribe a customer from your server, or sync their preferences from your system POST /api/v0/subscribe Secret key Subscribe a customer from your server
Subscribe from a sign-up form on your site Releva.requestSubscribe(...) or POST /api/v0/subscribe/request Access token Subscribe a customer from the browser
Make sign-ups from your site wait for an email confirmation The setting Wait for confirmation, plus a workflow with {{subscribeLink}} Access token Set up double opt-in
Change one subscription without opting the customer out POST /api/v0/subscribe with addSubscriptions and removeSubscriptions Secret key Subscribe a customer from your server
Opt a customer out from your system, or from your own unsubscribe page in External mode POST /api/v0/unsubscribe Secret key Unsubscribe a customer with the API
Let customers unsubscribe from a message Nothing to call: Releva adds {{unsubscribeLink}} and the List-Unsubscribe header None Unsubscribe links and one-click unsubscribe
Show a new-subscriber offer only to addresses that never subscribed Releva.checkSubscribed(...) or POST /api/v0/subscribe/check Access token Check an email’s consent history
Send many profiles at once, with their consent fields POST /api/v0/profiles Secret key Profiles API overview

Never put the secret key in a browser or an app. The access token is made for them.

Every way a profile’s consent can change, and what it does:

Action Who triggers it What it does
POST /api/v0/subscribe Your server Subscribes right away, creates the profile if needed, and replaces, adds or removes subscriptions. Ignores Subscription Request Behavaior.
POST /api/v0/subscribe/request Your storefront, through Releva.requestSubscribe or your own form Subscribe right away: subscribes, and tags the subscribe event request. Wait for confirmation: records a subscribeRequest event and subscribes nobody yet.
{{subscribeLink}} in a message The customer Confirms a pending request and subscribes with the subscriptions that request carried. Internal mode only.
Subscribe button on a profile An admin user Subscribes right away. When the profile holds none of your user-visible subscriptions, adds them all. Shown only in Internal mode.
POST /api/v0/unsubscribe Your server Opts out shop-wide and removes the user-visible subscriptions. An unknown email address or phone number creates a new, unsubscribed profile.
Unsubscribe button on a profile An admin user The same as POST /api/v0/unsubscribe. Shown only in Internal mode.
{{unsubscribeLink}}, {{subscriptionManagementLink}} The customer Internal: the Subscription preferences page, where the customer changes subscriptions or unsubscribes from all. External: your shop’s unsubscribe page, which must call POST /api/v0/unsubscribe.
List-Unsubscribe email header The customer’s mail client Internal: one-click opt-out (RFC 8058). External: the same link as {{unsubscribeLink}}.

Every change records an event on the profile: subscribe when it becomes subscribed, subscriptionsChanged when its list changes, unsubscribe on an opt-out, and subscribeRequest for a pending confirmation. Workflows and segments can use them.

Subscription Management in Settings › Messaging decides who owns consent, and so which calls you need:

  • Internal: Releva owns consent. Releva’s links and the admin buttons change it for you. Call the API only for changes that start in your own system.
  • External: your shop owns consent. Releva links to your unsubscribe page, and your shop must call POST /api/v0/unsubscribe after each opt-out, and POST /api/v0/subscribe (or send consent with POST /api/v0/profiles) after each opt-in. Double opt-in through {{subscribeLink}} is not available.