Skip to content

Area: Developers

Subscribe a customer from the browser

POST https://releva.ai/api/v0/subscribe/request sends a sign-up from your storefront. It uses the access token, which is safe to expose in a browser or an app. What it does depends on Subscription Request Behavaior in Settings › Messaging: it either subscribes the customer right away, or records a request that the customer confirms by email (double opt-in).

  • You use the Releva JavaScript SDK: call Releva.requestSubscribe(...). It calls this endpoint for you (see The JavaScript SDK).
  • You build your own sign-up form and post from the browser without the SDK: call this endpoint.
  • You subscribe customers from your server: use Subscribe a customer from your server instead. It always subscribes right away.

Never send your secret key from a browser. This endpoint takes the access token only.

Subscription Request Behavaior (the label is spelled this way in the admin) is shown in Settings › Messaging when Subscription Management is Internal.

Setting What a request does Success response
Subscribe right away Subscribes the customer like the server-side call, and tags the subscribe event with request. If the email address or phone number already belongs to a profile, that profile is used, and the userId you sent is merged into it. 200 with { "userId": "..." }
Wait for confirmation Does not subscribe. Stores the email address, phone number, birthday and tags on the profile (an unsubscribeLink is kept only if the profile is already subscribed), and records a subscribeRequest event with the requested subscriptions and the locale. The customer is subscribed when they open the {{subscribeLink}} in a confirmation email. 202 with {}

Your access token is public, so with Subscribe right away anyone who copies it can subscribe any address. Wait for confirmation prevents that. To set it up end to end, read Set up double opt-in.

If you use Subscribe right away, limit the damage of a wrong sign-up: create a triggered campaign on subscribe events with the tag request, and send an email that welcomes the user and offers a link to unsubscribe in case they were subscribed in error.

If you are unsure which behaviour is right for you, email support@releva.ai.

With Subscribe right away, call this endpoint with the new set of subscriptions when a user updates their preferences. With Wait for confirmation, the call only records a request: subscriptions, addSubscriptions and removeSubscriptions do not change the profile until the customer confirms.

Send your shop’s access token as a bearer token:

authorization: Bearer $RELEVA_ACCESS_TOKEN

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, and accessToken url parameters is also missing. At least one of them is required.
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 The access token you provided is invalid.
No shop has this access token (also when you send the secret key here) Domain with the provided access token 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/request with content-type: application/json. Send at least one of email, phoneNumber or userId.

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.
userId string The visitor’s Releva id (the rlv_u cookie). The SDK sends it for you.
firstName string The customer’s first name.
lastName string The customer’s last name.
birthday string Date only, exactly YYYY-MM-DD.
subscriptions array of strings Subscription keys, stored exactly as sent. With Wait for confirmation they are applied when the customer confirms. Without them, your user-visible subscriptions apply (see Subscribe a customer from your server).
addSubscriptions boolean true adds subscriptions to the profile’s list instead of replacing it. With Wait for confirmation, the confirmation always adds.
removeSubscriptions array of strings Keys to remove from the profile’s list (Subscribe right away only).
tags array of strings Added to the profile’s tags, for example the form the sign-up came from.
unsubscribeLink string An absolute URL: this customer’s own unsubscribe page in your shop. Used only when Subscription Management is External; there it takes precedence over your shop’s Email Unsubscribe URL. Kept only while the profile is subscribed.
rejectAlreadySubscribed boolean true answers 409 and does nothing when this email address has ever been subscribed or unsubscribed in your shop. Checks email only. Rejected requests count toward a rate limit (see Limits).
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. With Wait for confirmation it is recorded on the subscribeRequest event; without it, your shop’s locale is recorded.

Fields not in this table are ignored.

curl -X POST 'https://releva.ai/api/v0/subscribe/request' \
-H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
-H 'content-type: application/json' \
-d '{
"email": "maria@example.com",
"subscriptions": ["weeklyNewsletter"],
"addSubscriptions": true,
"tags": ["footer-form"],
"locale": "en"
}'
Status Body Meaning
200 { "userId": "DEMO-1001" } Subscribe right away: the customer is subscribed. If you track visitors yourself, store this id as the visitor’s id: it can differ from the userId you sent when the email address or phone number belonged to an existing profile.
202 {} Wait for confirmation: the request is recorded. The customer is not subscribed until they open the confirmation link.
409 { "code": "alreadySubscribed" } rejectAlreadySubscribed was true and the email address has a consent history. Nothing was written.

Releva.requestSubscribe posts to this endpoint with the access token and the visitor’s rlv_u id. Call Releva.push() on the page first: the access token and the locale come from the last push.

Releva.requestSubscribe(
'maria@example.com', // email
'Maria', // firstName
'Example', // lastName
null, // phoneNumber
{}, // custom (ignored by this endpoint)
['weeklyNewsletter'], // subscriptions
function (response) { /* any 2xx: 200 or 202 */ },
function (error) { /* error.status and error.body, for example 409 */ },
false, // addSubscriptions
null, // birthday
null, // attributions
['footer-form'], // tags
{ rejectAlreadySubscribed: true } // options
);

The SDK leaves out an empty subscriptions array, so a form without subscription choices never clears a returning customer’s list. When the response carries a userId, the SDK stores it in the rlv_u cookie. The full signature is in the JavaScript SDK reference.

Errors have the shape { "message": "..." }, except the 409.

Status When Body or message
400 Authentication failed See Authentication
400 None of email, phoneNumber or userId At least one of (email, phoneNumber, userId) is required.
400 A field has the wrong type or format The same messages as Subscribe a customer from your server, for example The 'email' field must be a valid e-mail.
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
429 Too many failed requests with rejectAlreadySubscribed: true from one IP address
  • HTTPS only. Body size: 800 KB.
  • Rate limit: 30 requests per 15 minutes per IP address, counting only requests that send rejectAlreadySubscribed: true and get an error answer (such as the 409). Other requests are not limited. Responses carry the standard RateLimit and RateLimit-Policy headers.
  • One customer per request.
  • Customer dataSet up double opt-in

    Make sign-ups wait for an email confirmation, so a copied access token cannot subscribe strangers.

  • Customer dataCheck an email's consent history

    Find out before you show a new-subscriber offer whether an address has subscribed before.

  • Customer dataChoose a consent call

    Compare this call with the server-side subscribe and the profile button.