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

# Domains API — Create and Manage Custom Email Domains

> Create and manage custom email domains with the UGMail API. POST /api/principal to add a domain, GET to list or fetch, DELETE to remove.

Before you can provision mailboxes or send email, you need to register your domain with UGMail. The Domains API lets you add any domain you own, retrieve its details, list all domains in your account, and remove it when it is no longer needed. Domains are a type of **principal** in UGMail, so you create and manage them through the `/api/principal` endpoints.

***

## Create a Domain

<br />

`POST /api/principal`

Register a new domain with your UGMail account. Once the domain is created, use the [DNS Records API](/api-reference/dns) to retrieve the MX, SPF, and DKIM records you need to add at your registrar.

### Request Parameters

<ParamField body="name" type="string" required>
  The domain name to register (e.g., `example.com`). This becomes the unique identifier for the domain principal.
</ParamField>

<ParamField body="type" type="string" required>
  Must be `"domain"` to create a domain principal.
</ParamField>

### Example Request

```bash theme={null}
curl -X POST "https://mail.ugmail.co/api/principal" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "example.com",
    "type": "domain"
  }'
```

### Example Response

```json theme={null}
{
  "id": "example.com",
  "name": "example.com",
  "type": "domain"
}
```

### Response Fields

<ResponseField name="id" type="string">
  The unique identifier for the domain principal. Identical to `name` for domain principals.
</ResponseField>

<ResponseField name="name" type="string">
  The domain name that was registered.
</ResponseField>

<ResponseField name="type" type="string">
  Always `"domain"` for domain principals.
</ResponseField>

<Tip>
  After creating a domain, call `GET /api/dns/{domain}` to retrieve the DNS records you must configure at your registrar before email delivery will work.
</Tip>

***

## List All Principals

<br />

`GET /api/principal`

Retrieve a list of all principals in your account. Filter by type to return only domains.

### Example Request

```bash theme={null}
curl "https://mail.ugmail.co/api/principal?type=domain" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Query Parameters

<ParamField query="type" type="string">
  Filter results by principal type. Pass `type=domain` to return only domain principals.
</ParamField>

### Example Response

```json theme={null}
[
  {
    "id": "example.com",
    "name": "example.com",
    "type": "domain"
  },
  {
    "id": "myotherdomain.com",
    "name": "myotherdomain.com",
    "type": "domain"
  }
]
```

***

## Get a Domain

<br />

`GET /api/principal/{name}`

Retrieve the details of a specific domain by its name.

### Path Parameters

<ParamField path="name" type="string" required>
  The domain name (e.g., `example.com`).
</ParamField>

### Example Request

```bash theme={null}
curl "https://mail.ugmail.co/api/principal/example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example Response

```json theme={null}
{
  "id": "example.com",
  "name": "example.com",
  "type": "domain"
}
```

***

## Delete a Domain

<br />

`DELETE /api/principal/{name}`

Remove a domain from your account. This action is permanent and cannot be undone.

### Path Parameters

<ParamField path="name" type="string" required>
  The domain name to delete (e.g., `example.com`).
</ParamField>

### Example Request

```bash theme={null}
curl -X DELETE "https://mail.ugmail.co/api/principal/example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### Example Response

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

<Warning>
  Deleting a domain permanently removes all mailboxes, aliases, and forwarders associated with that domain. This action cannot be reversed. Make sure you no longer need any of the associated resources before proceeding.
</Warning>