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

# Set Up a Custom Email Domain on UGMail Step by Step

> Add a custom domain to UGMail, retrieve the required DNS records, and configure them in your registrar to start sending and receiving email.

Before you can send or receive email through UGMail, you need to register your domain with the platform and point your DNS records to UGMail's infrastructure. This guide walks you through creating the domain via the Management API, fetching the DNS records UGMail generates for you, and adding those records at your registrar so your domain is fully verified and ready to use.

## Prerequisites

* A UGMail account with a valid Bearer token (find yours at **Settings → API Connection** in the [UGMail dashboard](https://my.ugmail.co))
* A domain you own and can manage DNS records for
* `curl` or any HTTP client

<Steps>
  <Step title="Create the domain via the API">
    Send a `POST` request to `/api/principal` with your domain name and the type `domain`. This registers the domain inside your UGMail account and triggers generation of the DNS records you'll need in the next step.

    ```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 a `201` status along with a JSON object confirming the domain has been created. If you receive a `409`, the domain is already registered on your account.
  </Step>

  <Step title="Fetch your DNS records">
    Retrieve the DNS records UGMail has generated for your domain by calling the `/api/dns/{domain}` endpoint. The response includes the MX record, an SPF TXT record, and a DKIM TXT record — all three are required for full email deliverability.

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

    Copy the values from the response — you'll paste them into your DNS registrar in the next step.
  </Step>

  <Step title="Add the DNS records at your registrar">
    Log in to your domain registrar (e.g., Cloudflare, Namecheap, GoDaddy) and create the following records using the exact values returned by the API in the previous step:

    | Record                | Type | Purpose                                                                     |
    | --------------------- | ---- | --------------------------------------------------------------------------- |
    | `@` or `mail`         | MX   | Routes incoming email to UGMail's mail servers                              |
    | `@`                   | TXT  | SPF record — prevents spoofing by authorizing UGMail to send on your behalf |
    | `selector._domainkey` | TXT  | DKIM record — cryptographically signs outgoing messages                     |

    Enter the values exactly as provided. Any trailing spaces or missing characters in the DKIM record will cause signature verification to fail.
  </Step>

  <Step title="Verify DNS propagation">
    DNS changes can take anywhere from a few minutes to 48 hours to propagate worldwide. Before testing email delivery, confirm that your records are live and resolving correctly.

    <Tip>
      Use [MXToolbox](https://mxtoolbox.com) to verify each record type. Enter your domain in the MX Lookup tool, and use the TXT Lookup tool to confirm both your SPF and DKIM records are visible from the public DNS.
    </Tip>

    Once all three record types resolve correctly, your domain is fully configured. You can now [provision mailboxes](/guides/provision-mailbox) on this domain.
  </Step>
</Steps>

<Note>
  DNS propagation typically completes within a few hours, but the full window is up to **48 hours** depending on your registrar's TTL settings and how aggressively resolvers around the world cache records. If records aren't visible after 48 hours, double-check that you saved the correct values at your registrar and that there are no conflicting records of the same type.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Provision a Mailbox" icon="inbox" href="/guides/provision-mailbox">
    Create your first email account on this domain using the Management API.
  </Card>

  <Card title="Manage Aliases" icon="at" href="/guides/manage-aliases">
    Add role-based addresses like support@ and info@ to existing mailboxes.
  </Card>
</CardGroup>