Forward an address
Where the mail of an address goes besides its mailbox. Every destination confirms by email before it receives anything.
Runs any of 5 calls on your workspace.
GET /domains/{id}/addresses/{addressId}/forwards
Where the mail of an address goes besides its mailbox. Every destination confirms by email before it receives anything.
List the destinations
Needs domains:read. Every destination of the address, oldest first. destination says whether the address also keeps a copy here (mailbox) or only forwards (forward), and max is how many destinations one address may have.
curl "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/addresses/5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18/forwards" -H "$AUTH"{ "object": "list", "address": "[email protected]", "destination": "mailbox", "max": 10, "data": [ { "object": "address_forward", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "[email protected]", "enabled": true, "status": "live", "confirmedAt": "2026-09-26T08:12:40.000Z", "askedAt": "2026-09-26T08:02:11.000Z", "lastRelayAt": "2026-09-30T16:45:03.000Z", "lastError": null, "failures": 0, "createdAt": "2026-09-26T08:02:11.000Z" } ]}status is live once the destination confirmed it wants the mail, pending while it has not answered, refused when it said no and paused while it is switched off. Only a live destination receives anything.
Add destinations
Needs domains:write. POST /domains/{id}/addresses/{addressId}/forwards with { emails }, 1 to 10 addresses. Each new destination is sent an email asking it to confirm, so it starts pending.
curl -X POST "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/addresses/5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18/forwards" -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{ "emails": ["[email protected]", "[email protected]"] }'{ "object": "address_forwards", "added": [ { "object": "address_forward", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "[email protected]", "enabled": true, "status": "pending", "confirmedAt": null, "askedAt": "2026-09-26T08:02:11.000Z", "lastRelayAt": null, "lastError": null, "failures": 0, "createdAt": "2026-09-26T08:02:11.000Z" } ], "skipped": [ { "email": "[email protected]", "reason": "[email protected] is hosted here, so it cannot be a forwarding destination. Share the address with that person instead." } ]}An address hosted here, one already on the list, one that would make a loop, one past the limit of 10 and one that refused mail from this workspace are named in skipped with the reason, and the rest are still added.
An address that is switched off is refused with 409 address_disabled.
A key limited to particular addresses or domains needs to hold the whole domain, and an app acting for a member can only forward an address that member reaches.
An OAuth access token needs a verification code for this call. Until the app has verified one in the last 60 minutes, the call answers 403 step_up_required and changes nothing. An API key is never asked. The Authentication page shows how to ask for a code and verify it.
Pause or switch on a destination
Needs domains:write. PATCH /domains/{id}/addresses/{addressId}/forwards/{forwardId} with { enabled }. A paused destination keeps its confirmation, so switching it back on needs none.
curl -X PATCH "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/addresses/5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18/forwards/9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d" -H "$AUTH" \ -H "Content-Type: application/json" \ -d '{ "enabled": false }'{ "object": "address_forward", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "[email protected]", "enabled": false, "status": "paused", "destination": "mailbox"}When the last destination that is on is paused, the address goes back to keeping its mail here, and destination says so.
An OAuth access token needs a verification code for this call. Until the app has verified one in the last 60 minutes, the call answers 403 step_up_required and changes nothing. An API key is never asked. The Authentication page shows how to ask for a code and verify it.
Remove a destination
Needs domains:write. DELETE /domains/{id}/addresses/{addressId}/forwards/{forwardId}. Nothing more is forwarded to it.
curl -X DELETE "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/addresses/5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18/forwards/9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d" -H "$AUTH"{ "object": "address_forward", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "[email protected]", "deleted": true, "destination": "mailbox"}When it was the last destination that was on, the address goes back to keeping its mail here.
An OAuth access token needs a verification code for this call. Until the app has verified one in the last 60 minutes, the call answers 403 step_up_required and changes nothing. An API key is never asked. The Authentication page shows how to ask for a code and verify it.
Ask a destination to confirm again
Needs domains:write. POST /domains/{id}/addresses/{addressId}/forwards/{forwardId}/resend sends the confirmation email once more.
curl -X POST "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/addresses/5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18/forwards/9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d/resend" -H "$AUTH"{ "object": "address_forward_consent", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "[email protected]", "status": "sent"}status is sent, already-confirmed when the destination needs nothing, too-soon when the last email went out moments ago, revoked when the destination refused mail from this workspace, or send-failed when the email could not be sent.
An OAuth access token needs a verification code for this call. Until the app has verified one in the last 60 minutes, the call answers 403 step_up_required and changes nothing. An API key is never asked. The Authentication page shows how to ask for a code and verify it.
Reference
/domains/{id}/addresses/{addressId}/forwardsFull reference/domains/{id}/addresses/{addressId}/forwardsFull reference/domains/{id}/addresses/{addressId}/forwards/{forwardId}Full reference/domains/{id}/addresses/{addressId}/forwards/{forwardId}Full reference/domains/{id}/addresses/{addressId}/forwards/{forwardId}/resendFull reference