Skip to main content
The Messages API lets you fetch a paginated list of messages in your workspace and bulk update message statuses (for example mark as seen, read, archived). These Python helpers are wrappers over the underlying List Messages and Bulk Update Message Status endpoints.

​
List Messages

Fetch a paginated list of messages for your workspace. All filter parameters are optional. 
from suprsend import Suprsend

supr_client = Suprsend("workspace_key", "workspace_secret")

# Returns first page with default limit
response = supr_client.messages.list()
print(response)
Filter parameters
ParameterTypeDescription
limitintegerRecords per page. Default 1000, max 1000.
afterstringOpaque cursor for the next page. Pass the meta.after value from a previous response.
beforestringOpaque cursor for the previous page. Pass the meta.before value from a previous response.
message_idstringFilter by a specific message id.
idempotency_keystringFilter by the idempotency key associated with the message at trigger time.
recipient_idarray of stringFilter by one or more recipient distinct_ids. Multiple values are OR-ed.
tenant_idstringFilter messages belonging to a specific tenant.
object_typestringFilter messages sent to an object. Must be provided together with object_id.
object_idstringFilter messages sent to an object. Must be provided together with object_type.
workflow_slugstringFilter messages triggered from a specific workflow.
execution_idstringFilter by workflow execution id (matches wf_exec_id or broadcast_id).
channelstringFilter by delivery channel. Valid values: email, sms, whatsapp, androidpush, iospush, webpush, slack, ms_teams.
statusarray of stringFilter by one or more derived statuses. Multiple values are OR-ed. Valid values: triggered, delivered, delivery_failed, seen, clicked, dismissed, read, unread, archived.
categoryarray of stringFilter by one or more notification categories. Multiple values are OR-ed.
is_campaignbooleanSet True to return only messages sent as part of a broadcast/campaign.
created_at_gtestring (RFC3339)Inclusive lower bound on created_at. Example: "2026-01-01T00:00:00Z".
created_at_ltestring (RFC3339)Inclusive upper bound on created_at. Must be >= created_at_gte when both are set.

​
Bulk Update Message Status

Update the status of one or more messages in a single call. 
from suprsend import Suprsend

supr_client = Suprsend("workspace_key", "workspace_secret")

messages = [
    {"message_id": "__message_id_1__", "action": "read"},
    {"message_id": "__message_id_2__", "action": "archived"},
]
response = supr_client.messages.bulk_update(messages)
print(response)
Available actions and their descriptions:
ActionDescriptionApplicable Channels
seenMark the message as viewed/opened by the user.All channels
clickedMark the message as clicked by the user.All channels
dismissedMark the push notification as dismissed by the user (for example, swiped away from the notification tray).androidpush, iospush
readMark the inbox message as read. Doesn’t change the message status on update, instead sets is_read flag and read_at timestamp.inbox only
unreadRevert a previously read inbox message back to unread. Doesn’t change the message status on update, instead unsets is_read flag and record unread_at timestamp.inbox only
archivedMove the inbox message to the archive. Doesn’t change the message status on update, instead sets is_archived flag and marks archived_at timestamp.inbox only
unarchivedRestore a previously archived inbox message back to the active list. Doesn’t change the message status on update, instead unsets is_archived flag and record unarchived_at timestamp.inbox only