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
The forwarding address (e.g.,
forward@example.com). This is the address that receives the incoming mail and redirects it.Must be
"individual".The email address(es) that trigger the forward. Typically contains just the forwarding address itself.
The destination address(es) where mail should be redirected. Can include external addresses on any domain.
Example Request
Example Response
Response Fields
The unique identifier for the forwarder principal.
The forwarding address.
Always
"individual" for forwarder principals.The address(es) that trigger the forward.
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
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
The forwarding address to update (e.g.,
forward@example.com).Request Parameters
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
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.