Skip to content

Area: Developers

Inbox API overview

Used byMobile SDKs, iOS (Swift), Flutter, React Native

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

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

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.

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.

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.

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

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.

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:

{
"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.

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

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.

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

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.

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

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

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.

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.

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

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.

All endpoints are under /api/v0. For how versions and changes are handled, see Authentication, errors and limits.