---
title: "Read a mailbox"
method: GET
path: "/v1/mailboxes/{mailbox_id}"
tags: ["Mailboxes"]
---

# Read a mailbox

`GET /v1/mailboxes/{mailbox_id}`

## Request

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

Reading never changes the mailbox. Read address settings, emails and files through their own endpoints.

## Path parameters

- `mailbox_id` string, required

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

## Response `200`

Success

- object
  - `success` true, required
  - `data` object, required
    - `mailbox` Mailbox, required: A mailbox: one receiving address with private file storage. Label it as title (email.address), or by email.address alone when title is null. Use id in API calls.
      - `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.

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