Skip to content

Area: Developers

Subscribe a customer from your server

POST https://releva.ai/api/v0/subscribe subscribes one customer to marketing messages and sets their subscriptions. It creates the profile when Releva does not know the email address or phone number yet.

If you send information about non-subscribed users to Releva, call it from your server once such a user subscribes. When a user updates their subscription preferences, call it with the new set of subscriptions. It always subscribes right away: the Subscription Request Behavaior setting does not apply to it.

Never call it from a browser or an app. It needs your secret key. To subscribe from a sign-up form on your site, use Subscribe a customer from the browser instead.

Send your shop’s secret key as a bearer token:

authorization: Bearer $RELEVA_SECRET_KEY

Find it under Settings › Shop & Integration; see Find your Access Token and Secret Key.

Authentication failures answer 400, not 401:

Problem Message
No authorization header Authorization header is missing.
The header is not Bearer followed by a token Authorization header is malformed. It should look like `Bearer <string>`.
The token is not a UUID Authorization header contains an invalid Bearer token.
No shop has this secret key (also when you send the access token here) Domain with the provided secret key cannot be found.

A shop that is switched off answers 402 with Domain is disabled. Please reach out to support@releva.ai to enable it.

POST /api/v0/subscribe with content-type: application/json. Every field is optional. Send email, phoneNumber or both: the endpoint does not reject a body that has neither, so check it on your side.

Field Type Notes
email string The customer’s email address.
phoneNumber string International format with a leading + and digits only, for example +15555550199. A number without + gets your shop country’s dialling code added before it is checked.
firstName string Stored on the profile.
lastName string Stored on the profile.
birthday string Date only, exactly YYYY-MM-DD, for example 1990-05-21.
subscriptions array of strings Subscription keys, stored exactly as sent (marketing, weeklyNewsletter). Replaces the profile’s list, unless addSubscriptions is true.
addSubscriptions boolean true adds subscriptions to the profile’s list instead of replacing it.
removeSubscriptions array of strings Keys to remove from the profile’s list. Combine with addSubscriptions: true to change part of the list and leave the rest alone.
unsubscribeLink string An absolute URL: this customer’s own unsubscribe page in your shop. Used when Subscription Management is External, and takes precedence over the unsubscribe link configured in your shop settings.
tags array of strings Added to the profile’s tags. Existing tags are kept.
userId string The Releva profile id to write to. Leave it out to let Releva find the profile by email address or phone number.
rejectAlreadySubscribed boolean true answers 409 and writes nothing when this email address has ever been subscribed or unsubscribed in your shop. Checks email only. Use it for “subscribe and get a discount” offers meant for new subscribers.
attributions object Links the change to a message: emailId, campaignId, textMessageId, viberMessageId, whatsappMessageId, all strings.
locale string A two-letter ISO 639-1 code such as en. Checked, but not used by this endpoint.

Fields not in this table are ignored.

Default subscriptions. If the call leaves the customer with none of your shop’s user-visible subscriptions, Releva adds all of them. It does not do this when the call removes subscriptions (removeSubscriptions), or when the customer was already subscribed and the call names subscriptions. With the default list, a call without subscriptions stores ["marketing"]. See User-visible subscriptions.

curl -X POST 'https://releva.ai/api/v0/subscribe' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{
"email": "maria@example.com",
"firstName": "Maria",
"lastName": "Example",
"subscriptions": ["marketing", "weeklyNewsletter"],
"unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-1001",
"tags": ["checkout-opt-in"]
}'

To add one subscription and remove another without touching the rest:

curl -X POST 'https://releva.ai/api/v0/subscribe' \
-H "authorization: Bearer $RELEVA_SECRET_KEY" \
-H 'content-type: application/json' \
-d '{
"email": "maria@example.com",
"subscriptions": ["weeklyNewsletter"],
"addSubscriptions": true,
"removeSubscriptions": ["dailyDeals"]
}'

200 with the profile id:

{ "userId": "DEMO-1001" }

The profile has been written when the response arrives. Releva records a subscribe event when the profile becomes subscribed, and a subscriptionsChanged event when its list changes.

Errors have the shape { "message": "..." }, except the 409. When several fields fail, the messages are joined with a space in one response.

Status When Body or message
400 Authentication failed See Authentication
400 "email": "not-an-email" The 'email' field must be a valid e-mail.
400 "phoneNumber": "12ab" phoneNumber must be a valid telephone number starting with + and international code, e.g. +1. Got 12ab instead.
400 "subscriptions": "marketing" (a string, not an array) The 'subscriptions' field must be an array.
400 "addSubscriptions": "yes" The 'addSubscriptions' field must be a boolean.
400 "unsubscribeLink": "/unsubscribe" (not absolute) The 'unsubscribeLink' field must be a valid URL.
400 "locale": "english" locale must be a valid ISO-639-1 code! Got english instead.
400 "birthday": "21/05/1990" Starts with birthday must be a valid ISO-8601 date such as 2020-01-01. The message also mentions times, but only YYYY-MM-DD is accepted.
400 "attributions": {"campaignId": 42} The 'attributions.campaignId' field must be a string.
402 The shop is switched off See Authentication
409 rejectAlreadySubscribed: true and the email address has a consent history { "code": "alreadySubscribed" }
413 The body is larger than 800 KB request entity too large
  • HTTPS only. A plain HTTP request answers 400 with We do not support non-HTTPS requests.
  • Body size: 800 KB.
  • Rate limits: none on this endpoint.
  • One customer per request.