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

# Email Aliases and Forwarders: Routing Mail in UGMail

> Aliases let multiple addresses share one mailbox. Forwarders automatically redirect incoming messages to another address. Both are managed via the API.

Routing email intelligently is just as important as sending and receiving it. UGMail gives you two distinct tools for controlling where inbound messages land: aliases, which let multiple addresses share a single mailbox, and forwarders, which redirect messages to a completely different destination. Both are managed programmatically through the UGMail API.

<Info>
  Aliases and forwarders are managed per-domain. The domain referenced in any alias or forwarder address must already exist as a domain principal in your tenant.
</Info>

***

## Aliases

An alias is an additional email address that delivers mail into an existing mailbox. When a message arrives at an alias address, UGMail routes it to the mailbox that owns that alias — the recipient sees the message in their inbox exactly as if it had been sent directly to their primary address.

### Use Cases

<CardGroup cols={2}>
  <Card title="Role-based addresses" icon="briefcase">
    Map `support@example.com`, `billing@example.com`, and `hello@example.com` to a single inbox without creating separate accounts.
  </Card>

  <Card title="Catch-all addresses" icon="net">
    Catch every message sent to any address on your domain and route it to one mailbox for review.
  </Card>

  <Card title="Branded inboxes" icon="tag">
    Give a user multiple branded identities (e.g., `alice@acme.com` and `alice@support.acme.com`) that both land in the same place.
  </Card>

  <Card title="Privacy addresses" icon="eye-slash">
    Issue throwaway addresses that forward to a real inbox, keeping the primary address private.
  </Card>
</CardGroup>

### Creating an Alias

Aliases are stored in the `emails` array of a mailbox principal. To add an alias, update the mailbox's `emails` array to include the new address alongside the existing ones.

First, retrieve the current mailbox to get its ID and existing `emails` value:

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

Then patch the mailbox to add the alias:

```bash theme={null}
curl -X PATCH "https://mail.ugmail.co/api/principal/MAILBOX_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      "alice@example.com",
      "support@example.com",
      "hello@example.com"
    ]
  }'
```

From this point on, messages sent to `support@example.com` or `hello@example.com` are delivered to the same mailbox as `alice@example.com`.

<Note>
  The `emails` array is a full replacement — always include the primary address and all existing aliases when you PATCH, or previous entries will be removed.
</Note>

***

## Forwarders

A forwarder is a routing rule that redirects incoming mail from one address to a different destination. Unlike an alias, the destination of a forwarder does not have to be a mailbox on the same domain — it can be any valid email address, including an external one (for example, a Gmail or Outlook address).

### Use Cases

<CardGroup cols={2}>
  <Card title="Consolidate inboxes" icon="inbox">
    Pull mail from multiple domain addresses into one external inbox during a migration or transition period.
  </Card>

  <Card title="Temporary redirects" icon="clock">
    Forward mail for a former employee to their replacement for a set period after they leave.
  </Card>

  <Card title="Support routing" icon="headset">
    Redirect `support@example.com` to your helpdesk platform's inbound email address.
  </Card>

  <Card title="Monitoring" icon="bell">
    Forward a copy of all mail sent to an address to a logging or archiving mailbox.
  </Card>
</CardGroup>

### Creating a Forwarder

Create a forwarder by posting a principal of type `"forwarder"` and specifying the source address and the destination to forward to:

```bash theme={null}
curl -X POST "https://mail.ugmail.co/api/principal" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support@example.com",
    "type": "forwarder",
    "emails": ["support@example.com"],
    "members": ["helpdesk@external-provider.com"]
  }'
```

Once the forwarder is active, any message sent to `support@example.com` is automatically redirected to `helpdesk@external-provider.com`.

<Warning>
  Forwarding email to external addresses can affect your domain's deliverability and spam reputation if the destination provider applies strict SPF checks. Consider setting up a [DKIM signature](/concepts/dkim-signing) and configuring DMARC to mitigate forwarding-related delivery issues.
</Warning>

***

## Aliases vs. Forwarders at a Glance

| Feature                       | Alias                       | Forwarder                                  |
| ----------------------------- | --------------------------- | ------------------------------------------ |
| Destination                   | Same mailbox on UGMail      | Any email address                          |
| Stores mail on UGMail         | ✅ Yes                       | ❌ No (redirected only)                     |
| Supports external destination | ❌ No                        | ✅ Yes                                      |
| Managed via                   | `emails` array on principal | `members` array on a `forwarder` principal |
| Authentication needed to read | ✅ Yes (IMAP/POP3/JMAP)      | ❌ N/A                                      |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Domains" icon="globe" href="/concepts/domains">
    Review domain setup if you haven't configured DNS yet.
  </Card>

  <Card title="DKIM Signing" icon="shield-check" href="/concepts/dkim-signing">
    Protect forwarded and outbound mail with DKIM authentication.
  </Card>
</CardGroup>