Mailboxes

List mailboxes

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)
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

Query parameters

offsetinteger

Number of items to skip

limitinteger

Maximum items to return (1-100)

sort'latest' | 'oldest'

Sort order

searchstring

Search by email address

status'active' | 'inactive' | 'pending' | 'in_progress'

Filter by status. Valid values: active, inactive, pending, in_progress

domain_idinteger

Filter by domain ID

tag_idsinteger[]

Filter by tag IDs (comma-separated)

include_credentialsboolean

Include SMTP/IMAP credentials

include_tagsboolean

Include tags in response. Tag filtering still works regardless of this flag.

Response

Successfully retrieved mailboxes

successboolean

Success flag

timestampstring

Response timestamp

Example response

{
  "success": true,
  "data": [
    {
      "id": 456,
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "status": "active",
      "created_at": "2025-12-01T10:30:00Z",
      "updated_at": "2025-12-10T15:45:00Z",
      "domain_id": 123,
      "domain": "example.com",
      "credentials": {
        "smtp": {
          "host": "smtp.topdeliverabilityninja.com",
          "port": 587,
          "username": "john@example.com",
          "security": "TLS"
        },
        "imap": {
          "host": "smtp.topdeliverabilityninja.com",
          "port": 587,
          "username": "john@example.com",
          "security": "TLS"
        }
      },
      "tags": [
        {
          "id": 789,
          "name": "client-abc",
          "display_name": "Client ABC",
          "color": "#000369",
          "status": "active",
          "domain_count": 10,
          "mailbox_count": 45,
          "created_at": "2025-12-01T10:30:00Z",
          "updated_at": "2025-12-10T15:45:00Z"
        }
      ]
    }
  ],
  "pagination": {
    "limit": 20,
    "total": 150,
    "has_more": true
  },
  "timestamp": "2025-12-14T10:30:00Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.