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

# Domains

> Register and verify sending domains

# Domains

Before you can send email, you need at least one verified domain. Numonic registers your domain with AWS SES and provides the DNS records you need to prove ownership and enable DKIM signing.

All domain endpoints require **JWT authentication**.

***

## Register a domain

```
POST /api/v1/domains
```

Registers a domain and returns the DNS records you need to add.

### Request

```bash theme={null}
curl -X POST https://api.numonic.com/api/v1/domains \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "domain_name": "yourapp.com"
  }'
```

### Body parameters

| Parameter     | Type   | Required | Description                                 |
| ------------- | ------ | -------- | ------------------------------------------- |
| `domain_name` | string | Yes      | The domain to register (e.g. `yourapp.com`) |

### Response `201`

```json theme={null}
{
  "tenant_id":   "550e8400-e29b-41d4-a716-446655440000",
  "domain_id":   123,
  "domain_name": "yourapp.com",
  "identity_arn": "arn:aws:ses:us-east-1:123456789012:identity/yourapp.com",
  "dns_records": [
    {
      "type":  "TXT",
      "name":  "_amazonses.yourapp.com",
      "value": "abc123def456..."
    },
    {
      "type":  "CNAME",
      "name":  "abc123._domainkey.yourapp.com",
      "value": "abc123.dkim.amazonses.com"
    }
  ]
}
```

Add all returned DNS records at your domain registrar. Verification typically completes within minutes but can take up to 72 hours.

### Errors

| Status | Code               | Cause                        |
| ------ | ------------------ | ---------------------------- |
| `409`  | `CONFLICT`         | Domain is already registered |
| `422`  | `VALIDATION_ERROR` | Invalid domain format        |

***

## List domains

```
GET /api/v1/domains
```

Returns all domains registered to your account.

### Request

```bash theme={null}
curl https://api.numonic.com/api/v1/domains \
  -H "Authorization: Bearer YOUR_JWT"
```

### Response `200`

```json theme={null}
[
  {
    "domain_id":              123,
    "tenant_id":              "550e8400-e29b-41d4-a716-446655440000",
    "domain_name":            "yourapp.com",
    "verification_status":    "Success",
    "identity_arn":           "arn:aws:ses:us-east-1:123456789012:identity/yourapp.com",
    "configuration_set_name": "numonic-emails"
  }
]
```

### Verification status values

| Status    | Meaning                            |
| --------- | ---------------------------------- |
| `Pending` | DNS records not yet detected       |
| `Success` | Domain verified and ready to send  |
| `Failed`  | DNS records incorrect or not found |

***

## Get domain details

```
GET /api/v1/domains/:id
```

Returns full details for a single domain, including DNS records.

### Request

```bash theme={null}
curl https://api.numonic.com/api/v1/domains/123 \
  -H "Authorization: Bearer YOUR_JWT"
```

### Response `200`

```json theme={null}
{
  "domain_id":              123,
  "tenant_id":              "550e8400-e29b-41d4-a716-446655440000",
  "domain_name":            "yourapp.com",
  "verification_status":    "Success",
  "identity_arn":           "arn:aws:ses:us-east-1:123456789012:identity/yourapp.com",
  "configuration_set_name": "numonic-emails",
  "dns_records": [
    {
      "type":  "TXT",
      "name":  "_amazonses.yourapp.com",
      "value": "abc123def456..."
    },
    {
      "type":  "CNAME",
      "name":  "abc123._domainkey.yourapp.com",
      "value": "abc123.dkim.amazonses.com"
    }
  ]
}
```

### Errors

| Status | Code        | Cause                                         |
| ------ | ----------- | --------------------------------------------- |
| `404`  | `NOT_FOUND` | Domain not found or belongs to another tenant |

***

## Delete a domain

```
DELETE /api/v1/domains/:id
```

Removes a domain from your account and deregisters it from SES.

### Request

```bash theme={null}
curl -X DELETE https://api.numonic.com/api/v1/domains/123 \
  -H "Authorization: Bearer YOUR_JWT"
```

### Response `200`

```json theme={null}
{
  "success": true
}
```

### Errors

| Status | Code        | Cause                                         |
| ------ | ----------- | --------------------------------------------- |
| `404`  | `NOT_FOUND` | Domain not found or belongs to another tenant |