> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coldsend.pro/llms.txt
> Use this file to discover all available pages before exploring further.

# Domain Management

> Add, configure, and manage custom domains for email sending.

Custom domains enable professional email sending with your own domain reputation. ColdSend manages DNS, email services, and infrastructure setup automatically.

## Domain Status

| Status                 | Description                                                |
| ---------------------- | ---------------------------------------------------------- |
| `PENDING`              | Initial state, waiting to start setup                      |
| `DNS_CONFIGURING`      | Setting up DNS infrastructure                              |
| `DNS_PENDING`          | Waiting for you to configure nameservers at your registrar |
| `SERVICES_CONFIGURING` | Setting up email services (Azure, Mailcow)                 |
| `ACTIVE`               | Domain is ready to use                                     |
| `FAILED`               | Setup failed — can be retried                              |

## Add a Domain

**POST** `/api/public/v1/domains`

```python theme={null}
response = requests.post(
    "https://api.coldsend.pro/api/public/v1/domains",
    headers={"X-API-Key": api_key},
    json={
        "domain": "mail.yourcompany.com"
    }
)
```

The response includes nameservers you need to configure at your domain registrar. The domain then enters `DNS_PENDING` state.

## List Domains

**GET** `/api/public/v1/domains`

List all domains with optional status filtering:

```python theme={null}
response = requests.get(
    "https://api.coldsend.pro/api/public/v1/domains?status=ACTIVE&page=1&limit=20",
    headers={"X-API-Key": api_key}
)
```

### Query Parameters

| Parameter | Description                         |
| --------- | ----------------------------------- |
| `page`    | Page number (1-based, default: 1)   |
| `limit`   | Items per page (1-100, default: 20) |
| `status`  | Filter by status                    |

## Get Domain Details

**GET** `/api/public/v1/domains/{domain_id}`

Retrieve full domain information including DNS records and inbox capacity:

```python theme={null}
response = requests.get(
    f"{base_url}/api/public/v1/domains/{domain_id}",
    headers={"X-API-Key": api_key}
)
```

## Activate a Domain

**POST** `/api/public/v1/domains/{domain_id}/activate`

Complete setup after nameservers are configured:

```python theme={null}
response = requests.post(
    f"{base_url}/api/public/v1/domains/{domain_id}/activate",
    headers={"X-API-Key": api_key}
)
```

This activates email services (Azure Communication Services, Mailcow) and moves the domain to `ACTIVE` status.

## Check Setup Progress

**GET** `/api/public/v1/domains/{domain_id}/progress`

```python theme={null}
response = requests.get(
    f"{base_url}/api/public/v1/domains/{domain_id}/progress",
    headers={"X-API-Key": api_key}
)
```

Returns progress percentage and user-friendly status message.

## Delete Domain

**DELETE** `/api/public/v1/domains/{domain_id}`

Remove a domain and all associated resources:

```python theme={null}
response = requests.delete(
    f"{base_url}/api/public/v1/domains/{domain_id}",
    headers={"X-API-Key": api_key}
)
```

<Warning>
  This deletes all inboxes on the domain and cleans up Azure/Mailcow resources. The action cannot be undone. Only domains with no active campaigns can be deleted.
</Warning>

## Setup Workflow

1. **Add Domain** → Returns nameservers to configure
2. **Configure Nameservers** → Update at your registrar (GoDaddy, Cloudflare, etc.)
3. **Wait for Propagation** → Typically 15-30 minutes
4. **Activate Domain** → Completes email service setup
5. **Create Inboxes** → Use the domain to create ColdSend Native inboxes

***

## Domain Redirects

Configure URL redirect rules on your domain — useful for forwarding traffic from your sending domain to your main website or a specific landing page. Redirects are managed through Cloudflare automatically.

### Get Redirect

**GET** `/api/public/v1/domains/{domain_id}/redirect`

Returns the current redirect configuration. Returns `404` if no redirect has been configured.

```python theme={null}
response = requests.get(
    f"{base_url}/api/public/v1/domains/{domain_id}/redirect",
    headers={"X-API-Key": api_key}
)
```

### Create or Update Redirect

**POST** `/api/public/v1/domains/{domain_id}/redirect`

Acts as an **upsert** — creates a redirect if none exists, or updates the existing one. The domain must be **ACTIVE** before a redirect can be configured.

```python theme={null}
response = requests.post(
    f"{base_url}/api/public/v1/domains/{domain_id}/redirect",
    headers={"X-API-Key": api_key},
    json={
        "target_domain": "yourcompany.com",
        "status_code": 301,
        "preserve_path": True,
        "preserve_query_string": True
    }
)
```

| Field                   | Type   | Description                                                 |
| ----------------------- | ------ | ----------------------------------------------------------- |
| `target_domain`         | string | The destination domain to redirect to                       |
| `status_code`           | int    | HTTP redirect code — `301` (permanent) or `302` (temporary) |
| `preserve_path`         | bool   | Append the original URL path to the target                  |
| `preserve_query_string` | bool   | Forward query parameters to the target                      |

### Delete Redirect

**DELETE** `/api/public/v1/domains/{domain_id}/redirect`

Removes the redirect rule from Cloudflare and deletes the configuration record.

```python theme={null}
response = requests.delete(
    f"{base_url}/api/public/v1/domains/{domain_id}/redirect",
    headers={"X-API-Key": api_key}
)
```

<Info>
  Cloudflare cleanup failures are logged but do not prevent the record from being removed — the configuration is always deleted even if the Cloudflare rule can't be reached.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Sender Accounts" icon="inbox" href="/sender-accounts/overview">
    Create inboxes on your active domain.
  </Card>

  <Card title="Campaigns Overview" icon="mail" href="/campaigns/overview">
    Use your domain-enabled inboxes in campaigns.
  </Card>
</CardGroup>