Unsubscribe a customer with the API
POST https://releva.ai/api/v0/unsubscribe opts one customer out of marketing messages in your shop. It records the opt-out and removes the subscriptions the customer could see.
When to use it
Section titled “When to use it”- Your shop manages consent (External mode). When a customer lands on your unsubscribe page, mark them unsubscribed in your shop and call this endpoint. See External mode.
- A customer opts out somewhere else in your system, for example in their account settings or through your support team. Call it so Releva stops sending too.
You do not need it for links that Releva renders in Internal mode: those unsubscribe the customer themselves (see Unsubscribe links and one-click unsubscribe). To remove a single subscription without opting the customer out, use Subscribe a customer from your server with removeSubscriptions.
Never call it from a browser or an app. It needs your secret key.
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/unsubscribe with content-type: application/json. Send email, phoneNumber or both.
| Field | Type | Required | Notes |
|---|---|---|---|
email |
string | One of email, phoneNumber |
The customer’s email address. |
phoneNumber |
string | One of email, phoneNumber |
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. |
attributions |
object | No | Links the opt-out to a message: emailId, campaignId, textMessageId, viberMessageId, whatsappMessageId, all strings. When campaignId is one of your shop’s campaigns, the unsubscribe event is tagged with that campaign’s mode, for example triggered. |
No other field is allowed: an unknown field answers 400.
By email address:
curl -X POST 'https://releva.ai/api/v0/unsubscribe' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "email": "maria@example.com" }'By phone number:
curl -X POST 'https://releva.ai/api/v0/unsubscribe' \ -H "authorization: Bearer $RELEVA_SECRET_KEY" \ -H 'content-type: application/json' \ -d '{ "phoneNumber": "+15555550199" }'When you send both, Releva opts out the profile it finds by the email address and the profile it finds by the phone number.
Response
Section titled “Response”202 with the body {}. The profile has been written when the response arrives.
What changed on the profile:
- The customer is unsubscribed. Opt-in Marketing and Opt-out Marketing campaigns on email, SMS, Viber, WhatsApp and webhooks stop reaching them; Transactional campaigns still do.
- Your shop’s user-visible subscriptions are removed from the profile. Subscriptions that you set only through the API and never made visible stay. The
marketingsubscription is always removed, even if your shop does not show it. - An
unsubscribeevent is recorded. - An email address or phone number that Releva does not know creates a new, unsubscribed profile. A later import or subscribe of that address starts from an opt-out.
External mode
Section titled “External mode”When Subscription Management in Settings › Messaging is External, your shop owns consent and Releva links to your unsubscribe page instead of its own:
- The customer’s own link, if your integration sent an absolute
unsubscribeLinkfor them (throughPOST /api/v0/subscribeorPOST /api/v0/profiles). Releva uses it as it is. - Otherwise the Email Unsubscribe URL from Settings › Messaging, with
encodedEmail(the email address, base64-encoded),encodedPhoneNumber(the phone number, base64-encoded, when the profile has one) andurl(your shop’s URL) added as query parameters.
Your page must:
- Read the customer from the link: decode
encodedEmailorencodedPhoneNumberfrom base64, or use your own per-customer link. - Mark the customer unsubscribed in your shop.
- Call
POST /api/v0/unsubscribewith the email address or phone number.
If you leave Email Unsubscribe URL empty, profiles without their own link are skipped by Opt-in Marketing and Opt-out Marketing campaigns, because their messages could not carry a link that identifies them. Transactional campaigns still reach them, with your shop’s URL as the link. Shops connected to Klaviyo are not affected, because Klaviyo adds its own unsubscribe link.
Errors
Section titled “Errors”Errors have the shape { "message": "..." }. When several fields fail, the messages are joined with a space.
| Status | When | Message |
|---|---|---|
400 |
Authentication failed | See Authentication |
400 |
{} (neither email nor phoneNumber) |
At least one of (email, phoneNumber) is required. |
400 |
An extra field, for example subscriptions |
The object '' contains forbidden keys: 'subscriptions'. |
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. |
402 |
The shop is switched off | See Authentication |
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.