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

# Forwarders API — Redirect Incoming Email Automatically

> Create email forwarders that redirect incoming messages to another address. Manage forwarders via the UGMail API on any domain in your account.

A forwarder redirects incoming email from one address to another — the message is not stored locally but is passed on to a destination address, which can be on any domain, including external providers like Gmail or Outlook. Forwarders are useful for catch-all routing, legacy address migration, or giving contractors a company address that forwards to their personal inbox.

Forwarders are created as `individual` principals with a `members` array specifying the destination address(es). Unlike aliases — which deliver copies of mail into the same mailbox inbox — forwarders redirect the message away from the local system entirely.

***

## Create a Forwarder

<br />

`POST /api/principal`

Create a forwarding address on your domain. Incoming mail to the address in `emails` is redirected to every address listed in `members`.

### Request Parameters

<ParamField body="name" type="string" required>
  The forwarding address (e.g., `forward@example.com`). This is the address that receives the incoming mail and redirects it.
</ParamField>

<ParamField body="type" type="string" required>
  Must be `"individual"`.
</ParamField>

<ParamField body="emails" type="array of strings" required>
  The email address(es) that trigger the forward. Typically contains just the forwarding address itself.
</ParamField>

<ParamField body="members" type="array of strings" required>
  The destination address(es) where mail should be redirected. Can include external addresses on any domain.
</ParamField>

### Example Request

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

### Example Response

```json theme={null}
{
  "id": "forward@example.com",
  "name": "forward@example.com",
  "type": "individual",
  "emails": ["forward@example.com"],
  "members": ["destination@otherdomain.com"]
}
```

### Response Fields

<ResponseField name="id" type="string">
  The unique identifier for the forwarder principal.
</ResponseField>

<ResponseField name="name" type="string">
  The forwarding address.
</ResponseField>

<ResponseField name="type" type="string">
  Always `"individual"` for forwarder principals.
</ResponseField>

<ResponseField name="emails" type="array of strings">
  The address(es) that trigger the forward.
</ResponseField>

<ResponseField name="members" type="array of strings">
  The destination address(es) where mail is redirected.
</ResponseField>

***

## List All Forwarders

<br />

`GET /api/principal`

Retrieve all principals in your account and filter to individual principals to find forwarders. You can identify forwarders by the presence of a non-empty `members` array in the response.

### Example Request

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

***

## Get a Forwarder

<br />

`GET /api/principal/{name}`

Retrieve the details of a specific forwarder by its address.

### Path Parameters

<ParamField path="name" type="string" required>
  The forwarding address to retrieve (e.g., `forward@example.com`).
</ParamField>

### Example Request

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

### Example Response

```json theme={null}
{
  "id": "forward@example.com",
  "name": "forward@example.com",
  "type": "individual",
  "emails": ["forward@example.com"],
  "members": ["destination@otherdomain.com"]
}
```

***

## Update a Forwarder

<br />

`PATCH /api/principal/{name}`

Update the destination address(es) for an existing forwarder by replacing the `members` array.

### Path Parameters

<ParamField path="name" type="string" required>
  The forwarding address to update (e.g., `forward@example.com`).
</ParamField>

### Request Parameters

<ParamField body="members" type="array of strings">
  The new list of destination addresses. This replaces the existing `members` array entirely.
</ParamField>

### Example — Change the Destination

```bash theme={null}
curl -X PATCH "https://mail.ugmail.co/api/principal/forward@example.com" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "members": ["newdestination@otherdomain.com"]
  }'
```

### Example — Forward to Multiple Addresses

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

***

## Delete a Forwarder

<br />

`DELETE /api/principal/{name}`

Remove a forwarder. Incoming mail to the address will no longer be redirected.

### Path Parameters

<ParamField path="name" type="string" required>
  The forwarding address to delete (e.g., `forward@example.com`).
</ParamField>

### Example Request

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

***

<Note>
  **Aliases vs. Forwarders:** An alias is an additional address on an existing mailbox — mail is stored in that mailbox's inbox. A forwarder redirects mail to another address without storing it locally. Use aliases when you want multiple addresses to reach the same inbox. Use forwarders when you want mail routed elsewhere, such as to an external address or to multiple recipients.
</Note>