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.
When to use it
Section titled “When to use it”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.
Authentication
Section titled “Authentication”Send your shop’s secret key as a bearer token:
authorization: Bearer $RELEVA_SECRET_KEYFind 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.
Request
Section titled “Request”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"] }'Response
Section titled “Response”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
Section titled “Errors”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 |
Limits
Section titled “Limits”- HTTPS only. A plain HTTP request answers
400withWe do not support non-HTTPS requests. - Body size: 800 KB.
- Rate limits: none on this endpoint.
- One customer per request.