> ## 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.

# Aliases API — Add Multiple Email Addresses to a Mailbox

> Add and remove email aliases on any mailbox by updating the emails array via PATCH /api/principal/{name}. Route multiple addresses to one inbox.

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

<br />

`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

<ParamField path="name" type="string" required>
  The primary email address of the mailbox (e.g., `alice@example.com`).
</ParamField>

### Request Parameters

<ParamField body="emails" type="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.
</ParamField>

### Example — Add Two Aliases

```bash theme={null}
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

```json theme={null}
{
  "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`

```bash theme={null}
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:

```bash theme={null}
curl "https://mail.ugmail.co/api/principal/alice@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```json theme={null}
{
  "id": "alice@example.com",
  "name": "alice@example.com",
  "type": "individual",
  "emails": [
    "alice@example.com",
    "support@example.com"
  ]
}
```

***

<Note>
  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](/api-reference/domains) for how to register a domain.
</Note>

<Tip>
  Need to deliver to an external address instead of storing in an inbox? That is a forwarder, not an alias. See the [Forwarders API](/api-reference/forwarders) for details.
</Tip>