Skip to content

Area: Developers

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.

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

Send your shop’s secret key as a bearer token:

authorization: Bearer $RELEVA_SECRET_KEY

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

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.

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 marketing subscription is always removed, even if your shop does not show it.
  • An unsubscribe event 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.

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 unsubscribeLink for them (through POST /api/v0/subscribe or POST /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) and url (your shop’s URL) added as query parameters.

Your page must:

  1. Read the customer from the link: decode encodedEmail or encodedPhoneNumber from base64, or use your own per-customer link.
  2. Mark the customer unsubscribed in your shop.
  3. Call POST /api/v0/unsubscribe with 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 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
  • HTTPS only. A plain HTTP request answers 400 with We do not support non-HTTPS requests.
  • Body size: 800 KB.
  • Rate limits: none on this endpoint.
  • One customer per request.