Routing Rules

Control how email flows

Routing rules let you automatically forward, label, store, or trigger webhooks based on attributes of each incoming message. Rules are evaluated in priority order — the first match wins.

Overview

Every email that arrives at a Mailpipe mailbox is run through the routing pipeline. Rules are tested in ascending priority order (lower number = higher priority). As soon as a rule matches, its actions execute and evaluation stops — unless you set continue_on_match: true.

Match conditions

Filter by sender, recipient, subject line, or any header

Execute actions

Forward, call a webhook, store, label, or discard

Priority ordering

First match wins — order your rules carefully

Rule Structure

Each rule is a JSON object containing a conditions array and an actions array. All conditions in the array must match (logical AND) for the rule to fire.

Rule object schema
{
  "name": "My Rule",
  "priority": 10,
  "continue_on_match": false,
  "conditions": [
    {
      "field": "from" | "to" | "subject" | "header",
      "operator": "equals" | "contains" | "starts_with" | "ends_with" | "matches_regex",
      "value": "string to match",
      // Only required when field = "header":
      "header_name": "X-Custom-Header"
    }
  ],
  "actions": [
    {
      "type": "forward" | "webhook" | "store" | "label" | "discard",
      // type-specific fields — see Actions below
    }
  ]
}

Condition fields

Attributes you can match against

fromSender address (e.g. billing@stripe.com)
toRecipient address — any address in To, CC, or BCC
subjectEmail subject line
headerArbitrary header — specify header_name alongside value

Action types

What happens when conditions are met

forward

Re-deliver the message to another email address

Requires: to (string)

webhook

POST the full message payload to an HTTPS endpoint

Requires: url (string)

store

Save to a specific mailbox (overrides default)

Requires: mailbox_id (string)

label

Apply one or more labels for dashboard organisation

Requires: labels (string[])

discard

Drop the message silently — nothing is stored or forwarded

No extra fields required

Creating Rules

Send a POST request to /api/v1/routing/rules with your rule definition. Mailpipe validates the structure and activates the rule immediately.

POST /api/v1/routing/rules
curl -X POST "https://api.mailpipe.dev/v1/routing/rules" \
  -H "Authorization: Bearer mp_live_your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support ticket intake",
    "priority": 10,
    "conditions": [
      { "field": "to", "operator": "ends_with", "value": "@support.yourdomain.com" }
    ],
    "actions": [
      { "type": "webhook", "url": "https://your-app.com/webhooks/mailpipe" },
      { "type": "label",   "labels": ["support", "needs-triage"] }
    ]
  }'
Response
{
  "id": "rule_xyz789",
  "name": "Support ticket intake",
  "priority": 10,
  "enabled": true,
  "conditions": [ ... ],
  "actions": [ ... ],
  "created_at": "2025-01-15T12:00:00Z"
}
GET/v1/routing/rulesList all routing rules, ordered by priority
POST/v1/routing/rulesCreate a new routing rule
GET/v1/routing/rules/:idRetrieve a single rule by ID
PATCH/v1/routing/rules/:idUpdate rule fields or reorder priority
DELETE/v1/routing/rules/:idPermanently delete a rule

Rule Examples

Forward billing emails to your finance team

Any email whose subject contains the word "invoice" or "receipt" is automatically forwarded to an external finance address.

Rule — forward billing emails
{
  "name": "Forward invoices to finance",
  "priority": 20,
  "conditions": [
    {
      "field": "subject",
      "operator": "matches_regex",
      "value": "(?i)(invoice|receipt|payment|billing)"
    }
  ],
  "actions": [
    { "type": "forward", "to": "finance@yourcompany.com" },
    { "type": "label",   "labels": ["billing"] }
  ]
}

Trigger a webhook for inbound support email

When email arrives on your support@ address, call your helpdesk webhook to open a new ticket automatically.

Rule — support webhook
{
  "name": "Open support ticket",
  "priority": 10,
  "conditions": [
    { "field": "to", "operator": "equals", "value": "support@yourdomain.com" }
  ],
  "actions": [
    {
      "type": "webhook",
      "url": "https://your-helpdesk.com/api/webhooks/new-ticket",
      "headers": {
        "X-Source": "mailpipe"
      }
    },
    { "type": "label", "labels": ["support"] }
  ]
}

Silently discard email from a blocked domain

Drop any email from a known spam domain before it reaches your inbox.

Rule — discard spam sender
{
  "name": "Block spammer domain",
  "priority": 1,
  "conditions": [
    { "field": "from", "operator": "ends_with", "value": "@spammydomain.example" }
  ],
  "actions": [
    { "type": "discard" }
  ]
}

Priority and Ordering

Rules with a lower priority number are evaluated first. If two rules share the same priority, they are ordered by creation date (oldest first). You can reorder rules at any time using the PATCH /v1/routing/rules/:id endpoint.

Reorder a rule
curl -X PATCH "https://api.mailpipe.dev/v1/routing/rules/rule_xyz789" \
  -H "Authorization: Bearer mp_live_your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{ "priority": 5 }'
PriorityRuleNotes
1Block spammer domainEvaluated first — discards before further processing
10Open support ticketOnly reached if rule 1 did not match
20Forward invoices to financeCatch-all billing rule runs last

Leave gaps between priority numbers (e.g. 10, 20, 30) so you can insert new rules later without having to renumber everything.

Next Steps

Webhooks

Set up real-time event callbacks for your application

Domains

Add and verify domains before creating routing rules

Need Help?

Our team is here to help. Reach out if you have any questions.

Contact Support