Knock Messages API
Read, list, and update Knock messages — the per-recipient delivery records produced by workflow runs. Includes activity, delivery log, and event timelines plus mark-as-seen/read/interacted/archived single and batch endpoints.
OpenAPI Specification
openapi: 3.0.3
info:
title: Knock Messages API
version: '1.0'
description: Read, list, and update Knock messages — the per-recipient delivery records produced by workflow runs. Includes
activity, delivery log, and event timelines plus mark-as-seen/read/interacted/archived single and batch endpoints.
contact:
name: Knock
url: https://knock.app
license:
name: Proprietary
servers:
- url: https://api.knock.app
variables: {}
security:
- BearerAuth: []
paths:
/v1/messages/{message_id}/delivery_logs:
get:
callbacks: {}
description: Returns a paginated list of delivery logs for the specified message.
operationId: listMessageDeliveryLogs
parameters:
- description: The ID of the message to fetch delivery logs for.
in: path
name: message_id
required: true
schema:
type: string
x-struct: null
x-validate: null
- description: The cursor to fetch entries after.
in: query
name: after
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The cursor to fetch entries before.
in: query
name: before
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The number of items per page (defaults to 50).
in: query
name: page_size
required: false
schema:
type: integer
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessageDeliveryLogsResponse'
description: OK
summary: List delivery logs
tags:
- Messages
x-ratelimit-tier: 3
x-retention-policy: true
/v1/messages:
get:
callbacks: {}
description: Returns a paginated list of messages for the current environment.
operationId: listMessages
parameters:
- description: The cursor to fetch entries after.
in: query
name: after
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The cursor to fetch entries before.
in: query
name: before
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The number of items per page (defaults to 50).
in: query
name: page_size
required: false
schema:
type: integer
x-struct: null
x-validate: null
- description: Limits the results to items with the corresponding tenant.
example: tenant_123
in: query
name: tenant
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Limits the results to items with the corresponding channel ID.
example: 123e4567-e89b-12d3-a456-426614174000
in: query
name: channel_id
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Limits the results to messages with the given delivery status.
example:
- delivered
in: query
name: status[]
required: false
schema:
items:
enum:
- queued
- sent
- delivered
- delivery_attempted
- undelivered
- not_sent
- bounced
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
- description: Limits the results to messages with the given engagement status.
example:
- unread
in: query
name: engagement_status[]
required: false
schema:
items:
enum:
- seen
- unseen
- read
- unread
- archived
- unarchived
- link_clicked
- interacted
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
- description: '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.'
example:
- 1jNaXzB2RZX3LY8wVQnfCKyPnv7
in: query
name: message_ids[]
required: false
schema:
items:
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
- description: Limits the results to messages related to any of the provided categories.
example:
- workflow_123
in: query
name: workflow_categories[]
required: false
schema:
items:
type: string
x-struct: null
x-validate: null
type: array
x-struct: null
x-validate: null
- description: Limits the results to messages triggered by the given workflow key.
example: comment-created
in: query
name: source
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Limits the results to messages associated with the top-level workflow run ID returned by the workflow
trigger request.
example: 123e4567-e89b-12d3-a456-426614174000
in: query
name: workflow_run_id
required: false
schema:
format: uuid
type: string
x-struct: null
x-validate: null
- description: Limits the results to messages for a specific recipient's workflow run.
example: 123e4567-e89b-12d3-a456-426614174000
in: query
name: workflow_recipient_run_id
required: false
schema:
format: uuid
type: string
x-struct: null
x-validate: null
- description: Limits the results to only messages that were generated with the given data. See [trigger data filtering](/api-reference/overview/trigger-data-filtering)
for more information.
example: '{"comment_id": "123"}'
in: query
name: trigger_data
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Limits the results to items inserted after the given date.
example: '2025-01-01T00:00:00Z'
in: query
name: inserted_at.gt
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Limits the results to items inserted after or on the given date.
example: '2025-01-01T00:00:00Z'
in: query
name: inserted_at.gte
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Limits the results to items inserted before the given date.
example: '2025-01-01T00:00:00Z'
in: query
name: inserted_at.lt
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: Limits the results to items inserted before or on the given date.
example: '2025-01-01T00:00:00Z'
in: query
name: inserted_at.lte
required: false
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessagesResponse'
description: OK
summary: List messages
tags:
- Messages
x-ratelimit-tier: 4
x-retention-policy: true
/v1/messages/{message_id}/unseen:
delete:
callbacks: {}
description: Marks a message as `unseen`. This reverses the `seen` state. Read more about message engagement statuses
[here](/send-notifications/message-statuses#engagement-status).
operationId: markMessageUnseen (2)
parameters:
- description: The unique identifier for the message.
example: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
in: path
name: message_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Message'
example:
__typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses: []
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: null
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
step_ref: email_step_1
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
x-struct: null
x-validate: null
description: OK
summary: Mark message as unseen
tags:
- Messages
x-ratelimit-tier: 2
x-retention-policy: true
/v1/messages/batch/unarchived:
post:
callbacks: {}
description: 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.
operationId: batchMarkMessagesAsUnarchived
parameters: []
requestBody:
content:
application/json:
example:
message_ids:
- 2w3YUpTTOxuDvZFji8OMsKrG176
- 2w3YVRbPXMIh8Zq6oBFcVDA5xes
schema:
$ref: '#/components/schemas/BatchMessagesStatusRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
description: The list of messages that were updated.
example:
- __typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses:
- seen
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: '2025-01-01T00:01:00Z'
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
items:
allOf:
- $ref: '#/components/schemas/Message'
example:
__typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses:
- seen
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: '2025-01-01T00:01:00Z'
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
x-struct: null
x-validate: null
title: BatchListMessagesResponse
type: array
x-struct: null
x-validate: null
description: OK
summary: Mark messages as unarchived
tags:
- Messages
x-ratelimit-tier: 3
x-retention-policy: true
/v1/messages/{message_id}/unread:
delete:
callbacks: {}
description: Marks a message as `unread`. This reverses the `read` state. Read more about message engagement statuses
[here](/send-notifications/message-statuses#engagement-status).
operationId: markMessageUnread (2)
parameters:
- description: The unique identifier for the message.
example: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
in: path
name: message_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Message'
example:
__typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses:
- seen
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: '2025-01-01T00:01:00Z'
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
step_ref: email_step_1
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
x-struct: null
x-validate: null
description: OK
summary: Mark message as unread
tags:
- Messages
x-ratelimit-tier: 2
x-retention-policy: true
/v1/messages/{message_id}/seen:
delete:
callbacks: {}
description: Marks a message as `unseen`. This reverses the `seen` state. Read more about message engagement statuses
[here](/send-notifications/message-statuses#engagement-status).
operationId: markMessageUnseen
parameters:
- description: The unique identifier for the message.
example: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
in: path
name: message_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Message'
example:
__typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses: []
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: null
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
step_ref: email_step_1
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
x-struct: null
x-validate: null
description: OK
summary: Mark message as unseen
tags:
- Messages
x-ratelimit-tier: 2
x-retention-policy: true
put:
callbacks: {}
description: 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](/send-notifications/message-statuses#engagement-status).
operationId: markMessageSeen
parameters:
- description: The unique identifier for the message.
example: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
in: path
name: message_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Message'
example:
__typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses:
- seen
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: '2025-01-01T00:01:00Z'
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
step_ref: email_step_1
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
x-struct: null
x-validate: null
description: OK
summary: Mark message as seen
tags:
- Messages
x-ratelimit-tier: 2
x-retention-policy: true
/v1/messages/{message_id}/events:
get:
callbacks: {}
description: Returns a paginated list of events for the specified message.
operationId: listMessageEvents
parameters:
- description: The ID of the message to fetch events for.
in: path
name: message_id
required: true
schema:
type: string
x-struct: null
x-validate: null
- description: The cursor to fetch entries after.
in: query
name: after
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The cursor to fetch entries before.
in: query
name: before
required: false
schema:
type: string
x-struct: null
x-validate: null
- description: The number of items per page (defaults to 50).
in: query
name: page_size
required: false
schema:
type: integer
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListMessageEventsResponse'
description: OK
summary: List events
tags:
- Messages
x-ratelimit-tier: 3
x-retention-policy: true
/v1/messages/batch/seen:
post:
callbacks: {}
description: 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](/send-notifications/message-statuses#engagement-status).
operationId: batchMarkMessagesAsSeen
parameters: []
requestBody:
content:
application/json:
example:
message_ids:
- 2w3YUpTTOxuDvZFji8OMsKrG176
- 2w3YVRbPXMIh8Zq6oBFcVDA5xes
schema:
$ref: '#/components/schemas/BatchMessagesStatusRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
description: The list of messages that were updated.
example:
- __typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses:
- seen
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: '2025-01-01T00:01:00Z'
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
items:
allOf:
- $ref: '#/components/schemas/Message'
example:
__typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses:
- seen
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: '2025-01-01T00:01:00Z'
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
x-struct: null
x-validate: null
title: BatchListMessagesResponse
type: array
x-struct: null
x-validate: null
description: OK
summary: Mark messages as seen
tags:
- Messages
x-ratelimit-tier: 3
x-retention-policy: true
/v1/messages/batch/unseen:
post:
callbacks: {}
description: Marks the given messages as `unseen`. This reverses the `seen` state. Read more about message engagement
statuses [here](/send-notifications/message-statuses#engagement-status).
operationId: batchMarkMessagesAsUnseen
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BatchMessagesStatusRequest'
description: Params
required: true
responses:
'200':
content:
application/json:
schema:
description: The list of messages that were updated.
example:
- __typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses: []
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: null
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
items:
allOf:
- $ref: '#/components/schemas/Message'
example:
__typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses: []
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: null
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
x-struct: null
x-validate: null
title: BatchListMessagesResponse
type: array
x-struct: null
x-validate: null
description: OK
summary: Mark messages as unseen
tags:
- Messages
x-ratelimit-tier: 3
x-retention-policy: true
/v1/messages/{message_id}/read:
delete:
callbacks: {}
description: Marks a message as `unread`. This reverses the `read` state. Read more about message engagement statuses
[here](/send-notifications/message-statuses#engagement-status).
operationId: markMessageUnread
parameters:
- description: The unique identifier for the message.
example: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
in: path
name: message_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/Message'
example:
__typename: Message
actors:
- user_123
archived_at: null
channel_id: 123e4567-e89b-12d3-a456-426614174000
clicked_at: null
data:
foo: bar
engagement_statuses:
- seen
id: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
inserted_at: '2021-01-01T00:00:00Z'
interacted_at: null
link_clicked_at: null
metadata:
external_id: 123e4567-e89b-12d3-a456-426614174000
read_at: null
recipient: user_123
scheduled_at: null
seen_at: '2025-01-01T00:01:00Z'
source:
__typename: NotificationSource
categories:
- collaboration
key: comment-created
step_ref: email_step_1
version_id: 123e4567-e89b-12d3-a456-426614174000
status: sent
tenant: tenant_123
updated_at: '2021-01-01T00:00:00Z'
workflow: comment-created
x-struct: null
x-validate: null
description: OK
summary: Mark message as unread
tags:
- Messages
x-ratelimit-tier: 2
x-retention-policy: true
put:
callbacks: {}
description: Marks a message as `read`. This indicates that the user has read the message content. Read more about message
engagement statuses [here](/send-notifications/message-statuses#engagement-status).
operationId: markMessageRead
parameters:
- description: The unique identifier for the message.
example: 1jNaXzB2RZX3LY8wVQnfCKyPnv7
in: path
name: message_id
required: true
schema:
type: string
x-struct: null
x-validate: null
responses:
'200':
content:
application/json:
schema:
# --- truncated at 32 KB (116 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/knock-app/refs/heads/main/openapi/knock-messages-api-openapi.yml