--- title: "Forward an address" description: "Where the mail of an address goes besides its mailbox. Every destination confirms by email before it receives anything." url: "https://openemail.uk/docs/api/domains/addresses/forwards" area: "API" category: "Mailbox" --- # Forward an address Where the mail of an address goes besides its mailbox. Every destination confirms by email before it receives anything. `GET /domains/{id}/addresses/{addressId}/forwards` **Also documents:** `POST /domains/{id}/addresses/{addressId}/forwards`, `PATCH /domains/{id}/addresses/{addressId}/forwards/{forwardId}`, `DELETE /domains/{id}/addresses/{addressId}/forwards/{forwardId}`, `POST /domains/{id}/addresses/{addressId}/forwards/{forwardId}/resend` ## 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** ``` curl "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/addresses/5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18/forwards" -H "$AUTH" ``` **Response** ``` { "object": "list", "address": "billing@acme.com", "destination": "mailbox", "max": 10, "data": [ { "object": "address_forward", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "accounts@partner.example", "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** ``` 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": ["accounts@partner.example", "team@acme.com"] }' ``` **Response** ``` { "object": "address_forwards", "added": [ { "object": "address_forward", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "accounts@partner.example", "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": "team@acme.com", "reason": "team@acme.com 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** ``` 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 }' ``` **Response** ``` { "object": "address_forward", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "accounts@partner.example", "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** ``` curl -X DELETE "$OE/domains/b3e1f0a4-6c2d-4e8a-9f17-2d5c8a0b4e6f/addresses/5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18/forwards/9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d" -H "$AUTH" ``` **Response** ``` { "object": "address_forward", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "accounts@partner.example", "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** ``` 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" ``` **Response** ``` { "object": "address_forward_consent", "id": "9a4c1e7b-2d3f-4b5a-8c6d-0e1f2a3b4c5d", "addressId": "5f0c2b7e-8d41-4a6f-b913-7e2a0c4d9b18", "email": "accounts@partner.example", "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 - [`GET /domains/{id}/addresses/{addressId}/forwards`](https://openemail.uk/docs/api/reference/domains#get-domains-id-addresses-addressid-forwards): full reference - [`POST /domains/{id}/addresses/{addressId}/forwards`](https://openemail.uk/docs/api/reference/domains#post-domains-id-addresses-addressid-forwards): full reference - [`PATCH /domains/{id}/addresses/{addressId}/forwards/{forwardId}`](https://openemail.uk/docs/api/reference/domains#patch-domains-id-addresses-addressid-forwards-forwardid): full reference - [`DELETE /domains/{id}/addresses/{addressId}/forwards/{forwardId}`](https://openemail.uk/docs/api/reference/domains#delete-domains-id-addresses-addressid-forwards-forwardid): full reference - [`POST /domains/{id}/addresses/{addressId}/forwards/{forwardId}/resend`](https://openemail.uk/docs/api/reference/domains#post-domains-id-addresses-addressid-forwards-forwardid-resend): full reference