---
title: "List mailboxes"
method: GET
path: "/v1/accounts"
tags: ["Email Accounts"]
---

# List mailboxes

`GET /v1/accounts`

## Request

- Base URL: `https://api.mailbeast.ai`
- URL: `https://api.mailbeast.ai/v1/accounts`
- Auth: HTTP bearer

List your mailboxes, newest first, with stable cursor pagination. Filter by `status` or `tags` (any-of), or pass `email` to look one mailbox up by its address instead of by `id`.

Requires one of the following scopes: `accounts:read`, `accounts:all`, `all:read`, `all:all`.

## Query parameters

- `cursor` string
- `limit` number
- `status` 'active' | 'inactive' | 'checking' | 'revoked' | 'failed'
- `email` string
- `tags` string

## Response `200`

- AccountListApiResponseDto
  - `data` AccountApiDto[], required
    - `id` string, uuid, required
    - `emailAddress` string, required
    - `firstName` string, nullable, required
    - `lastName` string, nullable, required
    - `displayName` string, nullable, required
    - `provider` string, required: How the mailbox is connected: `custom` for any SMTP/IMAP mailbox (including Gmail/Outlook connected with an app password), or `google` / `microsoft` for a native OAuth connection.
    - `status` 'active' | 'inactive' | 'checking' | 'revoked' | 'failed', required: Current state. `active` - sending. `inactive` - paused by you (or connected but not verified yet); nothing re-activates it on its own, call `resume`. `checking` - being verified. `failed` - we stopped it after repeated failures; see `statusMessage` for the provider’s reason, and `resume` re-checks it. `revoked` - the OAuth grant is gone; reconnect it.
    - `maxEmailsPerDay` number, required: Daily CAMPAIGN send cap. Warmup is budgeted separately (`warmup.maxPerDay`).
    - `sendingGapMinutes` number, required: Minimum minutes between two sends from this mailbox, across all campaigns.
    - `campaignSlowRamp` boolean, required: Ramp campaign volume up gradually when the mailbox joins a campaign.
    - `replyToAddress` string, nullable, required: Where replies are sent, when it differs from the mailbox address.
    - `signature` string, nullable, required: HTML signature appended to outgoing emails.
    - `bcc` string, nullable, required
    - `automationLanguage` string, required: ISO 639-1 language for auto-generated content.
    - `warmup` AccountWarmupSummaryDto, required
      - `enabled` boolean, required
      - `strategy` 'standard' | 'aggressive' | 'custom', required: Fixed preset (`standard` / `aggressive`), or `custom` to run on the tuning values below.
      - `maxPerDay` number, required: Warmup emails per day. Separate from the campaign cap. Honoured while ramping up on `custom` only; from the maintaining stage on it caps every strategy.
      - `replyRatePercentage` number, required: `custom` strategy only; the presets use their own reply rate.
      - `rampupEnabled` boolean, required: `custom` strategy only.
      - `dailyRampup` number, required: Emails added per day while ramping. Read only when `rampupEnabled` is true. `custom` strategy only.
      - `randomizer` number, required: Percent of warmup sends randomly skipped each day. `custom` strategy only.
      - `skipWeekends` boolean, required
      - `timezone` string, required
      - `trackingEnabled` boolean, required
      - `phase` 'warming_up' | 'maintaining' | 'active_with_campaigns', nullable, required: Where the mailbox is in its warmup lifecycle. Null until warmup starts.
      - `startedAt` string, date-time, nullable, required: When warmup began. Null if it never has.
      - `poolAccess` 'free' | 'standard' | 'premium' | 'ultra', required: Quality of the warmup pool this mailbox converses with. Set by your plan, read-only.
    - `tracking` AccountTrackingSummaryDto, required
      - `domainId` string, uuid, nullable, required: Tracking domain in use. Null means opens and clicks are not tracked for this mailbox.
    - `statusMessage` AccountStatusMessageDto, required
      - `code` string, nullable, required: Transport/protocol class of the failure.
      - `command` string, nullable, required: The SMTP command that failed.
      - `responseCode` number, nullable, required: Numeric SMTP status returned by the provider.
      - `response` string, nullable, required: The provider’s raw response line.
      - `message` string, required: The error text.
      - `occurredAt` string, date-time, required: When the failure happened.
    - `tags` TagApiDto[], required: Tags on this mailbox. Create and delete them in the dashboard - here they are read, and you can filter the list by them with `?tags=`.
      - `id` string, uuid, required
      - `name` string, required
      - `color` string, nullable, required: Hex colour shown in the dashboard.
    - `healthScore` number, required: Deliverability health score, from 0 to 100.
    - `smtp` AccountSmtpDto, required
      - `host` string, nullable, required
      - `port` number, nullable, required
      - `username` string, nullable, required
    - `imap` AccountImapDto, required
      - `host` string, nullable, required
      - `port` number, nullable, required
      - `username` string, nullable, required
    - `verification` AccountVerificationSummaryDto, required
      - `overallStatus` 'pending' | 'verified' | 'failed', required: Overall outcome of the mailbox checks.
      - `smtp` 'active' | 'inactive' | 'checking' | 'revoked' | 'failed', required: Sending status of the mailbox.
      - `imap` 'not_checked' | 'pending' | 'in_progress' | 'verified' | 'failed' | 'check_unavailable' | 'skipped', required: IMAP connection status.
      - `dns` AccountDnsDto, required
        - `mx` 'not_checked' | 'pending' | 'in_progress' | 'verified' | 'failed' | 'check_unavailable' | 'skipped', required
        - `spf` 'not_checked' | 'pending' | 'in_progress' | 'verified' | 'failed' | 'check_unavailable' | 'skipped', required
        - `dkim` 'not_checked' | 'pending' | 'in_progress' | 'verified' | 'failed' | 'check_unavailable' | 'skipped', required
        - `dmarc` 'not_checked' | 'pending' | 'in_progress' | 'verified' | 'failed' | 'check_unavailable' | 'skipped', required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `meta` AccountListMetaDto, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required: Pass as `?cursor=` for the next page; `null` on the last page.

## Other responses

- `400`: The request body or parameters failed validation.
- `401`: Missing or invalid API key.
- `403`: The key lacks a required scope, or the plan does not include API access.
- `429`: Rate limit exceeded - retry after the interval in the Retry-After header.

---

[API](https://skmtc.dev/mailbeast/apis/mailbeast-public-api.md) · [All operations](https://skmtc.dev/mailbeast/apis/mailbeast-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mailbeast/apis/mailbeast-public-api/revisions/6440ce0738a4?raw)