Notification inbox
The in-app notification inbox — adding messages with add_to_inbox, expiry, SDK and public API endpoints, read/archived states.
The notification inbox is a persistent list of messages the user can see inside the app even if a push never arrives. When add_to_inbox: true is set on a POST /v1/notifications, campaign or journey send, an item is created for each targeted (non-suppressed) user: title/body in the user's language, app_url or url, big_picture and data. The same message is added to the same user only once; when inbox_ttl (seconds) expires, the item becomes invisible and is deleted during daily maintenance.
{
"target": { "include_external_ids": ["user_42"] },
"headings": { "tr": "Kampanya başladı" },
"contents": { "tr": "Seçili ürünlerde %20 indirim" },
"app_url": "myapp://campaigns/spring",
"add_to_inbox": true,
"inbox_ttl": 604800
}Messages without a push channel (e.g. only target.channels: ["email"]) are added to the inbox too; for users without push permission, it may be the only visible channel.
Content cards
If content_card { type, pinned?, priority?, button_text? } is added to the message content, a persistent card is created for each
person reached (types classic, captioned_image, image_only; image types require big_picture). Cards do not appear in the inbox list or in the unread
count; in the SDKs they are read through ContentCards (list, impression, click, dismiss). Android HsContentCardsView and
iOS HSContentCardsView are ready-made views. Impression and click rates appear in the campaign details.
SDK endpoints
The subscription must belong to the user; if the app requires identity verification, identity_hash (or a JWT) is mandatory.
| Endpoint | Response |
|---|---|
GET /sdk/v1/apps/{app_id}/users/{user_id}/inbox?subscription_id=&identity_hash=&limit=&cursor= | { data: [{ id, message_id, title, body, url, image_url, data, read, read_at, archived_at, expires_at, created_at }], unread_count, next_cursor, has_more } (newest first) |
POST …/inbox/{item_id}/read { subscription_id, identity_hash? } | the item |
POST …/inbox/read-all { subscription_id, identity_hash? } | { updated, unread_count } |
DELETE …/inbox/{item_id}?subscription_id=&identity_hash= | archives the item |
SDK surface (the same on all clients): Pushizo.Inbox.list({ cursor }), markRead(id), markAllRead(), archive(id), unreadCount and a change observer; a ready-made component on Web (Web SDK → notification inbox), and <PushizoInbox /> in framework wrappers (React).
Public API
The user is selected by alias; reading requires users:read, modifying users:write:
GET /v1/apps/{app_id}/users/by/{label}/{value}/inbox?include_archived=&limit=&cursor=POST …/inbox/{item_id}/read,POST …/inbox/read-all,DELETE …/inbox/{item_id}
All fields and language examples: API → Notification inbox. In the dashboard, the Notification inbox tab on the user detail page shows the items and their states.
Behavior notes
- The unread count
unread_countis returned with every list; the SDK uses it for badges/counters. - In A/B campaigns, the item is created with the content of the variant assigned to the user.
- When a user is deleted, their items are deleted; "Clear data" empties the inbox.
Embedded placements
Instead of a popup, place content in an area you reserve in your app, such as a home page banner or a recommendation slot below the cart. You change the content from the dashboard; no app update is needed. Decision record:…
Users, aliases and subscriptions
The Pushizo identity model — end users, external_id and custom aliases, subscriptions (device, email, phone), tags/properties/deltas, anonymous → identified merging, events and public API endpoints.