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.
When to use it
Section titled “When to use it”- Releva React Native or Swift SDK: you do not call these endpoints.
client.initializeInbox()and theInboxServicemethods 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.
Authentication
Section titled “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.
authorization: Bearer $RELEVA_ACCESS_TOKENAuthentication 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.
The userId
Section titled “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
GETendpoints it goes in the query string. - On
POSTandDELETEit goes in the JSON body, also on theDELETE.
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
Section titled “Request format”- HTTPS only. Plain HTTP answers
400 {"message":"We do not support non-HTTPS requests."}. - Send JSON with
content-type: application/jsononPOSTandDELETE. With another content type the body is not parsed and you get400 {"message":"A valid userId is required."}. - Bodies are limited to 800 KB (far more than these calls need).
- Unknown body fields are ignored.
Responses
Section titled “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 |
Limits
Section titled “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
Section titled “Message object”{ "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
Section titled “Endpoints”List messages
Section titled “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.
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:
- Call without
cursor. - While
nextCursoris notnull, call again withcursor=<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
Section titled “Count unread messages”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.
Mark a message as read
Section titled “Mark a message as read”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.
Mark all messages as read
Section titled “Mark all messages as read”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 a message
Section titled “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.
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
Section titled “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.
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
Section titled “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
Section titled “Versioning”All endpoints are under /api/v0. For how versions and changes are handled, see Authentication, errors and limits.