An email forwarding rule routes an address such as sales@example.com to an existing destination inbox. It does not create a mailbox, password, IMAP account or outgoing SMTP service. Confirm that the domain's configured mail runtime and product support forwarding before replacing existing MX records.
| Method | Resource | Scope | Idempotency-Key |
|---|---|---|---|
POST |
/v2/forwarding/domains/{domainId}/mail-rules |
forwarding:mail |
Required |
PATCH |
/v2/forwarding/mail-rules/{ruleId} |
forwarding:mail |
Required |
POST |
/v2/forwarding/mail-rules/{ruleId}/resend-verification |
forwarding:mail |
Required |
POST |
/v2/forwarding/mail-rules/{ruleId}/verify-destination |
forwarding:mail |
Required |
01 Create and verify one alias
- Complete forwarding-domain onboarding and review the current mail DNS instructions and conflicts.
- List existing rules so the same source is not unintentionally assigned twice.
- POST
source_type: "address",source_localpart: "sales"and the completedestination_email. Choose the intended enabled state and supported spam policy. - Ask the authorised recipient to open the destination inbox and complete the issued verification. If using the API verification step, submit the received
verification_codeonly for that owned rule. - Check the rule's verification state and the resulting deployment work. Confirm the mail domain's DNS and runtime are ready before testing delivery.
- Send a test from an independent mailbox and check the destination and available delivery trace.
02 Change or remove a route
Changing destination_email invalidates the previous destination's verification. The new recipient must verify again before the route is ready. Preserve the old rule details for your change record and use the current If-Match version when editing concurrently.
The delete endpoint disables the forwarding rule and queues the relevant deployment. Confirm the runtime outcome; it does not delete the external destination inbox. A saved local change and deployed routing are distinct states.
Common questions
Can I forward every possible address?
A catch_all rule is available only when the mail-domain policy permits it. Whole-domain address mapping is not supported by this rule contract. Prefer explicit aliases when those meet the business need.
What if the verification email is missing?
Confirm the destination spelling, inbox access and spam folder, then use the resend endpoint. Repeated requests do not verify the recipient automatically. Keep verification codes out of logs and support screenshots.
Can I send mail as sales@example.com using this rule?
Forwarding covers incoming routing. Configure an authorised outgoing mail service separately and follow its sender authentication requirements.