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
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
string
required
The forwarding address (e.g.,
forward@example.com). This is the address that receives the incoming mail and redirects it.string
required
Must be
"individual".array of strings
required
The email address(es) that trigger the forward. Typically contains just the forwarding address itself.
array of strings
required
The destination address(es) where mail should be redirected. Can include external addresses on any domain.
Example Request
Example Response
Response Fields
string
The unique identifier for the forwarder principal.
string
The forwarding address.
string
Always
"individual" for forwarder principals.array of strings
The address(es) that trigger the forward.
array of strings
The destination address(es) where mail is redirected.
List All Forwarders
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
Get a Forwarder
GET /api/principal/{name}
Retrieve the details of a specific forwarder by its address.
Path Parameters
string
required
The forwarding address to retrieve (e.g.,
forward@example.com).Example Request
Example Response
Update a Forwarder
PATCH /api/principal/{name}
Update the destination address(es) for an existing forwarder by replacing the members array.
Path Parameters
string
required
The forwarding address to update (e.g.,
forward@example.com).Request Parameters
array of strings
The new list of destination addresses. This replaces the existing
members array entirely.Example — Change the Destination
Example — Forward to Multiple Addresses
Delete a Forwarder
DELETE /api/principal/{name}
Remove a forwarder. Incoming mail to the address will no longer be redirected.
Path Parameters
string
required
The forwarding address to delete (e.g.,
forward@example.com).Example Request
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.