---
title: "List domains"
method: GET
path: "/api/v1/domains"
tags: ["Domains"]
---

# List domains

`GET /api/v1/domains`

## Request

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

Returns a paginated list of domains for the authenticated client.

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

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

## Pagination
- **offset**: Number of items to skip (default: 0)
- **limit**: Maximum items to return (default: 20, max: 100)

## Response
Each domain includes:
- Basic domain information
- Active nameservers
- DNS provider details
- Associated tags (if requested with `include_tags=true`)
- Mailboxes (if requested with `include_mailboxes=true`)

**Note**: 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.

## Query parameters

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

## Response `200`

Successfully retrieved domains

- DomainListResponse
  - `success` boolean: Success flag
  - `data` Domain[]: List of items
    - `id` integer: Domain ID
    - `domain_tld` string: Full domain name including TLD
    - `mail_domain` string: Mail domain prefix
    - `status` string: Domain status
    - `is_warmup` boolean: Whether domain is in warmup
    - `warmup_start_date` string: Warmup start date
    - `warmup_end_date` string: Warmup end date
    - `mailbox_count` integer: Number of mailboxes used
    - `redirect_url` string: Domain redirect URL
    - `attached_at` string: Date domain was attached
    - `nameservers` string[]: Active nameservers for the domain
    - `dns_provider` DnsProvider: DNS provider information
      - `id` integer: Provider ID
      - `name` string: Provider name
    - `mailboxes` Mailbox[]: Mailboxes belonging to this domain (if requested)
      - `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
    - `tags` Tag[]: Tags assigned to this domain
      - `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)