Skip to content

Area: Developers

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.

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.

  1. In the admin, open Settings › Messaging and the General tab.
  2. Under Subscription Management, select External.
  3. Enter your endpoint’s URL in Subscriber Sync API.
  4. Select Save.

The Subscriber Sync API field appears only in External mode.

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/sync from 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).

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 for page=2, page=3 and so on, and stops after page reaches pageCount.
  • With nextCursor, Releva sends it back as &cursor=<value> and stops when nextCursor is null or empty.

Return pageCount or nextCursor in every response. Without either one, Releva does not stop paging.

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.

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.

  • 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.