Skip to content

Area: Developers

POST

Subscribe a profile or update its subscriptions

Path
/subscribe
Auth
Secret key · server only
POST
/subscribe
curl --request POST \
--url https://releva.ai/api/v0/subscribe \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "email": "maria@example.com", "firstName": "Maria", "lastName": "Example", "subscriptions": [ "marketing" ], "tags": [ "footer-form" ] }'

Marks the profile as subscribed and updates its subscriptions, creating the profile if the email or phone number is unknown. Call it from your server only: it uses your secret key. subscriptions replaces the profile’s list unless addSubscriptions is true; removeSubscriptions removes entries. If the profile ends up with none of your shop’s user-visible subscriptions and was not subscribed before (or the request names none), all user-visible subscriptions are added. tags are added to the profile’s tags. Unknown fields are ignored. The profile is written before the response is sent; the resulting subscribe or subscriptionsChanged event is recorded asynchronously.

Media typeapplication/json

Send at least one of email or phoneNumber. Unknown fields are ignored.

object
email
string format: email
phoneNumber
string
>= 2 characters <= 32 characters /^\+\d+$/
firstName
string
lastName
string
birthday

YYYY-MM-DD exactly.

string format: date
subscriptions

Replaces the profile’s subscriptions, or is added to them when addSubscriptions is true.

Array<string>
addSubscriptions

Add subscriptions to the current list instead of replacing it.

boolean
removeSubscriptions

Subscriptions to remove (also removes the label form of a user-visible subscription).

Array<string>
unsubscribeLink

Absolute URL; per-profile unsubscribe link used when subscription management is External.

string format: uri
locale

ISO 639-1 code. Used by /subscribe/request in Wait for confirmation mode.

string
userId

Releva profile id (the rlv_u cookie on the frontend).

string
tags

Added to the profile’s tags.

Array<string>
rejectAlreadySubscribed

Answer 409 instead of subscribing when the email has been subscribed or unsubscribed before.

boolean
attributions

Links the event to the message or campaign that caused it. All values are ids as strings.

object
emailId
string
campaignId
string
textMessageId
string
viberMessageId
string
whatsappMessageId
string

Example

{
"email": "maria@example.com",
"firstName": "Maria",
"lastName": "Example",
"subscriptions": [
"marketing"
],
"tags": [
"footer-form"
]
}

Subscribed. userId is the profile id. If neither email nor phoneNumber is sent, nothing is written and the body is {}.

Media typeapplication/json
object
userId

The profile id. Absent when no identifier was sent.

string

Example

{
"userId": "DEMO-CUST-1001"
}

Authentication or validation error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "Authorization header is missing."
}

The domain is disabled.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "Domain is disabled. Please reach out to support@releva.ai to enable it."
}

rejectAlreadySubscribed was set and the email has been subscribed or unsubscribed before. Nothing was written.

Media typeapplication/json
object
code
required
string
Allowed value: alreadySubscribed

Example

{
"code": "alreadySubscribed"
}

Request body larger than 800 KB.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "request entity too large"
}