# Mailgun Forwards API

## Overview

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.

## Why Forwards Instead of Routes?

|  | 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.

## Wildcard Matching

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 like `a.*@example.com` matches addresses starting with `a.` (literal dot), not any character after `a`.


## The Forward Rule Object

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 |