# List scheduled sends

Returns scheduled email sends for this mailbox. By default lists pending sends; pass state to view historical or completed scheduled sends.

## `GET /api/v1/mailboxes/{mailboxId}/scheduled`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Query parameters

- `state` ("pending" | "releasing" | "sent" | "failed" | "canceled") — Filter by state ('pending', 'releasing', 'sent', 'failed', 'canceled')
- `limit` (integer, ≥ 1, ≤ 200) — Page size (default 100)
- `cursor` (string) — Opaque page cursor from a previous response

### Responses

**200** — List of scheduled sends

`application/json` → object

- `scheduled` (ScheduledSend[], required)
  - `attempts` (integer, required) — Number of delivery attempts made
  - `createdAt` (integer <int64>, required) — Creation timestamp in epoch seconds
  - `deferrals` (integer, required) — Number of deferrals encountered
  - `deliveryId` (string, required) — Idempotency key for this submission
  - `error` (string | null, required) — Error reason if sending failed or was canceled, or null
  - `finishedAt` (integer | null, required) — Completion timestamp in epoch seconds, or null if pending
  - `messageId` (string, required) — Draft message ULID scheduled for sending
  - `recipients` (string[], required) — List of target recipient email addresses
  - `releaseAt` (integer <int64>, required) — Actual scheduled release time in epoch seconds
  - `result` (array | null, required) — Per-recipient delivery outcomes, or null if pending
  - `scheduleId` (string, required) — Scheduled send ULID
  - `sendAt` (integer <int64>, required) — Requested send time in epoch seconds
  - `state` ("pending" | "releasing" | "sent" | "failed" | "canceled", required) — Current scheduling status
  - `threadId` (string | null, required) — Associated conversation thread ID, or null
- `nextCursor` (string) — Opaque cursor for the next page; absent on the last page

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible

`application/json` → ErrorBody

**503** — temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

### Example request

```bash
curl -X GET 'https://api.open.email/api/v1/mailboxes/{mailboxId}/scheduled' \
  -H 'Authorization: Bearer oek_…'
```

## TypeScript SDK

[`openemail.scheduled.list`](/docs/sdks/typescript/scheduled/list)

```ts
for await (const scheduledSend of openemail.scheduled.list(mailboxId)) {
  // every item of every page (await the call instead for one page)
}
```
