> ## 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.

# UGMail Domains: Set Up and Manage Your Email Domain

> A domain in UGMail is the foundation of your email infrastructure. Learn how domains are created, verified with DNS, and managed through the API.

A domain in UGMail is the organizational container that anchors your entire email infrastructure. Every mailbox, alias, and forwarder you provision belongs to a domain, so adding a domain is always the first step when setting up email for any of your users or services.

## What is a Domain in UGMail?

When you register a domain with UGMail, you are telling the platform to manage sending and receiving for that domain name (for example, `example.com`). UGMail then issues the DNS records you need to point your registrar at UGMail's mail servers and to authenticate your outbound email. Until those records are in place, messages will not flow correctly, so completing DNS setup is a required part of domain onboarding.

Each domain is fully isolated within your tenant — other UGMail accounts cannot see or interact with your domains, mailboxes, or configuration.

## Creating a Domain

Create a domain by sending a `POST` request to `/api/principal` with `type` set to `"domain"`. The `name` field must be the fully qualified domain name you want to manage.

```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"}'
```

A successful response returns the newly created principal object, including the domain's unique identifier, which you can use in subsequent API calls.

<Note>
  You must own the domain and have access to its DNS settings before creating it in UGMail. UGMail does not register domain names — it manages email for domains you already control.
</Note>

## Setting Up DNS

After creating a domain, retrieve the exact DNS records UGMail requires by calling `GET /api/dns/{domain}`. The response includes MX, SPF, and DKIM records tailored to your domain.

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

The response will contain a set of records similar to the following:

| Record type | Host                              | Value                            |
| ----------- | --------------------------------- | -------------------------------- |
| MX          | `example.com`                     | `mail.ugmail.co` (priority 10)   |
| TXT (SPF)   | `example.com`                     | `v=spf1 include:ugmail.co ~all`  |
| TXT (DKIM)  | `selector._domainkey.example.com` | `v=DKIM1; k=rsa; p=<public-key>` |

Log in to your domain registrar or DNS provider and add each record exactly as returned by the API. Once the records propagate (typically within a few minutes to a few hours), your domain is active and ready to send and receive mail.

<Warning>
  Do not delete or modify your existing MX records until you are ready to fully switch email handling to UGMail. Changing MX records will immediately redirect incoming mail.
</Warning>

## Domain Lifecycle

Every domain in UGMail moves through the following stages:

<Steps>
  <Step title="Create the domain">
    Call `POST /api/principal` with `type: "domain"` and the domain name. UGMail registers the domain within your tenant.
  </Step>

  <Step title="Retrieve DNS records">
    Call `GET /api/dns/{domain}` to get your MX, SPF, and DKIM records.
  </Step>

  <Step title="Configure your DNS provider">
    Add the returned records at your domain registrar or DNS host. Wait for propagation (up to 48 hours in rare cases, but usually much faster).
  </Step>

  <Step title="Domain becomes active">
    Once DNS is propagated, your domain is fully active. You can now provision mailboxes, aliases, and forwarders under it.
  </Step>
</Steps>

## Managing Multiple Domains

UGMail supports an unlimited number of domains per tenant. This is useful for:

<CardGroup cols={2}>
  <Card title="Multi-brand businesses" icon="building">
    Operate separate email domains for different product lines or subsidiaries from a single UGMail account.
  </Card>

  <Card title="Customer tenants" icon="users">
    Provision a dedicated domain for each of your own customers if you are building an email-as-a-service product on top of UGMail.
  </Card>

  <Card title="Staging environments" icon="flask">
    Create isolated domains for development and QA so test emails never touch your production domain.
  </Card>

  <Card title="Catch-all routing" icon="envelope">
    Run a secondary domain that catches all inbound mail and routes it to a single mailbox for monitoring or archiving.
  </Card>
</CardGroup>

To list all domains currently registered under your tenant, call `GET /api/principal` and filter results by `type: "domain"`.

## Next Steps

With your domain created and DNS configured, you are ready to start provisioning mailboxes.

<CardGroup cols={2}>
  <Card title="Mailboxes" icon="inbox" href="/concepts/mailboxes">
    Create individual email accounts under your domain.
  </Card>

  <Card title="DKIM Signing" icon="shield-check" href="/concepts/dkim-signing">
    Learn how DKIM authentication protects your outbound mail.
  </Card>
</CardGroup>