Domains API — Create and Manage Custom Email Domains

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

POST /api/principal Register a new domain with your UGMail account. Once the domain is created, use the DNS Records API to retrieve the MX, SPF, and DKIM records you need to add at your registrar.

Request Parameters

name

string

required

The domain name to register (e.g., example.com). This becomes the unique identifier for the domain principal.

type

string

required

Must be "domain" to create a domain principal.

Example Request

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

{
  "id": "example.com",
  "name": "example.com",
  "type": "domain"
}

Response Fields

string

The unique identifier for the domain principal. Identical to name for domain principals.

name

string

The domain name that was registered.

type

string

Always "domain" for domain principals.

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.

List All Principals

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

Example Request

curl "https://mail.ugmail.co/api/principal?type=domain" \
  -H "Authorization: Bearer YOUR_TOKEN"

Query Parameters

type

string

Filter results by principal type. Pass type=domain to return only domain principals.

Example Response

[
  {
    "id": "example.com",
    "name": "example.com",
    "type": "domain"
  },
  {
    "id": "myotherdomain.com",
    "name": "myotherdomain.com",
    "type": "domain"
  }
]

Get a Domain

GET /api/principal/{name} Retrieve the details of a specific domain by its name.

Path Parameters

name

string

required

The domain name (e.g., example.com).

Example Request

curl "https://mail.ugmail.co/api/principal/example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "id": "example.com",
  "name": "example.com",
  "type": "domain"
}

Delete a Domain

DELETE /api/principal/{name} Remove a domain from your account. This action is permanent and cannot be undone.

Path Parameters

name

string

required

The domain name to delete (e.g., example.com).

Example Request

curl -X DELETE "https://mail.ugmail.co/api/principal/example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "success": true
}

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.

Overview

Endpoints

Domains API — Create and Manage Custom Email Domains

Create a Domain

Request Parameters

Example Request

Example Response

Response Fields

List All Principals

Example Request

Query Parameters

Example Response

Get a Domain

Path Parameters

Example Request

Example Response

Delete a Domain

Path Parameters

Example Request

Example Response

​Create a Domain

​Request Parameters

​Example Request

​Example Response

​Response Fields

​List All Principals

​Example Request

​Query Parameters

​Example Response

​Get a Domain

​Path Parameters

​Example Request

​Example Response

​Delete a Domain

​Path Parameters

​Example Request

​Example Response

Create a Domain

Request Parameters

Example Request

Example Response

Response Fields

List All Principals

Example Request

Query Parameters

Example Response

Get a Domain

Path Parameters

Example Request

Example Response

Delete a Domain

Path Parameters

Example Request

Example Response