Skip to main content
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.
A successful response returns the newly created principal object, including the domain’s unique identifier, which you can use in subsequent API calls.
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.

​
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.
The response will contain a set of records similar to the following: 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.
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.

​
Domain Lifecycle

Every domain in UGMail moves through the following stages:
1

Create the domain

Call POST /api/principal with type: "domain" and the domain name. UGMail registers the domain within your tenant.
2

Retrieve DNS records

Call GET /api/dns/{domain} to get your MX, SPF, and DKIM records.
3

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).
4

Domain becomes active

Once DNS is propagated, your domain is fully active. You can now provision mailboxes, aliases, and forwarders under it.

​
Managing Multiple Domains

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

Multi-brand businesses

Operate separate email domains for different product lines or subsidiaries from a single UGMail account.

Customer tenants

Provision a dedicated domain for each of your own customers if you are building an email-as-a-service product on top of UGMail.

Staging environments

Create isolated domains for development and QA so test emails never touch your production domain.

Catch-all routing

Run a secondary domain that catches all inbound mail and routes it to a single mailbox for monitoring or archiving.
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.

Mailboxes

Create individual email accounts under your domain.

DKIM Signing

Learn how DKIM authentication protects your outbound mail.
Last modified on July 17, 2026