---
title: "Get a scheduled mailbox send"
canonical: "https://bird.com/docs/api/reference/get-mailbox-scheduled-message"
---

# Get a scheduled mailbox send

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

Read the scheduled send and its dispatch, failure or cancellation state. The actual message enters the conversation only at dispatch.

## 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 get <mailbox-id> <scheduled-message-id>
```

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

## Example response `200`

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

## Path parameters

- `mailbox_id` (string, required): Mailbox that owns the scheduled send.
- `scheduled_message_id` (string, required): Scheduled send identifier from scheduled_message_id in the acceptance response.

## 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

- `id` (string, required): Scheduled send identifier.
- `mailbox_id` (string, required): Mailbox that owns the send.
- `thread_id` (string, required): Reserved conversation identifier. A new compose does not create the conversation until dispatch.
- `message_id` (string): Actual message identifier once handed to the send pipeline.
- `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`
- `scheduled_at` (string, required): Scheduled at.
- `cancel_on_reply` (boolean, required): Whether an inbound message cancels this send before dispatch is claimed.
- `failure_reason` (string): Why dispatch failed.
- `cancellation_reason` (string): Why canceled; replied means new inbound mail canceled an opted-in schedule.
- `subject` (string, required): Frozen subject.
- `snippet` (string, required): Plain-text preview of the frozen message.
- `recipients` (array of string, required): Visible recipients (To and Cc). Bcc addresses remain only in the frozen send payload.
- `created_by` (object, required): Authenticated caller that scheduled the send.
- `created_by.id` (string, required): Actor identifier.
- `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`
- `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.
- `created_at` (string, required)
- `updated_at` (string, required)

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