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

# List mailboxes

`GET /api/v1/mailboxes`

## Request

- Base URL: `https://api.aerosend.io`
- URL: `https://api.aerosend.io/api/v1/mailboxes`
- Auth: API key in header `X-API-Key`

Returns a paginated list of mailboxes for the authenticated client.

## Filtering
- **search**: Filter by email address (partial match)
- **status**: Filter by status. Valid values: `active`, `inactive`, `pending`, `in_progress`
- **domain_id**: Filter by specific domain
- **tag_ids**: Filter by tag IDs (comma-separated)

## Sorting
- **sort**: Order by creation date. Valid values: `latest` or `oldest` (default: `latest`)
- Invalid sort values will be rejected with a validation error

## Tags
- **include_tags**: Include tags in response (default: `false`)
- Tag filtering via `tag_ids` works regardless of the `include_tags` flag
- When `include_tags=false`, tags are not included in the response but filtering still applies

## Credentials
Set `include_credentials=true` to include SMTP and IMAP connection details.
**Note**: Credentials are not cached for security reasons.

## SMTP/IMAP Configuration
When credentials are requested:
- **SMTP**: smtp.topdeliverabilityninja.com:587 (TLS)
- **IMAP**: Retrieved from domain's mail server (SSL, port 993)

## Query parameters

- `offset` integer
- `limit` integer
- `sort` 'latest' | 'oldest'
- `search` string
- `status` 'active' | 'inactive' | 'pending' | 'in_progress'
- `domain_id` integer
- `tag_ids` integer[]
- `include_credentials` boolean
- `include_tags` boolean

## Response `200`

Successfully retrieved mailboxes

- MailboxListResponse
  - `success` boolean: Success flag
  - `data` Mailbox[]: List of items
    - `id` integer: Mailbox ID
    - `email` string: Email address
    - `first_name` string: First name
    - `last_name` string: Last name
    - `status` string: Mailbox status
    - `created_at` string: Creation timestamp
    - `updated_at` string: Last modification timestamp
    - `domain_id` integer: Domain ID this mailbox belongs to
    - `domain` string: Domain name
    - `credentials` Credentials: SMTP and IMAP credentials for mailbox
      - `smtp` ServerConfig: Mail server configuration
        - `host` string: Server hostname
        - `port` integer: Server port
        - `username` string: Username (email address)
        - `password` string: Password for authentication
        - `security` string: Security protocol
      - `imap` ServerConfig: Mail server configuration
        - `host` string: Server hostname
        - `port` integer: Server port
        - `username` string: Username (email address)
        - `password` string: Password for authentication
        - `security` string: Security protocol
    - `tags` Tag[]: Tags assigned to this mailbox
      - `id` integer: Tag ID
      - `name` string: Normalized tag name
      - `display_name` string: Display name
      - `color` string: Tag color in hex
      - `status` string: Tag status
      - `domain_count` integer: Number of domains with this tag
      - `mailbox_count` integer: Number of mailboxes with this tag
      - `created_at` string: Creation timestamp
      - `updated_at` string: Last update timestamp
  - `pagination` Pagination: Pagination metadata
    - `offset` integer: Current offset
    - `limit` integer: Items per page
    - `total` integer: Total number of items
    - `has_more` boolean: Whether there are more items
  - `timestamp` string: Response timestamp

## Other responses

- `400`: Invalid request parameters
- `401`: Unauthorized - Invalid or expired API key
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/aerosend/apis/aerosend-developer-api.md) · [All operations](https://skmtc.dev/aerosend/apis/aerosend-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aerosend/apis/aerosend-developer-api/revisions/9828eeb89b1f?raw)