---
title: "List scheduled messages"
method: GET
path: "/scheduled-messages"
tags: ["Messages"]
---

# List scheduled messages

`GET /scheduled-messages`

## Request

- Base URL: `https://shipmail.to/api/v1`
- URL: `https://shipmail.to/api/v1/scheduled-messages`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://shipmail.to/api/auth/oauth2/authorize`, token URL `https://shipmail.to/api/auth/oauth2/token`)

List future scheduled messages. Transient undo holds are omitted unless include_held is true.

## Query parameters

- `include_held` boolean
- `search` string
- `limit` integer

## Headers

- `X-Shipmail-Organization` string

## Response `200`

Scheduled message list.

- ScheduledMessageList
  - `object` 'scheduled_message_list', required
  - `data` ScheduledMessage[], required
    - `object` 'scheduled_message', required
    - `id` string, required: Tracked message ID used by scheduled-message endpoints.
    - `scheduled_message_id` string, required: Internal scheduled lifecycle row ID.
    - `status` 'scheduled' | 'settling': `scheduled` while the message waits for its send time. `settling` when a send attempt may already have gone out and Shipmail is checking whether it did: the message cannot be updated or cancelled until that resolves, and it then leaves the scheduled list as sent, or returns as `scheduled`. Treat a value you do not recognize as not editable. Absent from responses of servers that predate the field; treat absence as `scheduled`.
    - `kind` 'scheduled' | 'undo', required
    - `mailbox_id` string, required
    - `mailbox_address` string, email, required
    - `from_address` string, email, required
    - `identity_id` string, required
    - `mode` 'live' | 'test', required: The API-key data plane that owns this resource. Test resources are isolated from live delivery, quota, suppression, and reputation.
    - `subject` string, required
    - `to` Recipient[], required
      - union: Email recipient. Either an object with address and optional name, or a string.
        - object
          - `address` string, email, required: Email address.
          - `name` string, nullable: Display name (optional).
        - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
    - `cc` Recipient[], required
      - union: Email recipient. Either an object with address and optional name, or a string.
        - object
          - `address` string, email, required: Email address.
          - `name` string, nullable: Display name (optional).
        - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
    - `bcc` Recipient[], required
      - union: Email recipient. Either an object with address and optional name, or a string.
        - object
          - `address` string, email, required: Email address.
          - `name` string, nullable: Display name (optional).
        - string: Email address as a string. Accepts plain address ("user@example.com") or display name format ("Jane Doe <user@example.com>").
    - `attachments` AttachmentMetadata[], required
      - `filename` string, required
      - `size` integer, required: Size in bytes.
      - `content_type` string, required
    - `scheduled_at` string, date-time, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `last_error` string, nullable, required
    - `draft_email_id` string
    - `from_name` string
    - `text` string
    - `html` string
    - `in_reply_to` string, nullable
    - `references` string[]
    - `uploaded_attachments` object[]
      - `blob_id` string, required
      - `filename` string, required
      - `content_type` string, required
      - `size` integer, required
  - `total` integer, required

## Other responses

- `422`: Validation failed.
- `429`: Rate limit exceeded.

---

[API](https://skmtc.dev/shipmail/apis/shipmail-api.md) · [All operations](https://skmtc.dev/shipmail/apis/shipmail-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shipmail/apis/shipmail-api/revisions/2c23e59d7e30?raw)