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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

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)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Retention policy applied

Get message content

Returns the fully rendered contents of a message, where the response depends on which channel the message was sent through.

Endpoint

GET/v1/messages/{message_id}/content

Rate limit

Tier 4

Path parameters

message_id

string

The ID of the message to fetch contents of.

Returns

MessageContents

The content of a message.

__typename

string

The typename of the schema.

data

5 possible types

Content data specific to the channel type.

inserted_at

string(date-time)

Timestamp when the message content was created.

message_id

string

The unique identifier for the message content.

Retention policy applied

List messages

Returns a paginated list of messages for the current environment.

Endpoint

GET/v1/messages

Rate limit

Tier 4

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.

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)

engagement_statuses

enum(string)[]

Required

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

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

Retention policy applied

List events

Returns a paginated list of events for the specified message.

Endpoint

GET/v1/messages/{message_id}/events

Rate limit

Tier 3

Path parameters

message_id

string

The ID of the message to fetch events 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).

Returns

ListMessageEventsResponse

Returns a paginated list of delivery and engagement events for the specified message.

items

MessageEvent[]

A list of message events.

__typename

string

Required

The typename of the schema.

data

object(any)

The data associated with the message event. Only present for some event types.

string

Required

The unique identifier for the message event.

inserted_at

string(date-time)

Required

Timestamp when the event was created.

recipient

2 possible types

Required

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

type

enum(string)

Required

The type of event that occurred.

message.archivedmessage.bouncedmessage.deliveredmessage.delivery_attemptedmessage.interactedmessage.link_clickedmessage.not_sentmessage.queuedmessage.readmessage.seenmessage.sentmessage.unarchivedmessage.undeliveredmessage.unreadmessage.unseen

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

Retention policy applied

List delivery logs

Returns a paginated list of delivery logs for the specified message.

Endpoint

GET/v1/messages/{message_id}/delivery_logs

Rate limit

Tier 3

Path parameters

message_id

string

The ID of the message to fetch delivery logs 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).

Returns

ListMessageDeliveryLogsResponse

A message delivery log response.

items

MessageDeliveryLog[]

Returns a paginated list of delivery logs from the downstream provider for the specified message. For Knock in-app channels, the delivery logs will always be an empty list.

__typename

string

Required

The typename of the schema.

environment_id

string(uuid)

Required

The ID of the environment in which the message delivery occurred.

string

Required

The unique identifier for the message delivery log.

inserted_at

string

Required

Timestamp when the message delivery log was created.

request

MessageDeliveryLogRequest

Required

A message delivery log request.

body

2 possible types

The body content that was sent with the request.

headers

object(any)

The headers that were sent with the request.

host

string

The host to which the request was sent.

method

enum(string)

The HTTP method used for the request.

GETPOSTPUTDELETEPATCH

path

string

The path of the URL that was requested.

query

string

The query string of the URL that was requested.

response

MessageDeliveryLogResponse

Required

A message delivery log response.

body

2 possible types

The body content that was received with the response.

headers

object(any)

The headers that were received with the response.

status

integer

The HTTP status code of the response.

service_name

string

Required

The name of the service that processed the delivery.

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

Retention policy applied

List activities

Returns a paginated list of activities for the specified message.

Endpoint

GET/v1/messages/{message_id}/activities

Rate limit

Tier 4

Path parameters

message_id

string

The ID of the message to fetch activities for.

Query parameters

trigger_data

string

The trigger data to filter activities by.

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

Returns

ListActivitiesResponse

Returns a paginated list of activities associated with a given message. For messages produced after a batch step, this will contain one or more activities. Non-batched messages will always return a single activity.

items

Activity[]

A list of activities.

__typename

string

The typename of the schema.

actor

Recipient

The actor who performed the activity.

data

object(any)

The workflow trigger data payload associated with the activity.

string

Unique identifier for the activity.

inserted_at

string(date-time)

Timestamp when the activity was created.

recipient

2 possible types

A recipient of a notification, which is either a user or an object.

updated_at

string(date-time)

Timestamp when the activity was last updated.

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

Retention policy applied

Mark message as seen

Marks a message as seen. This indicates that the user has viewed the message in their feed or inbox. Read more about message engagement statuses here.

Endpoint

PUT/v1/messages/{message_id}/seen

Rate limit

Tier 2

Path parameters

message_id

string

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

__typename

string

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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

Deprecated, use channel.id instead.

clicked_at

string(date-time)

Timestamp when the message was clicked.

data

object(any)

engagement_statuses

enum(string)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Retention policy applied

Mark message as unseen

Marks a message as unseen. This reverses the seen state. Read more about message engagement statuses here.

Endpoint

DELETE/v1/messages/{message_id}/seen

Rate limit

Tier 2

Path parameters

message_id

string

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

__typename

string

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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

Deprecated, use channel.id instead.

clicked_at

string(date-time)

Timestamp when the message was clicked.

data

object(any)

engagement_statuses

enum(string)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Retention policy applied

Mark message as read

Marks a message as read. This indicates that the user has read the message content. Read more about message engagement statuses here.

Endpoint

PUT/v1/messages/{message_id}/read

Rate limit

Tier 2

Path parameters

message_id

string

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

__typename

string

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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

Deprecated, use channel.id instead.

clicked_at

string(date-time)

Timestamp when the message was clicked.

data

object(any)

engagement_statuses

enum(string)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Retention policy applied

Mark message as unread

Marks a message as unread. This reverses the read state. Read more about message engagement statuses here.

Endpoint

DELETE/v1/messages/{message_id}/read

Rate limit

Tier 2

Path parameters

message_id

string

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

__typename

string

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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

Deprecated, use channel.id instead.

clicked_at

string(date-time)

Timestamp when the message was clicked.

data

object(any)

engagement_statuses

enum(string)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Retention policy applied

Mark message as interacted

Marks a message as interacted with by the user. This can include any user action on the message, with optional metadata about the specific interaction. Cannot include more than 5 key-value pairs, must not contain nested data. Read more about message engagement statuses here.

Endpoint

PUT/v1/messages/{message_id}/interacted

Rate limit

Tier 2

Path parameters

message_id

string

The unique identifier for the message.

Request body

metadata

object(any)

Metadata about the interaction.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

__typename

string

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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

Deprecated, use channel.id instead.

clicked_at

string(date-time)

Timestamp when the message was clicked.

data

object(any)

engagement_statuses

enum(string)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Retention policy applied

Archive message

Archives a message for the user. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.

Endpoint

PUT/v1/messages/{message_id}/archived

Rate limit

Tier 2

Path parameters

message_id

string

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

__typename

string

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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

Deprecated, use channel.id instead.

clicked_at

string(date-time)

Timestamp when the message was clicked.

data

object(any)

engagement_statuses

enum(string)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Retention policy applied

Unarchive message

Removes a message from the archived state, making it visible in the default message list in the feed again.

Endpoint

DELETE/v1/messages/{message_id}/archived

Rate limit

Tier 2

Path parameters

message_id

string

The unique identifier for the message.

Returns

Message

Represents a single message that was generated by a workflow for a given channel.

__typename

string

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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

Deprecated, use channel.id instead.

clicked_at

string(date-time)

Timestamp when the message was clicked.

data

object(any)

engagement_statuses

enum(string)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Batch operations

Operations that can be performed on a batch of messages.

Endpoints

GET/v1/messages/batch/content

POST/v1/messages/batch/seen

POST/v1/messages/batch/unseen

POST/v1/messages/batch/read

POST/v1/messages/batch/unread

POST/v1/messages/batch/interacted

POST/v1/messages/batch/archived

POST/v1/messages/batch/unarchived

Retention policy applied

Batch get message contents

Get the contents of multiple messages in a single request.

Endpoint

GET/v1/messages/batch/content

Rate limit

Tier 4

Query parameters

message_ids[]

string[]

The IDs of the messages to fetch contents of.

Returns

BatchGetMessageContentsResponse

A list of MessageContents

Retention policy applied

Mark messages as seen

Marks the given messages as seen. This indicates that the user has viewed the message in their feed or inbox. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/seen

Rate limit

Tier 3

Request body

message_ids

string[]

Required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as unseen

Marks the given messages as unseen. This reverses the seen state. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/unseen

Rate limit

Tier 3

Request body

message_ids

string[]

Required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as read

Marks the given messages as read. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/read

Rate limit

Tier 3

Request body

message_ids

string[]

Required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as unread

Marks the given messages as unread. This reverses the read state. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/unread

Rate limit

Tier 3

Request body

message_ids

string[]

Required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as interacted

Marks the given messages as interacted with by the user. This can include any user action on the message, with optional metadata about the specific interaction. Cannot include more than 5 key-value pairs, must not contain nested data. Read more about message engagement statuses here.

Endpoint

POST/v1/messages/batch/interacted

Rate limit

Tier 3

Request body

message_ids

string[]

Required

The message IDs to batch mark as interacted with.

metadata

object(any)

Metadata about the interaction.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as archived

Marks the given messages as archived. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.

Endpoint

POST/v1/messages/batch/archived

Rate limit

Tier 3

Request body

message_ids

string[]

Required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Retention policy applied

Mark messages as unarchived

Marks the given messages as unarchived. This reverses the archived state. Archived messages are hidden from the default message list in the feed but can still be accessed and unarchived later.

Endpoint

POST/v1/messages/batch/unarchived

Rate limit

Tier 3

Request body

message_ids

string[]

Required

The message IDs to update the status of.

Returns

BatchListMessagesResponse

The list of messages that were updated.

Message

Represents a single message that was generated by a workflow for a given channel.

Attributes

__typename

string

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)

The timestamp of when the channel was created.

string

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

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

type

enum(string)

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

emailin_appin_app_feedin_app_guidesmspushchathttp

updated_at

string(date-time)

The timestamp of when the channel was last updated.

channel_id

string(uuid)

Deprecated, use channel.id instead.

clicked_at

string(date-time)

Timestamp when the message was clicked.

data

object(any)

engagement_statuses

enum(string)[]

A list of engagement statuses.

seenreadinteractedlink_clickedarchived

string

The unique identifier for the message.

inserted_at

string(date-time)

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

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

The workflow or guide that triggered the message.

__typename

string

categories

string[]

The categories associated with the message.

key

string

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)

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)

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)

The timestamp when the resource was last updated.

workflow

string

The key of the workflow that generated the message.

Activity

An activity associated with a workflow trigger request. Messages produced after a batch step can be associated with one or more activities. Non-batched messages will always be associated with a single activity.

Attributes

__typename

string

The typename of the schema.

actor

Recipient

The actor who performed the activity.

data

object(any)

The workflow trigger data payload associated with the activity.

string

Unique identifier for the activity.

inserted_at

string(date-time)

Timestamp when the activity was created.

recipient

2 possible types

A recipient of a notification, which is either a user or an object.

updated_at

string(date-time)

Timestamp when the activity was last updated.

MessageDeliveryLog

A message delivery log contains a request from Knock to a downstream provider and the response that was returned.

Attributes

__typename

string

The typename of the schema.

environment_id

string(uuid)

The ID of the environment in which the message delivery occurred.

string

The unique identifier for the message delivery log.

inserted_at

string

Timestamp when the message delivery log was created.

request

MessageDeliveryLogRequest

A message delivery log request.

body

2 possible types

The body content that was sent with the request.

headers

object(any)

The headers that were sent with the request.

host

string

The host to which the request was sent.

method

enum(string)

The HTTP method used for the request.

GETPOSTPUTDELETEPATCH

path

string

The path of the URL that was requested.

query

string

The query string of the URL that was requested.

response

MessageDeliveryLogResponse

A message delivery log response.

body

2 possible types

The body content that was received with the response.

headers

object(any)

The headers that were received with the response.

status

integer

The HTTP status code of the response.

service_name

string

The name of the service that processed the delivery.

MessageEvent

A message event. Occurs when a message delivery or engagement status changes.

Attributes

__typename

string

The typename of the schema.

data

object(any)

The data associated with the message event. Only present for some event types.

string

The unique identifier for the message event.

inserted_at

string(date-time)

Timestamp when the event was created.

recipient

2 possible types

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

type

enum(string)

The type of event that occurred.