Set Up a Custom Email Domain on UGMail Step by Step

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)
A domain you own and can manage DNS records for
curl or any HTTP client

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.

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.

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.

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.

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.

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.

Use MXToolbox 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.

Once all three record types resolve correctly, your domain is fully configured. You can now provision mailboxes on this domain.

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.

Get Started

Core Concepts

Protocols

Guides

Security

Set Up a Custom Email Domain on UGMail Step by Step

Prerequisites

Next steps

Provision a Mailbox

Manage Aliases

​Prerequisites

​Next steps

Provision a Mailbox

Manage Aliases

Prerequisites

Next steps