The Forwards API is a streamlined way to configure inbound email processing on your Mailgun account. It is designed as a simpler, more scalable alternative to Mailgun's existing Routes service — purpose-built for the common case of forwarding incoming email to one or more destinations.
Where Routes offer broad, script-like flexibility (filtering, storing, stopping, and chaining actions), the Forwards API focuses on doing one thing well: matching an incoming recipient address and routing that email onward. This narrower scope means less configuration overhead and better performance at scale.
| Routes | Forwards API | |
|---|---|---|
| Use case | Complex, multi-action inbound processing | Simple email forwarding |
| Configuration | Expression-based filter syntax | Wildcard match patterns |
| Actions | Forward, store, stop | Forward to recipients, URLs, or store |
| Scale | Degrades with rule volume | Designed to scale with large rule sets |
| Best for | Advanced routing logic | Straightforward recipient-based forwarding |
Use the Forwards API when you need to forward inbound email based on recipient address and don't require complex conditional logic. Stick with Routes if you need multi-action pipelines or expression-based filtering.
Each forward rule includes a match pattern that is evaluated against the recipient address of every incoming email. Matching is case-insensitive and supports * as a wildcard for any sequence of characters.
| Pattern | Matches |
|---|---|
support@mg.example.com | Only that exact address |
support*@mg.example.com | Any address starting with support |
*@mg.example.com | All addresses on the domain (catch-all) |
Note: Only
*and literal characters are supported — this is not a regex match. A pattern likea.*@example.commatches addresses starting witha.(literal dot), not any character aftera.
All API endpoints that return a forward rule share this structure:
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the rule |
account_id | string | The Mailgun account this rule belongs to |
domain_name | string | The domain the rule is scoped to |
domain_id | string | Unique identifier of the associated domain |
match | string | The wildcard pattern matched against incoming recipient addresses |
forward.urls | array | Webhook URLs that receive matching emails |
forward.recipients | array | Email addresses that receive forwarded copies |
forward.store | string | Webhook URL notified on arrival, with a link to retrieve the message |
created_at | string | ISO 8601 timestamp of rule creation |
updated_at | string | ISO 8601 timestamp of the last update |