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).
When to use it
Section titled “When to use it”- 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.
The two behaviours
Section titled “The two behaviours”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.
Authentication
Section titled “Authentication”Send your shop’s access token as a bearer token:
authorization: Bearer $RELEVA_ACCESS_TOKENFind 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.
Request
Section titled “Request”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" }'Response
Section titled “Response”| 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. |
The JavaScript SDK
Section titled “The JavaScript SDK”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
Section titled “Errors”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 |
Limits
Section titled “Limits”- HTTPS only. Body size: 800 KB.
- Rate limit: 30 requests per 15 minutes per IP address, counting only requests that send
rejectAlreadySubscribed: trueand get an error answer (such as the409). Other requests are not limited. Responses carry the standardRateLimitandRateLimit-Policyheaders. - One customer per request.