Skip to content

Area: Developers

POST

Subscribe from the browser (double opt-in aware)

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

Browser-safe subscribe, authenticated with your access token; the Releva SDK’s requestSubscribe calls it. With Subscription Request Behavior “Subscribe right away” it subscribes like POST /subscribe (event tagged request) and returns 200 with the profile id; an existing profile with the same email or phone number wins over the userId you send. With “Wait for confirmation” it stores the contact details, records a subscribeRequest event and returns 202 {}; the shopper is subscribed when they open the {{subscribeLink}} from your confirmation email. Failed requests with rejectAlreadySubscribed are limited to 30 per 15 minutes per IP.

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",
"subscriptions": [
"marketing"
],
"tags": [
"footer-form"
]
}

Subscribed right away.

Media typeapplication/json
object
userId

The profile id. Absent when no identifier was sent.

string

Example

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

Accepted for asynchronous processing.

Media typeapplication/json
object
0

Example

{}

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, and accessToken url parameters is also missing. At least one of them is required."
}

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"
}

Too many rejected requests from this IP.