> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puffle.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# List Inboxes
> Return every inbox owned by the caller, newest first.
**CLI:**
```bash theme={null}
puffle email account
```
## Overview
Return every inbox owned by the caller, newest first. Each row is joined with its backing `email_domains` entry so clients can render domain status (`verified`, `pending`, …) without a second round-trip. Warmup analytics (`stat_warmup_score`, `health_score`, daily sends) are NOT included here — fetch them separately via `GET /api/email/accounts/warmup-analytics`.
This operation shares the URL path `/api/email/accounts` with other verbs. See [the sibling page](/api-reference/senders/create-email-account) for related operations on the same resource.
## OpenAPI
````yaml get /api/email/accounts
openapi: 3.0.3
info:
title: Puffle API
version: 1.0.0
description: >-
HTTP API for the Puffle GTM platform - Feed and Lead Finder search
preparation, campaign-backed Outbound execution, Puffle Agent runs, sender
management, and Unibox reply workflows. Designed for operation by both
humans and autonomous AI agents. Agents should start at the [Agent
Playbook](/guides/agent-playbook) which prescribes a workspace-context check
(`GET /api/context`) and core user journeys with exact call ordering.
contact:
name: Puffle Support
url: https://puffle.ai
servers:
- url: https://app.puffle.ai
description: Production
security:
- bearerAuth: []
tags:
- name: Campaigns
description: >-
Campaign-backed Outbound execution. These endpoints manage draft,
launching, active, paused, and completed Outbound runs with sequence
nodes, contacts, and sender accounts.
- name: Accounts
description: Signed-in user account, settings, and workspace context endpoints.
- name: Billing
description: Billing customer portal and account billing endpoints.
- name: Senders
description: >-
Connected sender accounts, email inboxes, sending domains, DNS
verification, warmup, and sender capacity.
- name: Socials
description: >-
Read connected LinkedIn and X accounts, review current and archived posts,
and reconcile publication status. Creating, editing, scheduling,
publishing, OAuth connection, analytics, and mentions remain
dashboard-managed workflows and are not part of the public Bearer-token
API.
paths:
/api/email/accounts:
get:
tags:
- Senders
summary: List Inboxes
description: >-
Return every email sender account owned by the caller, newest first.
Each row is joined with its backing `email_domains` entry so clients can
render domain status (`verified`, `pending`, …) without a second
round-trip. Warmup analytics (`stat_warmup_score`, `health_score`, daily
sends) are NOT included here — fetch them separately via `GET
/api/email/accounts/warmup-analytics`.
operationId: listEmailAccounts
parameters: []
responses:
'200':
description: >-
Array of email accounts. Empty array is a valid response for users
who have not created any inboxes.
content:
application/json:
schema:
type: object
properties:
accounts:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: Primary key in the `accounts` table.
user_id:
type: string
format: uuid
type:
type: string
enum:
- email
domain_id:
description: >-
FK to `email_domains.id` — the custom sending
domain.
type: string
format: uuid
nullable: true
email_address:
description: >-
Full inbox address, e.g. `sarah@acme.com`. Derived
from `@` at creation.
type: string
format: email
nullable: true
agentmail_inbox_id:
description: >-
Backing inbox identifier. Used internally for
send/reply routing and inbound webhook dedupe.
type: string
nullable: true
instantly_account_id:
description: >-
Warmup account identifier. Present while the account
is registered for warmup analytics; legacy field.
type: string
nullable: true
status:
type: string
enum:
- pending
- warming
- active
- disconnected
description: >-
Account readiness. Newly-created inboxes are
`warming` (warmup running) or `pending` (warmup
failed at creation). `active` accounts can send
campaign emails.
warmup_status:
description: >-
Warmup lifecycle. Campaigns will NOT send from
accounts with `warming` status unless an admin
override is enabled.
type: string
enum:
- not_started
- warming
- completed
- disabled
nullable: true
is_default_sender:
type: boolean
description: >-
Whether this inbox is the user's default email
sender. New accounts get one default warmed sender
during onboarding.
display_name:
type: string
nullable: true
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
signature:
description: >-
Per-account email signature. Synced before PATCH
completes; newlines become `
` for HTML
rendering.
type: string
nullable: true
instantly_tag_id:
type: string
nullable: true
instantly_warmup_tag_id:
type: string
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
nullable: true
email_domains:
type: object
properties:
id:
type: string
format: uuid
domain:
type: string
status:
type: string
enum:
- pending
- verifying
- verified
- failed
description: >-
Lifecycle status of the backing custom domain.
Only `verified` domains can be used to create
new inboxes.
required:
- id
- domain
- status
additionalProperties: false
description: >-
Compact domain reference joined onto each account
row so clients can show which custom sending domain
an inbox belongs to without a second round-trip.
nullable: true
required:
- id
- user_id
- type
- domain_id
- email_address
- agentmail_inbox_id
- instantly_account_id
- status
- warmup_status
- is_default_sender
- display_name
- first_name
- last_name
- signature
- instantly_tag_id
- instantly_warmup_tag_id
- created_at
- updated_at
- email_domains
additionalProperties: false
description: >-
A Puffle-managed email sending inbox. Each account row
maps to one backing inbox and optional warmup
registration.
required:
- accounts
additionalProperties: false
'401':
description: Missing or invalid Bearer token.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
additionalProperties: false
'500':
description: >-
Database read failed. The underlying Supabase error message is
forwarded in `error`.
content:
application/json:
schema:
type: object
properties:
error:
type: string
required:
- error
additionalProperties: false
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: pk_live_...
````