Registers a sending domain and returns DNS records. Permission: `domains`.

## Body Parameters

| Name | Type | Description |
| ---- | ---- | ----------- |
| `domain` | string | **Required.** Hostname to register, e.g. `mail.example.com`. |

## Response Fields

| Field | Type | Description |
| ----- | ---- | ----------- |
| `id` | string | MailDomain id. |
| `domain` | string | Registered hostname. |
| `status` | string | `NOT_STARTED`, `PENDING`, `VERIFIED`, or `FAILED`. |
| `region` | string | AWS region when provisioned. |
| `dnsRecords` | array | Records to add: `type`, `name`, `value`, `priority`, `ttl`, `purpose`. |
| `sesRecords` | array | Stored SES DNS records when present. |
| `message` | string | Next-step copy. |

## Errors

| Status | `name` | When |
| ------ | ------ | ---- |
| 401 | `missing_api_key` | Missing or invalid bearer token |
| 403 | `missing_permission` | Token lacks the `domains` permission |
| 400 | `validation_error` | Already registered, claimed elsewhere, or plan limit |

## Related

- [Verify Domain](/docs/api-reference/v2/domains-verify)
- [Get Domain](/docs/api-reference/v2/domains-get)
- [SDK: lumail.domains.create](/docs/sdk/v2/domains-create)


## API Reference
**Method:** POST
**Endpoint:** /api/v2/domains

### SDK
```ts
import { Lumail } from "lumail";

const lumail = new Lumail({ apiKey: process.env.LUMAIL_API_KEY });
const { data, error } = await lumail.domains.create({
  domain: "mail.example.com",
});
if (error) {
  throw error;
}
console.log(data.id, data.status);
```

### cURL
```bash
curl -X POST https://lumail.io/api/v2/domains \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'
```

### JavaScript
```javascript
const response = await fetch("https://lumail.io/api/v2/domains", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ domain: "mail.example.com" }),
});
const data = await response.json();
```

### Success Response
```json
{
  "id": "dom_abc123",
  "domain": "mail.example.com",
  "status": "NOT_STARTED",
  "dnsRecords": [
    {
      "type": "TXT",
      "name": "mail._domainkey.mail.example.com",
      "value": "p=...",
      "purpose": "dkim"
    }
  ],
  "message": "Domain created. Add the DNS records to your DNS provider, then call verify_domain to check verification."
}
```

### Error Response
```json
{
  "name": "validation_error",
  "message": "This domain is already registered",
  "statusCode": 400
}
```