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

# List project mailboxes

`GET /mailboxes/v1`

## Request

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

Lists all mailboxes belonging to the project, the current default outbound/auth sender settings, and setup actions when multiple active mailboxes need explicit defaults.

## Response `200`

Mailbox list

- MailboxListResponse
  - `mailboxes` Mailbox[]
    - `mailbox_id` string
    - `address` string: Current effective primary sender/recipient address. Uses ProjectDomain effective custom mailbox state only; otherwise uses the managed project mail host.
    - `managed_address` string: Stable Run402-managed address for this mailbox. Remains receive-compatible permanently, including after custom-domain activation.
    - `slug` string: Project-scoped email local part.
    - `project_id` string: Run402 project ID. Public IDs are not UUIDs.
    - `status` 'active' | 'suspended' | 'tombstoned' | 'deleted'
    - `footer_policy` 'run402_transparency' | 'none': Configured outbound footer policy for this mailbox. Defaults to run402_transparency.
    - `effective_footer_policy` 'run402_transparency' | 'none': Footer policy that will be applied to sends after tier gating. Prototype-tier projects are always run402_transparency.
    - `footer_policy_locked_reason` 'prototype_tier', nullable: Null when configurable; prototype_tier when the project tier forces the Run402 transparency footer.
    - `is_default_outbound` boolean: True when this mailbox is the project's default sender for implicit app/helper email sends.
    - `is_auth_sender` boolean: True when this mailbox is the configured sender for auth magic-link and invite emails.
    - `can_send` boolean: True when the mailbox is active and can currently send outbound email.
    - `send_blocked_reason` string, nullable: Machine-readable reason when can_send is false, such as mailbox_suspended or mailbox_deleted.
    - `domain_kind` 'managed' | 'custom': Whether the primary address currently uses the Run402-managed project mail host or ProjectDomain effective custom mailbox state.
    - `address_domain` string: Domain portion of the current primary address.
    - `managed_domain` string: Stable Run402-managed project mail domain.
    - `custom_domain_ready` boolean: True when ProjectDomain effective state has custom mailbox addresses active.
    - `can_receive` boolean: True when the mailbox has an inbound route for its current address namespace.
    - `sends_today` integer
    - `unique_recipients` integer
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `addresses` object: Structured primary/managed/custom address state.
      - `primary` object
      - `managed` object
      - `custom` object, nullable
    - `inbound_policy` 'reply_only' | 'allowlist' | 'open': First-contact inbound policy. reply_only is the default and preserves the sent-history gate.
    - `inbound_allowlist` string[]: Case-insensitive allowlist entries for inbound_policy=allowlist. Supports exact addresses and *@domain wildcards.
    - `suspended_reason` string, nullable
    - `suspended_at` string, date-time, nullable
    - `suspended_evidence` object, nullable
    - `next_action` NextAction
      - `type` string, required: Advisory machine-readable action type such as retry, authenticate, submit_payment, fund_wallet, renew_tier, check_usage, resume_deploy, edit_request, edit_migration, contact_support, upgrade_client, poll (poll the project events feed — appended when the envelope carries a correlated_platform_incident), or hand_to_member (on a commit/promote response that just activated a public site: show the human urls.site and urls.console, relay Run402's offer to promote the build on @run402com, and ask yes or no — see `credited_as` below).
      - `method` string
      - `path` string
      - `auth` string
      - `why` string
      - `credited_as` string, nullable: `hand_to_member` only. The caller's own live presence name in the project's default room, else that room's most recently active live presence, else `null` — in which case `why` tells the agent that joining the room with a name (`run402 rooms join --name ...`) is how the promotion credits it.
      - `body` object: `hand_to_member` only. A ready-to-send `POST /feedback/v1` template: `{ project_id, message: "promote: yes", handle? }`.
  - `mailbox_settings` MailboxSettings
    - `default_outbound_mailbox_id` string, nullable: Mailbox used by implicit app/function helper sends.
    - `auth_sender_mailbox_id` string, nullable: Mailbox used by hosted/API magic-link and invite emails.
  - `next_actions` NextAction[]: Repair actions, such as PATCH /mailboxes/v1/settings, when defaults are missing or unsafe.
    - `type` string, required: Advisory machine-readable action type such as retry, authenticate, submit_payment, fund_wallet, renew_tier, check_usage, resume_deploy, edit_request, edit_migration, contact_support, upgrade_client, poll (poll the project events feed — appended when the envelope carries a correlated_platform_incident), or hand_to_member (on a commit/promote response that just activated a public site: show the human urls.site and urls.console, relay Run402's offer to promote the build on @run402com, and ask yes or no — see `credited_as` below).
    - `method` string
    - `path` string
    - `auth` string
    - `why` string
    - `credited_as` string, nullable: `hand_to_member` only. The caller's own live presence name in the project's default room, else that room's most recently active live presence, else `null` — in which case `why` tells the agent that joining the room with a name (`run402 rooms join --name ...`) is how the promotion credits it.
    - `body` object: `hand_to_member` only. A ready-to-send `POST /feedback/v1` template: `{ project_id, message: "promote: yes", handle? }`.

## Other responses

- `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope.

---

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