# Inbox API overview

> The six endpoints a mobile app uses to read a shopper's App Inbox: authentication with the access token, the userId rule, pagination, read and delete semantics, errors and limits, with a working request for each.

The Inbox API is the read side of **App Inbox**, the persistent in-app message centre of your Android or iOS app. It lists a shopper’s messages, counts the unread ones, marks them read, deletes them and reports taps. There is no public endpoint to create an inbox message: messages are created in the admin as the **App Inbox** channel of a push notification and delivered by campaigns and workflows. Read [How the App Inbox works](https://releva.ai/documentation/learn/inbox/how-the-app-inbox-works/) for that side.

| Endpoint                                  | Purpose                                                       |
| ----------------------------------------- | ------------------------------------------------------------- |
| `GET /inbox/messages`                     | List the shopper’s messages, newest first, one page at a time |
| `GET /inbox/unread-count`                 | Count the shopper’s unread messages                           |
| `POST /inbox/messages/{messageId}/read`   | Mark one message as read                                      |
| `POST /inbox/messages/read-all`           | Mark every message as read                                    |
| `DELETE /inbox/messages/{messageId}`      | Delete one message                                            |
| `POST /inbox/messages/{messageId}/action` | Report that the shopper tapped a link or button in a message  |

Base URL: `https://releva.ai/api/v0`.

## When to use it

* **Releva React Native or Swift SDK**: you do not call these endpoints. `client.initializeInbox()` and the `InboxService` methods call them for you, cache the state on the device and refresh it when a new message arrives. See [Using the SDKs](https://releva.ai/documentation/learn/inbox/how-the-app-inbox-works/#using-the-sdks).
* **Another app stack** (Flutter, Kotlin, a custom native app): call the endpoints directly from the app. You render the message body yourself; it is Unlayer design JSON.
* The web SDK (`releva-sdk-js`) has no inbox support. A web page can call the API (CORS allows any origin), but App Inbox is designed for mobile apps.

## Authentication

Every endpoint uses the shop’s **access token**, the public key your website and apps already use, not the secret key. Find both under **Settings › Shop & Integration**; see [Find your API keys](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/).

```plaintext
authorization: Bearer $RELEVA_ACCESS_TOKEN
```

Authentication failures answer **`400`**, not `401`:

| Problem                                                      | Message                                                                                                              |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| No `authorization` header                                    | `Authorization header is missing, and accessToken url parameters is also missing. At least one of them is required.` |
| Header is not `Bearer <token>`                               | ``Authorization header is malformed. It should look like `Bearer <string>`.``                                        |
| Token is not a UUID                                          | `The access token you provided is invalid.`                                                                          |
| No shop has this token (including the secret key by mistake) | `Domain with the provided access token cannot be found.`                                                             |

A shop that has been switched off answers `402` with `Domain is disabled. Please reach out to support@releva.ai to enable it.`

> **Caution**
>
> The access token ships inside your app and is not secret. The only other thing an inbox call needs is the shopper’s `userId`. Anyone who knows both can read and change that shopper’s inbox. Use profile ids that cannot be guessed, and do not put sensitive data in inbox messages.

## The `userId`

Every call names the shopper with `userId`: the profile id your app registered with `setProfileId` (the same value you send as `profileId` in `POST /appPush/tokens`). It is a string of 1 to 96 characters.

* On the two `GET` endpoints it goes in the **query string**.
* On `POST` and `DELETE` it goes in the **JSON body**, also on the `DELETE`.

Without it, or with more than 96 characters, the call answers `400 {"message":"A valid userId is required."}`. A `userId` that has no messages is not an error: the list is empty and the count is `0`.

## Request format

* HTTPS only. Plain HTTP answers `400 {"message":"We do not support non-HTTPS requests."}`.
* Send JSON with `content-type: application/json` on `POST` and `DELETE`. With another content type the body is not parsed and you get `400 {"message":"A valid userId is required."}`.
* Bodies are limited to 800 KB (far more than these calls need).
* Unknown body fields are ignored.

## Responses

| Status | When                                                                                                                                       |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `200`  | List and count: the body is the data                                                                                                       |
| `202`  | Read, read-all and action: accepted, body `{}`. The database change is done; only the analytics event is written asynchronously            |
| `204`  | Delete: done, no body                                                                                                                      |
| `400`  | Authentication failed, or `userId` missing or too long                                                                                     |
| `402`  | The shop is disabled                                                                                                                       |
| `404`  | `{"message":"Message not found."}`: no message with this id for this `userId` in this shop. Another shopper’s message id answers `404` too |
| `500`  | `{"message":"An internal error occurred."}`. See the caution below                                                                         |

> **Caution**
>
> Malformed input currently answers `500` instead of `400`: a `messageId` that is not a UUID, a `userId` that is not a JSON string (for example `1001`), a `userId` sent only in the query string of a `POST` or `DELETE`, and a negative `limit`. Validate on your side; do not retry these.

## Limits

* Page size: default 20, maximum 50. Larger values are capped at 50.
* `userId`: 1 to 96 characters.
* No rate limit on these endpoints. The SDKs refresh at most once per app foreground when the cache is older than 5 minutes; do something similar.
* Deleted messages cannot be restored. Expired messages are hidden, not deleted.

## Message object

```plaintext
{
  "id": "fe9db61a-b2ef-491e-bae7-e96735072932",
  "title": "Summer sale starts today",
  "design": { "body": { "id": "demo", "rows": [], "values": {} }, "counters": {}, "schemaVersion": 16 },
  "read": false,
  "createdAt": "2026-10-21T19:18:20.804Z",
  "inboxMessageId": 2
}
```

| Field            | Type             | Meaning                                                                                                                                                     |
| ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`             | UUID             | The shopper’s copy of the message. Use it in the read, delete and action calls                                                                              |
| `title`          | string           | Title, personalised for this shopper when the message was sent                                                                                              |
| `design`         | object or `null` | Message body as Unlayer design JSON, personalised when sent. The SDKs render it with `InboxMessageWidget` / `InboxMessageView`                              |
| `read`           | boolean          | Whether the shopper has read it                                                                                                                             |
| `createdAt`      | ISO 8601         | When it was delivered                                                                                                                                       |
| `inboxMessageId` | integer          | The message template in the admin. The same for every shopper who got this message; a push notification that opens the inbox carries it as `inboxMessageId` |

## Endpoints

### List messages

`GET /api/v0/inbox/messages?userId=…&limit=…&cursor=…`

Returns the shopper’s active, unexpired messages, newest first. `limit` is optional (default 20, maximum 50; `0` or a non-number means 20). `cursor` is optional: pass the `nextCursor` of the previous page to get the next one. Treat it as opaque; an unreadable cursor is ignored and the first page comes back.

```plaintext
curl 'https://releva.ai/api/v0/inbox/messages?userId=DEMO-CUSTOMER-1001&limit=20' \
  -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json'
```

Response `200`:

```plaintext
{
  "messages": [
    {
      "id": "fe9db61a-b2ef-491e-bae7-e96735072932",
      "title": "Summer sale starts today",
      "design": { "body": { "id": "demo", "rows": [], "values": {} }, "counters": {}, "schemaVersion": 16 },
      "read": false,
      "createdAt": "2026-10-21T19:18:20.804Z",
      "inboxMessageId": 2
    },
    {
      "id": "0c5262f6-9791-4acd-9791-fcb6c10b6bad",
      "title": "Welcome to Demo Store",
      "design": { "body": { "id": "demo", "rows": [], "values": {} }, "counters": {}, "schemaVersion": 16 },
      "read": false,
      "createdAt": "2026-10-21T19:18:20.685Z",
      "inboxMessageId": 1
    }
  ],
  "nextCursor": null
}
```

`nextCursor` is `null` on the last page. With `limit=1` the first call returns the newest message and a cursor; the second call with `cursor=<that value>` returns the older one and `null`. The `design` objects are shortened here; a real response carries the full Unlayer design.

To page through everything:

1. Call without `cursor`.
2. While `nextCursor` is not `null`, call again with `cursor=<nextCursor>`.

Do not rely on two messages with exactly the same `createdAt` landing on different pages correctly; the cursor compares timestamps only.

### Count unread messages

`GET /api/v0/inbox/unread-count?userId=…`

```plaintext
curl 'https://releva.ai/api/v0/inbox/unread-count?userId=DEMO-CUSTOMER-1001' \
  -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json'
```

Response `200`: `{ "count": 2 }`. Counts active, unexpired, unread messages, so it is the badge number for your inbox icon.

### Mark a message as read

`POST /api/v0/inbox/messages/{messageId}/read`

```plaintext
curl -X POST 'https://releva.ai/api/v0/inbox/messages/fe9db61a-b2ef-491e-bae7-e96735072932/read' \
  -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"userId":"DEMO-CUSTOMER-1001"}'
```

Response `202` `{}`. Sets `read` to `true` and writes an `inboxMessageRead` event. Calling it again for a message that is already read answers `202` again and writes nothing. It also works on a message the shopper has deleted.

Errors: `404 Message not found.` for an unknown id or another shopper’s id; `400 A valid userId is required.` when the body is missing or not sent as JSON.

### Mark all messages as read

`POST /api/v0/inbox/messages/read-all`

```plaintext
curl -X POST 'https://releva.ai/api/v0/inbox/messages/read-all' \
  -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"userId":"DEMO-CUSTOMER-1001"}'
```

Response `202` `{}`, also when nothing was unread. Marks every unread message of the shopper read and writes one `inboxMessageRead` event per unread, unexpired message. The unread count is `0` afterwards.

### Delete a message

`DELETE /api/v0/inbox/messages/{messageId}`

The request needs a JSON body with `userId`, which is unusual for a `DELETE`; make sure your HTTP client sends it.

```plaintext
curl -X DELETE 'https://releva.ai/api/v0/inbox/messages/0c5262f6-9791-4acd-9791-fcb6c10b6bad' \
  -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"userId":"DEMO-CUSTOMER-1001"}'
```

Response `204`, no body. The message disappears from the list and from the unread count and cannot be restored. It writes an `inboxMessageDelete` event. Deleting the same message again answers `204` again (and writes another event), so do not retry a `204`.

Errors: `404 Message not found.`; `400 A valid userId is required.` without a body.

### Report a tap on a message

`POST /api/v0/inbox/messages/{messageId}/action`

Call it when the shopper taps a link or button inside the message. The SDK widgets do this for you.

```plaintext
curl -X POST 'https://releva.ai/api/v0/inbox/messages/fe9db61a-b2ef-491e-bae7-e96735072932/action' \
  -H "authorization: Bearer $RELEVA_ACCESS_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"userId":"DEMO-CUSTOMER-1001","devicePlatform":"ios"}'
```

Response `202` `{}`. Writes an `inboxMessageClick` event. It does **not** mark the message as read; call the read endpoint as well when the shopper opens the message. Every call counts as one more click, also on a deleted message, so send it once per tap. `devicePlatform` (`ios` or `android`, sent by the SDKs) is accepted but not stored at the moment.

Errors: `404 Message not found.`; `400 A valid userId is required.`.

## Events these calls write

Each call writes one event on the shopper’s profile, with the message template id (`inboxMessageId`) attached. The push notification statistics define **Inbox reads** and **Inbox clicks** columns from these events, but they attribute events by `pushNotificationId`, which only the delivery event carries. In the current code the read, click and delete events written by the API are therefore not counted per push notification; expect **Inbox sent** to be filled and **Inbox reads** / **Inbox clicks** to stay at 0 until this is changed.

| Call                                                                | Event                |
| ------------------------------------------------------------------- | -------------------- |
| Delivery of the message by a campaign or workflow (not an API call) | `inboxMessageSend`   |
| Read, read-all (one per message)                                    | `inboxMessageRead`   |
| Action                                                              | `inboxMessageClick`  |
| Delete                                                              | `inboxMessageDelete` |

The event is written after the response is sent; a failure to write it is logged and does not change the status code.

## Versioning

All endpoints are under `/api/v0`. For how versions and changes are handled, see [Authentication, errors and limits](https://releva.ai/documentation/reference/get-started/authentication-errors-and-limits/#versioning).

## Next steps

* [How the App Inbox works](https://releva.ai/documentation/learn/inbox/how-the-app-inbox-works/): Learn who receives inbox messages, when they expire and what read and delete mean.
* [How push notifications work](https://releva.ai/documentation/learn/push-notifications/how-push-notifications-work/): Learn how the push notification an inbox message belongs to reaches devices.
* [Push notifications API overview](https://releva.ai/documentation/reference/push-notifications/overview/): Register the app push token that makes a profile eligible for inbox messages.
* [Find your API keys](https://releva.ai/documentation/guides/shop-settings/find-your-api-keys/): Copy the access token these requests authenticate with.