Build the subscriber sync endpoint
With a subscriber sync, Releva pulls your subscriber list from an endpoint on your shop and updates its profiles from it. You build the endpoint; Releva calls it when you start a sync.
When to use it
Section titled “When to use it”Build it when your shop collects marketing consent into a database you own and Releva should follow it, or when you do not have a single unsubscribe page for all users and each subscriber gets a unique unsubscribe link. That is the External way of managing subscriptions. In other cases, or for a one-off load, prepare a CSV file with your subscribers and import it instead (see Import profiles from a CSV file). To push changes as they happen, use Create or update profiles.
Before you start
Section titled “Before you start”- In the admin, open Settings › Messaging and the General tab.
- Under Subscription Management, select External.
- Enter your endpoint’s URL in Subscriber Sync API.
- Select Save.
The Subscriber Sync API field appears only in External mode.
Start a sync
Section titled “Start a sync”A sync runs only when you start it. There is no schedule. Start it either way:
- Select Sync Now next to Subscriber Sync API in the admin.
- Call
POST https://releva.ai/api/v0/subscribers/syncfrom your server. No body.
curl -X POST 'https://releva.ai/api/v0/subscribers/sync' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json'The call answers 202 Accepted with the body {} and the pull runs in the background. A call while a sync is already queued adds nothing. If the shop has no Subscriber Sync API URL, the call still answers 202 and nothing is pulled. Only the authentication errors apply: 400 for a missing, malformed or unknown key and 402 for a disabled shop (the messages are in Create or update profiles).
Request Releva sends
Section titled “Request Releva sends”Releva calls your URL with GET and these headers. It may also add HTTP message signature headers (Signature-Agent, Signature-Input, Signature), which you can ignore.
| Header | Value |
|---|---|
content-type |
application/json |
authorization |
Bearer <your Secret Key> |
x-rlv-authorization |
The same value again, for servers that drop authorization |
Check the key before you answer: only Releva and you know it.
The first request is GET <your URL>?page=1. What comes next depends on your response:
- With
pageCount, Releva asks forpage=2,page=3and so on, and stops afterpagereachespageCount. - With
nextCursor, Releva sends it back as&cursor=<value>and stops whennextCursorisnullor empty.
Return pageCount or nextCursor in every response. Without either one, Releva does not stop paging.
Response your endpoint returns
Section titled “Response your endpoint returns”Status 200 with JSON:
{ "subscribers": [ { "email": "maria@example.com", "subscribedAt": "2026-01-15T10:05:00Z", "subscriptions": ["marketing"], "unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-1001" }, { "phoneNumber": "+15555550199", "subscribedAt": null } ], "pageCount": 3}| Field | Type | Notes |
|---|---|---|
subscribers |
array | Required in every response, empty when there are none. |
pageCount |
number | Page-based paging: the number of pages. |
nextCursor |
string or null |
Cursor-based paging: the cursor of the next page, null on the last page. |
Each subscriber updates the profile with the same email or phone number, or creates one:
| Field | Type | Notes |
|---|---|---|
email |
string | Identifies the person. Send email or phoneNumber. |
phoneNumber |
string | International form, + and digits. It is not converted. |
firstName, lastName |
string | |
subscribedAt |
string or null |
See the next section. Use ISO-8601 with seconds and an offset, for example 2026-01-15T10:05:00Z. |
subscriptions |
array of strings | Replaces the profile’s subscription list. |
unsubscribeLink |
string | Your unsubscribe page for this person. Send it only for a subscribed person. If you leave it out, Releva uses the Email Unsubscribe URL from Settings › Messaging. If that setting is empty, a subscriber without their own link receives no marketing emails (see External mode). |
consent |
string | legitimateInterest, privacyPolicy, mandatoryCookies or cookiesPolicy. A stored consent is never lowered. |
The values are not validated as strictly as in the profile API, so keep to these fields and types.
subscribedAt
Section titled “subscribedAt”The date and time when this subscriber gave their consent, or null if they are not subscribed.
This applies to the sync response only. In Create or update profiles, do not send null; call Unsubscribe a customer.
Limits
Section titled “Limits”- Page size: return 20 to 50 subscribers per page. Releva does not enforce a limit, but small pages keep each request fast.
- Rate limits: none on
POST /api/v0/subscribers/sync.