---
title: "List inboxes"
method: GET
path: "/v1/inboxes"
tags: ["inboxes"]
---

# List inboxes

`GET /v1/inboxes`

## Request

- Base URL: `https://api.openmail.sh`
- URL: `https://api.openmail.sh/v1/inboxes`
- Auth: HTTP bearer

List all inboxes for your account. Supports pagination.

## Query parameters

- `limit` integer
- `offset` integer
- `podId` string

## Response `200`

List of inboxes

- object: List of inboxes
  - `data` Inbox[]
    - `id` string: OpenMail inbox ID
    - `podId` string: ID of the pod this inbox belongs to. Inboxes created without an explicit pod land in your account's default pod.
    - `address` string, email: Full email address
    - `displayName` string, nullable: Sender display name
    - `webhookUrl` string, nullable: URL that receives signed webhook events for this inbox, if set. Overrides the account-level webhook for this inbox only.
    - `webhookSecret` string, nullable: Signing secret for this inbox's webhook. Only present in the response when the secret is generated or rotated (on create, on first setting a webhook URL, or via the rotate-secret endpoint) — it is never returned afterward.
    - `forwardTo` string, nullable: Address that receives copies of this inbox's inbound mail, if set.
    - `forwardWhen` 'always' | 'needs_human' | 'webhook_failed' | 'null', nullable: Which inbound mail is forwarded. Null when forwarding is not set.
    - `forwardStatus` 'pending' | 'active' | 'disabled' | 'null', nullable: `pending` until the address confirms via the emailed link (members of your organisation are confirmed at once); `active` once copies are flowing; `disabled` when forwarding paused itself after the address hard-bounced repeatedly or complained — set `forwardTo` again to resume. Null when forwarding is not set.
    - `createdAt` string, date-time
  - `total` integer

## Other responses

- `401`: Missing, invalid, or expired API key

---

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