Aliases API — Add Multiple Email Addresses to a Mailbox

An alias is an additional email address that delivers messages into an existing mailbox. When someone sends an email to an alias, it arrives in the same inbox as mail sent to the primary address — there is no separate account to check or manage. Aliases are useful for routing role-based addresses (like support@ or info@) to an individual’s inbox, or for giving one person multiple addresses across different domains. Aliases are managed by updating the emails array on a mailbox principal using PATCH /api/principal/{name}. The full array you provide replaces the existing one, so always include every address you want to keep — including the primary address.

Add Aliases to a Mailbox

PATCH /api/principal/{name} Update the emails array on a mailbox to add one or more aliases. Every address in the array will deliver to that mailbox’s inbox.

Path Parameters

name

string

required

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

Request Parameters

emails

array of strings

required

The complete list of email addresses for this mailbox. Include the primary address and all aliases you want active. Any address omitted from this array will be removed.

Example — Add Two Aliases

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",
      "support@example.com",
      "info@example.com"
    ]
  }'

Example Response

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

Remove an Alias

To remove an alias, send a PATCH request with an emails array that omits the address you want to delete. All other addresses in the array are preserved.

Example — Remove `info@example.com`

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",
      "support@example.com"
    ]
  }'

After this request, info@example.com no longer delivers to Alice’s inbox.

List Current Aliases

To see all aliases currently active on a mailbox, retrieve the principal and inspect its emails array:

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

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

All alias addresses must belong to domains that are registered in your UGMail account. You cannot add an alias on a domain you have not added via POST /api/principal. See the Domains API for how to register a domain.

Need to deliver to an external address instead of storing in an inbox? That is a forwarder, not an alias. See the Forwarders API for details.

Overview

Endpoints

Aliases API — Add Multiple Email Addresses to a Mailbox

Add Aliases to a Mailbox

Path Parameters

Request Parameters

Example — Add Two Aliases

Example Response

Remove an Alias

Example — Remove `info@example.com`

List Current Aliases

​Add Aliases to a Mailbox

​Path Parameters

​Request Parameters

​Example — Add Two Aliases

​Example Response

​Remove an Alias

​Example — Remove info@example.com

​List Current Aliases

Add Aliases to a Mailbox

Path Parameters

Request Parameters

Example — Add Two Aliases

Example Response

Remove an Alias

Example — Remove `info@example.com`

List Current Aliases