Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

List scheduled mailbox sends

GET
/v1/email/mailboxes/{mailbox_id}/scheduled-messages
bird email mailboxes scheduled-messages list <mailbox-id>
Response200
{
  "data": [
    {
      "id": "msm_01krdgeqcxet5s7t44vh8rt9mg",
      "mailbox_id": "mbx_01krdgeqcxet5s7t44vh8rt9mg",
      "thread_id": "thr_01krdgeqcxet5s7t44vh8rt9mg",
      "status": "scheduled",
      "scheduled_at": "2026-05-20T10:00:00Z",
      "cancel_on_reply": false,
      "recipients": [
        "customer@example.com"
      ],
      "subject": "Your request",
      "snippet": "Here is the reply.",
      "created_by": {
        "id": "usr_01krdgeqcxet5s7t44vh8rt9mg",
        "type": "user"
      },
      "created_at": "2026-05-20T09:14:52Z",
      "updated_at": "2026-05-20T09:14:52Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

List scheduled sends separately from conversation messages, including completed and canceled records. Filter by conversation or status; use cursors to page.

Parameters

mailbox_idstring

Mailbox that owns the scheduled send.

Query Parameters

thread_idstring

Filter by the reserved conversation identifier.

statusstring

Filter by scheduling state.

Possible values: scheduled, sending, sent, failed, canceled

limitinteger

Maximum number of items to return per page.

starting_afterstring

Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

Response Payload

data
array of object
required
Show child attributes
data.id
string
required

Scheduled send identifier.

data.mailbox_id
string
required

Mailbox that owns the send.

data.thread_id
string
required

Reserved conversation identifier. A new compose does not create the conversation until dispatch.

data.message_id
string

Actual message identifier once handed to the send pipeline.

data.status
string
required
  • scheduled: Waiting for its due time; cancellation is still possible.
  • sending: Dispatch has been claimed; cancellation is no longer possible.
  • sent: Handed to the ordinary send pipeline, not necessarily delivered. Follow message_id for delivery status.
  • failed: Terminal dispatch refusal or failure; see failure_reason. The schedule will not retry.
  • canceled: Terminal cancellation before dispatch; see cancellation_reason. The message will not send.

Possible values: scheduled, sending, sent, failed, canceled

data.scheduled_at
string
required

Scheduled at.

data.cancel_on_reply
boolean
required

Whether an inbound message cancels this send before dispatch is claimed.

data.failure_reason
string

Why dispatch failed.

data.cancellation_reason
string

Why canceled; replied means new inbound mail canceled an opted-in schedule.

data.subject
string
required

Frozen subject.

data.snippet
string
required

Plain-text preview of the frozen message.

data.recipients
array of string
required

Visible recipients (To and Cc). Bcc addresses remain only in the frozen send payload.

data.created_by
object
required

Authenticated caller that scheduled the send.

Show child attributes
data.created_by.id
string
required

Actor identifier.

data.created_by.type
string
required

New actor types may be added. Treat unrecognized values as future types, not errors.

  • user: a member's own session.
  • api_key: a workspace API key.
  • oauth_token: a token issued to a caller on a member's behalf.
  • system: an action we perform without a customer actor.
  • sso: an organization's SSO connection.
  • service_account: a workspace's connected Integration acting with no member behind it.
  • automation: an automation execution in your workspace.

Possible values (may grow over time): user, api_key, oauth_token, system, sso, service_account, automation

data.created_by.display_name
nullable string

The label the actor is shown under: typically a member's name or email address, or the API key's name. Null when it could not be resolved.

data.created_at
string
required
data.updated_at
string
required
next_cursor
nullable string
required

Cursor for the next page. Pass back as starting_after to advance forward. null when no next page exists.

prev_cursor
nullable string
required

Cursor for the previous page. Pass back as ending_before to step backward. null when no previous page exists.

refresh_cursor
nullable string
required

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief