# Subscribe a customer from your server

> POST /api/v0/subscribe with your secret key subscribes a customer to marketing messages right away and replaces, adds or removes their subscriptions. Fields, curl, response, errors and limits.

`POST https://releva.ai/api/v0/subscribe` subscribes one customer to marketing messages and sets their subscriptions. It creates the profile when Releva does not know the email address or phone number yet.

## When to use it

If you send information about non-subscribed users to Releva, call it from your server once such a user subscribes. When a user updates their subscription preferences, call it with the new set of subscriptions. It always subscribes right away: the **Subscription Request Behavaior** setting does not apply to it.

**Never call it from a browser or an app.** It needs your secret key. To subscribe from a sign-up form on your site, use [Subscribe a customer from the browser](https://releva.ai/documentation/reference/consent/subscribe-from-the-browser/) instead.

## Authentication

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

```plaintext
authorization: Bearer $RELEVA_SECRET_KEY
```

Find it under **Settings › Shop & Integration**; see [Find your Access Token and Secret Key](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

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

`POST /api/v0/subscribe` with `content-type: application/json`. Every field is optional. Send `email`, `phoneNumber` or both: the endpoint does not reject a body that has neither, so check it on your side.

| Field                     | Type             | Notes                                                                                                                                                                                                                   |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                   | string           | The customer’s email address.                                                                                                                                                                                           |
| `phoneNumber`             | string           | 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.                                            |
| `firstName`               | string           | Stored on the profile.                                                                                                                                                                                                  |
| `lastName`                | string           | Stored on the profile.                                                                                                                                                                                                  |
| `birthday`                | string           | Date only, exactly `YYYY-MM-DD`, for example `1990-05-21`.                                                                                                                                                              |
| `subscriptions`           | array of strings | Subscription keys, stored exactly as sent (`marketing`, `weeklyNewsletter`). Replaces the profile’s list, unless `addSubscriptions` is `true`.                                                                          |
| `addSubscriptions`        | boolean          | `true` adds `subscriptions` to the profile’s list instead of replacing it.                                                                                                                                              |
| `removeSubscriptions`     | array of strings | Keys to remove from the profile’s list. Combine with `addSubscriptions: true` to change part of the list and leave the rest alone.                                                                                      |
| `unsubscribeLink`         | string           | An absolute URL: this customer’s own unsubscribe page in your shop. Used when **Subscription Management** is **External**, and takes precedence over the unsubscribe link configured in your shop settings.             |
| `tags`                    | array of strings | Added to the profile’s tags. Existing tags are kept.                                                                                                                                                                    |
| `userId`                  | string           | The Releva profile id to write to. Leave it out to let Releva find the profile by email address or phone number.                                                                                                        |
| `rejectAlreadySubscribed` | boolean          | `true` answers `409` and writes nothing when this email address has ever been subscribed or unsubscribed in your shop. Checks `email` only. Use it for “subscribe and get a discount” offers meant for new subscribers. |
| `attributions`            | object           | Links the change to a message: `emailId`, `campaignId`, `textMessageId`, `viberMessageId`, `whatsappMessageId`, all strings.                                                                                            |
| `locale`                  | string           | A two-letter ISO 639-1 code such as `en`. Checked, but not used by this endpoint.                                                                                                                                       |

Fields not in this table are ignored.

**Default subscriptions.** If the call leaves the customer with none of your shop’s user-visible subscriptions, Releva adds all of them. It does not do this when the call removes subscriptions (`removeSubscriptions`), or when the customer was already subscribed and the call names subscriptions. With the default list, a call without `subscriptions` stores `["marketing"]`. See [User-visible subscriptions](https://releva.ai/documentation/learn/consent/how-consent-works-in-releva/#user-visible-subscriptions).

```plaintext
curl -X POST 'https://releva.ai/api/v0/subscribe' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "email": "maria@example.com",
    "firstName": "Maria",
    "lastName": "Example",
    "subscriptions": ["marketing", "weeklyNewsletter"],
    "unsubscribeLink": "https://demo-store.example.com/unsubscribe/DEMO-1001",
    "tags": ["checkout-opt-in"]
  }'
```

To add one subscription and remove another without touching the rest:

```plaintext
curl -X POST 'https://releva.ai/api/v0/subscribe' \
  -H "authorization: Bearer $RELEVA_SECRET_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "email": "maria@example.com",
    "subscriptions": ["weeklyNewsletter"],
    "addSubscriptions": true,
    "removeSubscriptions": ["dailyDeals"]
  }'
```

## Response

`200` with the profile id:

```plaintext
{ "userId": "DEMO-1001" }
```

The profile has been written when the response arrives. Releva records a `subscribe` event when the profile becomes subscribed, and a `subscriptionsChanged` event when its list changes.

## Errors

Errors have the shape `{ "message": "..." }`, except the `409`. When several fields fail, the messages are joined with a space in one response.

| Status | When                                                                        | Body or message                                                                                                                              |
| ------ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Authentication failed                                                       | See [Authentication](https://releva.ai/documentation/reference/consent/subscribe-a-customer/#authentication)                                                                                                        |
| `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.`                            |
| `400`  | `"subscriptions": "marketing"` (a string, not an array)                     | `The 'subscriptions' field must be an array.`                                                                                                |
| `400`  | `"addSubscriptions": "yes"`                                                 | `The 'addSubscriptions' field must be a boolean.`                                                                                            |
| `400`  | `"unsubscribeLink": "/unsubscribe"` (not absolute)                          | `The 'unsubscribeLink' field must be a valid URL.`                                                                                           |
| `400`  | `"locale": "english"`                                                       | `locale must be a valid ISO-639-1 code! Got english instead.`                                                                                |
| `400`  | `"birthday": "21/05/1990"`                                                  | Starts with `birthday must be a valid ISO-8601 date such as 2020-01-01`. The message also mentions times, but only `YYYY-MM-DD` is accepted. |
| `400`  | `"attributions": {"campaignId": 42}`                                        | `The 'attributions.campaignId' field must be a string.`                                                                                      |
| `402`  | The shop is switched off                                                    | See [Authentication](https://releva.ai/documentation/reference/consent/subscribe-a-customer/#authentication)                                                                                                        |
| `409`  | `rejectAlreadySubscribed: true` and the email address has a consent history | `{ "code": "alreadySubscribed" }`                                                                                                            |
| `413`  | The body is larger than 800 KB                                              | `request entity too large`                                                                                                                   |

## Limits

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

## Next steps

* [Choose a consent call](https://releva.ai/documentation/reference/consent/choose-a-consent-call/): Check that a server-side subscribe is the right call for your case.
* [Unsubscribe a customer with the API](https://releva.ai/documentation/reference/consent/unsubscribe-a-customer/): Send the opt-out from your server when a customer unsubscribes in your system.
* [Check a customer’s subscription status](https://releva.ai/documentation/guides/consent/check-a-customers-subscription-status/): Open the profile and confirm the call did what you expected.