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.
Pick a call
Section titled “Pick a call”| 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.
Ways in and out
Section titled “Ways in and out”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.
Internal or External
Section titled “Internal or External”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/unsubscribeafter each opt-out, andPOST /api/v0/subscribe(or send consent withPOST /api/v0/profiles) after each opt-in. Double opt-in through{{subscribeLink}}is not available.