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

# List mailboxes

`GET /v1/mailboxes`

## Request

- Base URL: `https://api.revdoku.com`
- URL: `https://api.revdoku.com/v1/mailboxes`
- Auth: HTTP bearer

Lists active mailboxes by default, newest first. Counts and pages cover only mailboxes this credential can access. Reads no email content.

## Query parameters

- `account_id` string
- `reason` string, nullable: Optional purpose for this action. AI agents should explain intentional reads and changes when known; omit when unknown. Do not include secrets, file contents, or transcripts.
- `status` 'active' | 'archived' | 'all'
- `q` string
- `limit` integer
- `cursor` string

## Response `200`

Success

- object
  - `success` true, required
  - `data` MailboxList, required
    - `mailboxes` Mailbox[], required
      - `id` string, required
      - `account_id` string, required
      - `title` string, nullable: Mailbox title chosen by people. Defaults to the email username given at creation. Null when unset or when the caller cannot see email.address.
      - `description` string, nullable
      - `metadata` object: Your application data. PATCH replaces the whole object.
      - `metadata_version` string, required: Send as expected_metadata_version on PATCH. Changes only when description or metadata changes.
      - `email` MailboxEmail, required: Receiving and sending state of a mailbox. Counts read the email index without reading content.
        - `address` string: Primary address. Present when the credential has write access to the mailbox. Show it after the title.
        - `message_count` integer, nullable, required: Emails currently stored. Null while the email index is being prepared.
        - `unread_count` integer, nullable, required: Stored emails with shared unread status. Null while the email index is being prepared.
        - `last_received_at` string, date-time, nullable, required: Receipt time of the latest saved email; null before the first email.
        - `receiving_enabled` boolean, required: Whether the mailbox can receive email now.
        - `blocked_reason` string: Why receiving is unavailable. Omitted when receiving_enabled is true.
        - `sending_enabled` boolean, required: Whether the mailbox can send replies now.
        - `sending_blocked_reason` string: Why sending is unavailable. Omitted when sending_enabled is true.
      - `archived` boolean, required
      - `archived_at` string, date-time, nullable
      - `lock` MailboxLock
        - `locked` boolean, required
        - `locked_until` string, date-time
        - `kind` string: For example mailbox_delete while a permanent delete runs.
        - `message` string
        - `progress` object
        - `locked_by` FileActor
          - `id` string
          - `name` string
          - `email` string
        - `locked_by_api_key` FileKey
          - `id` string
          - `label` string
          - `token_type` string
      - `storage_bytes` integer
      - `files_count` integer: Current files, including stored emails and attachments.
      - `version_id` string, nullable, required: Current mailbox file-tree version. Send as expected_mailbox_version on file writes to detect concurrent changes.
      - `version_number` integer, required
      - `created_at` string, date-time, nullable
      - `updated_at` string, date-time, nullable
      - `dashboard_url` string, uri: Opens the mailbox for signed-in members. It does not grant access.
      - `archive` MailboxAction, required
        - `allowed` boolean, required
        - `blocked_reason` string
        - `required_action` string
        - `confirmation` string: Delete only: send this value as confirmation in DELETE /v1/mailboxes/{mailbox_id} after the user confirms.
      - `unarchive` MailboxAction, required
        - `allowed` boolean, required
        - `blocked_reason` string
        - `required_action` string
        - `confirmation` string: Delete only: send this value as confirmation in DELETE /v1/mailboxes/{mailbox_id} after the user confirms.
      - `delete` MailboxAction, required
        - `allowed` boolean, required
        - `blocked_reason` string
        - `required_action` string
        - `confirmation` string: Delete only: send this value as confirmation in DELETE /v1/mailboxes/{mailbox_id} after the user confirms.
    - `counts` MailboxCounts, required: Exact authorized mailbox totals after query filtering, before status filtering and pagination.
      - `active` integer, required
      - `archived` integer, required
      - `total` integer, required
    - `pagination` Pagination, required: One page of a list. Request the next page with cursor=next_cursor and the same filters. Cursors are opaque strings: do not build or decode them.
      - `limit` integer, required
      - `has_more` boolean, required: True when another page exists.
      - `next_cursor` string, nullable, required: Cursor for the next page; null on the last page. Email lists always return a cursor so that you can poll for new mail.

## Other responses

- `default`: Request failed. See error.code. Any 429 or 503 response with Retry-After (for example 503 EMAIL_LABELING_PENDING or 503 EMAIL_INDEX_BUILDING): wait that many seconds, then try the read again. 429 EMAIL_SEND_RATE_LIMITED has no Retry-After. Never retry EMAIL_LOOP_DETECTED.

---

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