---
title: "Delete domains"
method: DELETE
path: "/api/v1/domains"
tags: ["Domains"]
---

# Delete domains

`DELETE /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`

Deletes one or more domains for the authenticated client.

## Deletion Rules
- **Only pending domains can be deleted**
- Domains in other statuses (active, in progress, inactive, etc.) are skipped
- Skipped domains are returned in the response with a reason

## Mailbox Handling
- **All pending mailboxes** under the domain are automatically **inactivated** before domain deletion
- **Domains with active mailboxes** (ACTIVE, IN_PROGRESS, etc.) **cannot be deleted** and are skipped
- Only domains where all mailboxes are PENDING or INACTIVE can be deleted
- When a domain is deleted, all its mailboxes are effectively removed (inactivated)

## Identifiers
You can specify domains to delete using:
- `ids`: Array of domain IDs
- `domains`: Array of domain names
- Or both (they will be combined)

## Slot Management
- **Domain slots** are automatically freed after successful deletion
- **Mailbox slots** are automatically freed based on the number of mailboxes that were inactivated

## Request body

- DeleteDomainsRequest: Request to delete one or more domains
  - `ids` integer[]: List of domain IDs to delete
  - `domains` string[]: List of domain names to delete

## Response `200`

Domains deleted successfully

- DeleteDomainsApiResponse
  - `success` boolean: Success flag
  - `data` DeleteDomainsResponse: Response after deleting domains
    - `deleted_count` integer: Number of domains successfully deleted
    - `deleted_domains` string[]: List of deleted domain names
    - `skipped_domains` SkippedDomain[]: List of domains that could not be deleted (not in pending status)
      - `identifier` string: Domain name or ID
      - `reason` string: Reason for skipping
  - `timestamp` string: Response timestamp

## Other responses

- `400`: Invalid request - missing identifiers
- `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)