---
title: "List scheduled mailbox sends"
canonical: "https://bird.com/docs/api/reference/list-mailbox-scheduled-messages"
---

# List scheduled mailbox sends

`GET /v1/email/mailboxes/{mailbox_id}/scheduled-messages`

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

## Servers

- `https://{region}.platform.bird.com`: Regional API endpoint. Use the host for the region your organization is hosted in. Official Bird SDKs and the CLI select it automatically from your API key, so you rarely need to set it by hand.
  - `region`: `us1`, `eu1`. Default: `us1`. The region your organization's data is hosted in.
- `https://platform.bird.com`: Region-independent endpoint for authentication and account administration.
- `http://localhost:8080`: Local development.

## Authentication

Use one authentication option:

- `BearerAuth`: HTTP bearer authentication. Pass the API key as a bearer token in the `Authorization` header. Workspace
keys use `bk_{region}_*`; organization master keys use `bm_{region}_*`.
The prefix identifies the region and selects the
API endpoint. Official Bird SDKs and the CLI derive the region from the key.

- `CookieAuth`: Send `bird_session` in cookie. Session cookie set after signing in to the Bird dashboard. The cookie
value is an opaque session token; no session data is stored in the cookie
itself.

## Code samples

**CLI**

```sh
bird email mailboxes scheduled-messages list <mailbox-id>
```

Examples: [CLI](/docs/api/reference/list-mailbox-scheduled-messages.cli.md) · [MCP](/docs/api/reference/list-mailbox-scheduled-messages.mcp.md) · [cURL](/docs/api/reference/list-mailbox-scheduled-messages.curl.md)

## Example response `200`

```json
{
  "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"
}
```

## Path parameters

- `mailbox_id` (string, required): Mailbox that owns the scheduled send.

## Query parameters

- `thread_id` (string, optional): Filter by the reserved conversation identifier.
- `status` (string, optional)

  Filter by scheduling state.

  Possible values: `scheduled`, `sending`, `sent`, `failed`, `canceled`
- `limit` (integer, optional): Maximum number of items to return per page.
- `starting_after` (string, optional): Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.
- `ending_before` (string, optional): 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.

## Header parameters

- `X-Workspace-Id` (string, optional): Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.
- `X-Organization-Id` (string, optional): Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

## Response body

- `data` (array of object, required)
- `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.
- `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

- [Should I use a Bird SDK or call the API directly?](/explained/platform/should-i-use-an-sdk-or-call-the-api-directly) (answer)
- [Build your first integration](/learn/paths/integration) (course)
- [Send your first email](/docs/get-started/send-your-first-email) (docs)

[Get an implementation brief](/learn/workspace?topic=api-basics)