> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mail.ugmail.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create and Manage Mailbox Aliases Using the UGMail API

> Add extra email addresses to any mailbox using aliases. Route support@, info@, and role-based addresses to the right inbox without creating extra accounts.

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.

```bash theme={null}
# Add aliases to an existing mailbox
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"
    ]
  }'
```

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.

```bash theme={null}
# Remove info@example.com, keep support@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"
    ]
  }'
```

## Aliases vs. forwarders

Aliases and forwarders both let you receive email at multiple addresses, but they work differently:

|                 | Alias                                               | Forwarder                                             |
| --------------- | --------------------------------------------------- | ----------------------------------------------------- |
| **Delivery**    | Delivers directly to the aliased mailbox            | Relays the message to a different destination address |
| **Destination** | Must be a mailbox on your UGMail account            | Can be any email address, including external ones     |
| **Replies**     | Replies come from the aliased mailbox's credentials | Replies come from the forwarding destination          |
| **Best for**    | Multiple addresses for the same person or team      | Redirecting mail to an address outside UGMail         |

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.

<Note>
  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](/guides/setup-domain), then add aliases on it.
</Note>

<Tip>
  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.
</Tip>

## Next steps

<CardGroup cols={2}>
  <Card title="Provision a Mailbox" icon="inbox" href="/guides/provision-mailbox">
    Create new mailboxes to assign aliases to via the Management API.
  </Card>

  <Card title="SaaS Onboarding" icon="users" href="/guides/saas-onboarding">
    Automate mailbox and alias provisioning for every new user or team.
  </Card>
</CardGroup>