Mailboxes API — Provision and Manage Email Accounts

Mailboxes are email accounts that can send and receive messages. In UGMail, a mailbox is an individual principal identified by its full email address. You can provision as many mailboxes as you need — there are no per-user fees. Each mailbox can have a password for IMAP/SMTP access and one or more email addresses (aliases) that deliver into the same inbox.

Create a Mailbox

POST /api/principal Create a new mailbox for a user on any domain in your account. The domain must already be registered before you can provision mailboxes under it.

Request Parameters

name

string

required

The full email address for the mailbox (e.g., alice@example.com). This is the unique identifier for the principal and cannot be changed after creation.

type

string

required

Must be "individual" to create a mailbox.

secrets

array of strings

required

One or more passwords for IMAP/SMTP authentication. Pass the password as a string inside an array (e.g., ["SecurePassword123!"]).

emails

array of strings

required

The list of email addresses that deliver to this mailbox. Always include the primary address (name) in this array. Additional entries become aliases.

Example Request

curl -X POST "https://mail.ugmail.co/api/principal" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "alice@example.com",
    "type": "individual",
    "secrets": ["SecurePassword123!"],
    "emails": ["alice@example.com"]
  }'

import requests

response = requests.post(
    "https://mail.ugmail.co/api/principal",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json",
    },
    json={
        "name": "alice@example.com",
        "type": "individual",
        "secrets": ["SecurePassword123!"],
        "emails": ["alice@example.com"],
    },
)

print(response.json())

const response = await fetch("https://mail.ugmail.co/api/principal", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "alice@example.com",
    type: "individual",
    secrets: ["SecurePassword123!"],
    emails: ["alice@example.com"],
  }),
});

const data = await response.json();
console.log(data);

Example Response

{
  "id": "alice@example.com",
  "name": "alice@example.com",
  "type": "individual",
  "emails": ["alice@example.com"]
}

Response Fields

string

The unique identifier for the mailbox principal. Identical to name.

name

string

The primary email address of the mailbox.

type

string

Always "individual" for mailbox principals.

emails

array of strings

All email addresses that deliver to this mailbox, including the primary address and any aliases.

List All Mailboxes

GET /api/principal Retrieve a list of all mailbox principals in your account. Use the type=individual query parameter to return only mailboxes and exclude domains and groups.

Query Parameters

type

string

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

Example Request

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

Example Response

[
  {
    "id": "alice@example.com",
    "name": "alice@example.com",
    "type": "individual",
    "emails": ["alice@example.com"]
  },
  {
    "id": "bob@example.com",
    "name": "bob@example.com",
    "type": "individual",
    "emails": ["bob@example.com", "robert@example.com"]
  }
]

Get a Mailbox

GET /api/principal/{name} Retrieve the details of a specific mailbox by its primary email address.

Path Parameters

name

string

required

The primary email address of the mailbox to retrieve (e.g., alice@example.com).

Example Request

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

Example Response

{
  "id": "alice@example.com",
  "name": "alice@example.com",
  "type": "individual",
  "emails": ["alice@example.com"]
}

Update a Mailbox

PATCH /api/principal/{name} Update an existing mailbox. Use this endpoint to change the password, add or remove aliases, or update other mailbox properties.

Path Parameters

name

string

required

The primary email address of the mailbox to update (e.g., alice@example.com).

Request Parameters

secrets

array of strings

Replace the mailbox password(s). Provide the new password(s) as an array of strings.

emails

array of strings

Replace the full list of email addresses for this mailbox. To add an alias, include the current addresses plus the new one. To remove an alias, omit it from the array. Always include the primary address.

Example — Change Password

curl -X PATCH "https://mail.ugmail.co/api/principal/alice@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "secrets": ["NewSecurePassword456!"]
  }'

Example — Add an Alias

curl -X PATCH "https://mail.ugmail.co/api/principal/alice@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "alice@example.com",
      "a.smith@example.com"
    ]
  }'

Delete a Mailbox

DELETE /api/principal/{name} Permanently remove a mailbox from your account. All email stored in the mailbox is deleted.

Path Parameters

name

string

required

The primary email address of the mailbox to delete (e.g., alice@example.com).

Example Request

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

Example Response

{
  "success": true
}

Connecting to a Mailbox

Once you provision a mailbox, your users can connect to it using any standard IMAP/SMTP email client. Use the following settings:

Setting	Value
IMAP Host	`mail.ugmail.co`
IMAP Port	`993` (SSL/TLS)
SMTP Host	`mail.ugmail.co`
SMTP Port	`587` (STARTTLS)
Username	Full email address (e.g., `alice@example.com`)
Password	The value passed in `secrets` when the mailbox was created

Your domain’s DNS records must be fully propagated before SMTP delivery will work. Retrieve the required records from GET /api/dns/ and add them at your registrar.

Overview

Endpoints

Mailboxes API — Provision and Manage Email Accounts

Create a Mailbox

Request Parameters

Example Request

Example Response

Response Fields

List All Mailboxes

Query Parameters

Example Request

Example Response

Get a Mailbox

Path Parameters

Example Request

Example Response

Update a Mailbox

Path Parameters

Request Parameters

Example — Change Password

Example — Add an Alias

Delete a Mailbox

Path Parameters

Example Request

Example Response

Connecting to a Mailbox

​Create a Mailbox

​Request Parameters

​Example Request

​Example Response

​Response Fields

​List All Mailboxes

​Query Parameters

​Example Request

​Example Response

​Get a Mailbox

​Path Parameters

​Example Request

​Example Response

​Update a Mailbox

​Path Parameters

​Request Parameters

​Example — Change Password

​Example — Add an Alias

​Delete a Mailbox

​Path Parameters

​Example Request

​Example Response

​Connecting to a Mailbox

Create a Mailbox

Request Parameters

Example Request

Example Response

Response Fields

List All Mailboxes

Query Parameters

Example Request

Example Response

Get a Mailbox

Path Parameters

Example Request

Example Response

Update a Mailbox

Path Parameters

Request Parameters

Example — Change Password

Example — Add an Alias

Delete a Mailbox

Path Parameters

Example Request

Example Response

Connecting to a Mailbox