Docs
/
/
Contact supportLog inGet started
Overview
Client libraries
API keys
Authentication
Rate limits
Batch rate limits
Idempotent requests
Data retention
Bulk endpoints
Trigger data filtering
Pagination
Errors
Common error codes
Overview
Get user
List users
Identify user
Merge users
Delete user
List user messages
List user schedules
List user subscriptions
List user preference sets
Get user preference set
Update user preference set
Get channel data
Set channel data
Unset channel data
Get startedLog inContact support
Platform
Integrations
In-app UI
API reference
CLI reference
Management API
Developer tools
Tutorials

List user messages

Returns a paginated list of messages for a specific user. Messages are sorted with the most recent ones appearing first. Messages outside the account's retention window will not be included in the results.

Retention policy applied

List user messages

Returns a paginated list of messages for a specific user. Messages are sorted with the most recent ones appearing first. Messages outside the account's retention window will not be included in the results.

Endpoint

GET/v1/users/{user_id}/messages

Rate limit

Tier 4

Path parameters

user_id
string

The user ID to list messages for.

Query parameters

after
string

The cursor to fetch entries after.

before
string

The cursor to fetch entries before.

page_size
integer

The number of items per page (defaults to 50).

tenant
string

Limits the results to items with the corresponding tenant.

channel_id
string

Limits the results to items with the corresponding channel ID.

status[]
enum(string)[]

Limits the results to messages with the given delivery status.

queuedsentdelivereddelivery_attemptedundeliverednot_sentbounced
engagement_status[]
enum(string)[]

Limits the results to messages with the given engagement status.

seenunseenreadunreadarchivedunarchivedlink_clickedinteracted
message_ids[]
string[]

Limits the results to only the message IDs given (max 50). Note: when using this option, the results will be subject to any other filters applied to the query.

workflow_categories[]
string[]

Limits the results to messages related to any of the provided categories.

source
string

Limits the results to messages triggered by the given workflow key.

workflow_run_id
string(uuid)

Limits the results to messages associated with the top-level workflow run ID returned by the workflow trigger request.

workflow_recipient_run_id
string(uuid)

Limits the results to messages for a specific recipient's workflow run.

trigger_data
string

Limits the results to only messages that were generated with the given data. See trigger data filtering for more information.

inserted_at.gte
string

Limits the results to messages inserted after or on the given date.

inserted_at.lte
string

Limits the results to messages inserted before or on the given date.

inserted_at.gt
string

Limits the results to messages inserted after the given date.

inserted_at.lt
string

Limits the results to messages inserted before the given date.

Returns

ListMessagesResponse

A paginated list of messages.

items
Message[]

A list of messages.

__typename
string
Required

The typename of the schema.

actors
RecipientReference[]

One or more actors that are associated with this message. Note: this is a list that can contain up to 10 actors if the message is produced from a batch.

archived_at
string(date-time)

Timestamp when the message was archived.

channel
object

A configured channel, which is a way to route messages to a provider.

created_at
string(date-time)
Required

The timestamp of when the channel was created.

id
string
Required

The unique identifier for the channel.

key
string

Unique identifier for the channel within a project (immutable once created).

name
string

The human-readable name of the channel.

provider
string
Required

The ID of the provider that this channel uses to deliver messages.

type
enum(string)
Required

The type of channel, determining what kind of messages it can send.

emailin_appin_app_feedin_app_guidesmspushchathttp
updated_at
string(date-time)
Required

The timestamp of when the channel was last updated.

channel_id
string(uuid)
Required

Deprecated, use channel.id instead.

clicked_at
string(date-time)

Timestamp when the message was clicked.

data
object(any)

Data associated with the message’s workflow run. Includes the workflow trigger request’s data payload merged with any additional data returned by a fetch function. For messages produced after a batch step, includes the payload data from the most-recent trigger request (the final activity in the batch).

engagement_statuses
enum(string)[]
Required

A list of engagement statuses.

seenreadinteractedlink_clickedarchived
id
string
Required

The unique identifier for the message.

inserted_at
string(date-time)
Required

Timestamp when the resource was created.

interacted_at
string(date-time)

Timestamp when the message was interacted with.

link_clicked_at
string(date-time)

Timestamp when a link in the message was clicked.

metadata
object(any)

The metadata associated with the message.

read_at
string(date-time)

Timestamp when the message was read.

recipient
2 possible types
Required

A reference to a recipient, either a user identifier (string) or an object reference (ID, collection).

scheduled_at
string(date-time)

Timestamp when the message was scheduled to be sent.

seen_at
string(date-time)

Timestamp when the message was seen.

source
object
Required

The workflow or guide that triggered the message.

__typename
string
Required
categories
string[]
Required

The categories associated with the message.

key
string
Required

The key of the workflow or guide that triggered the message.

step_ref
string

The step reference for the step in the workflow that generated the message.

type
enum(string)

Whether this message was generated from a workflow, broadcast, or guide.

broadcastworkflowguide
version_id
string(uuid)
Required

The ID of the version of the workflow or guide that triggered the message.

workflow_recipient_run_id
string(uuid)

The unique identifier for the workflow recipient run that generated this message. Only present for workflow/broadcast messages.

workflow_run_id
string(uuid)

The unique identifier for the workflow run that generated this message. Only present for workflow/broadcast messages.

status
enum(string)
Required

The message delivery status.

queuedsentdelivereddelivery_attemptedundeliverednot_sentbounced
tenant
string

The ID of the tenant associated with the message. Only present when a tenant is provided on a workflow trigger request.

updated_at
string(date-time)
Required

The timestamp when the resource was last updated.

workflow
string

The key of the workflow that generated the message.

page_info
PageInfo

Pagination information for a list of resources.

__typename
string

The typename of the schema.

after
string

The cursor to fetch entries after.

before
string

The cursor to fetch entries before.

page_size
integer

The number of items per page (defaults to 50).

New chat