Skip to main content
An alias is an additional email address that delivers mail to an existing mailbox. When someone sends a message to support@example.com, the message lands in the same inbox as alice@example.com — no second account, no separate login, no extra storage. Aliases are ideal for role-based addresses, shared team inboxes, and keeping your domain tidy without multiplying the number of accounts you manage. In UGMail, you add aliases by updating the emails array on an existing principal via the API.

​
What you can do with aliases

  • Route support@, info@, billing@, and hello@ to the right person’s inbox without creating separate accounts
  • Give a single person multiple identities (e.g., alice@example.com and a.smith@example.com) that all land in one place
  • Set up team inboxes where multiple senders all receive replies at a shared address
  • Consolidate role-based addresses during a team restructure without interrupting email delivery

​
Add an alias to an existing mailbox

To add aliases, send a PATCH request to /api/principal/{email} with the full, updated emails array. The array must always include the primary address — any address you include beyond the first becomes an alias.
After this request, any email sent to support@example.com or info@example.com will be delivered to Alice’s inbox. Alice can also send from these addresses if her email client supports multiple sender identities.

​
Remove an alias

To remove an alias, send the same PATCH request with an emails array that omits the address you want to remove. Only the addresses in the new array will be active — anything left out is removed.

​
Aliases vs. forwarders

Aliases and forwarders both let you receive email at multiple addresses, but they work differently: Use aliases when the destination is a mailbox you manage in UGMail. Use forwarders when you need to redirect mail to an external address, such as a team member’s personal account or a third-party helpdesk.
Aliases must use domains that are already registered in your UGMail account. If you try to add an alias on a domain you haven’t set up yet (e.g., support@newdomain.com before adding newdomain.com), the request will fail with an error indicating the domain is not found. Set up the domain first, then add aliases on it.
Aliases are a great way to create shared team inboxes without the overhead of a shared login. Assign support@example.com as an alias on your support lead’s mailbox, and billing@example.com on your finance lead’s mailbox. Each person manages their own inbox and credentials while the whole team presents a unified set of addresses to customers.

​
Next steps

Provision a Mailbox

Create new mailboxes to assign aliases to via the Management API.

SaaS Onboarding

Automate mailbox and alias provisioning for every new user or team.
Last modified on July 17, 2026