Skip to content

List Mailboxes

GET
/mailboxes

List sending mailboxes the authenticated user can access in this org.

Backs the MCP “pick a mailbox before launching a campaign” flow.

Sources from the canonical mailboxes table (NOT the ai_inbox_email_cron_jobs table the FE picker previously used — that table is the AI-inbox sync state, not the source of truth for which mailboxes exist). See .claude/agent-context/mailbox-picker-sources-cron-table.md.

Tenant scope: mailboxes lives in the per-org schema (NOT public — the earlier version of this comment was wrong; see select to_regclass('public.mailboxes') returning null vs. the per-org row count). Binding the session to schema=<org> IS the tenant boundary; no further org-filter predicate is needed.

Per-row RBAC (ENFORCE_MAILBOX_PERMISSIONS soak flag) is NOT enforced here yet — Phase 3b on issue #7180 — keeping symmetry with the FE picker. When that flag flips on, this endpoint will adopt the scope filter alongside the cdp/mailboxes/fetch surface.

Historical bug (fixed 2026-05-22): the previous implementation appended (t.org_id = :org_id OR m.created_by = :user_id) to the WHERE. Both halves silently matched zero rows in prod — mailboxes.team_id is NULL on every row (no team pinning) and mailboxes.created_by stores email strings, not propelauth UUIDs. Result: the endpoint returned an empty list for every caller. Dropping the predicate restores the correct per-org listing; tenant isolation comes from the schema bind.

Authorizations

Parameters

Query Parameters

limit
integer
default: 100 >= 1 <= 500
include_archived

Include archived mailboxes

boolean

Include archived mailboxes

connection_status
Any of:
string

Filter by connection_status (active|paused|disconnected|expired|…)

Header Parameters

X-Target-Org-Id
Any of:
string

Responses

200

Successful Response

object
data
required
Array<object>
object
key
additional properties
any
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
notes
Any of:
Array<string>
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer
total_available
Any of:
integer
total_is_lower_bound
Any of:
boolean

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string