Route incoming email with rules

Forward incoming mail to a webhook, store it, or send attachments on — using conditions you define.

NevarMail's inbound routing system lets you define rules that automatically process incoming emails based on conditions you specify. Rules are evaluated in priority order, and matching emails trigger the configured actions.

How it works

An inbound email arrives via your provider's webhook (e.g., SendGrid Inbound Parse)
NevarMail evaluates the email against all enabled routing rules, sorted by priority
For each matching rule, the configured actions are executed
Multiple rules can match the same email

Create a routing rule

The routing-rule endpoints on this page are browser-session only (the same calls the Inbound page in the app makes). An API key gets 403 SESSION_ONLY; there is no /api/v1/ equivalent yet, so manage rules from the app.

POST /api/inbound/rules
{
  "name": "Forward support emails",
  "priority": 0,
  "isEnabled": true,
  "conditions": [
    { "field": "to", "operator": "contains", "value": "support@" }
  ],
  "actions": [
    { "type": "webhook", "url": "https://your-app.com/webhooks/support" }
  ]
}

Rule fields

Field	Type	Required	Description
`name`	string	Yes	Rule name
`priority`	number	No	Evaluation order (lower = evaluated first)
`isEnabled`	boolean	No	Whether the rule is active (default: `true`)
`conditions`	array	Yes	Match conditions (all must match)
`actions`	array	Yes	Actions to execute on match
`metadata`	object	No	Arbitrary metadata

Condition operators

Operator	Description	Example
`contains`	Field contains the value	`{ "field": "subject", "operator": "contains", "value": "urgent" }`
`equals`	Field exactly matches the value	`{ "field": "from", "operator": "equals", "value": "bot@service.com" }`
`greater_than`	Field is greater than the value	`{ "field": "size", "operator": "greater_than", "value": "1000000" }`
`less_than`	Field is less than the value	`{ "field": "size", "operator": "less_than", "value": "500" }`

Condition fields

You can match against any field on the inbound email payload:

from -- Sender email address
to -- Recipient email address
subject -- Email subject line
body -- Email body content
size -- Email size in bytes
Any custom header

Action types

Type	Fields	Description
`webhook`	`url`	Send the email data to a webhook URL
`store`	`bucket`	Store the email in a named bucket
`forward`	`email`	Forward the email to another address
`forward_attachments`	`destination`	Deliver just the email's attachments to a webhook or S3

forward_attachments takes a destination object instead of a flat field, since it supports two delivery targets:

{
  "type": "forward_attachments",
  "destination": {
    "service": "webhook",
    "url": "https://your-app.com/webhooks/attachments",
    "bearerToken": "your-bearer-token"
  }
}

{
  "type": "forward_attachments",
  "destination": {
    "service": "s3",
    "bucket": "your-bucket",
    "region": "us-east-1",
    "accessKeyId": "AKIA...",
    "secretAccessKey": "your-secret-access-key",
    "pathTemplate": "inbound/{yyyy}/{mm}/{dd}/{msgid}/{filename}"
  }
}

For an S3-compatible endpoint other than AWS, add endpoint alongside bucket; region then defaults to "auto".

pathTemplate supports single-brace tokens only — {yyyy}, {mm}, {dd} (UTC date the email was received), {msgid} (a deterministic per-message id), {filename} (the sanitized original attachment filename), and {index} (the attachment's 0-based position in the email). The template must include {filename} or {index} so multiple attachments on one email can't overwrite each other, must not start with /, and can't contain .. or backslashes. "inbound/{yyyy}/{mm}/{dd}/{msgid}/{filename}" is the default when pathTemplate is omitted.

bearerToken and secretAccessKey are write-only: NevarMail encrypts them at rest and never returns them in a later read — omitting the field on an update keeps the currently stored value. Never paste a real token or key into a rule you're just testing; use a placeholder and set the real value from a system that already holds it securely.

Managing rules today

Routing rules are managed from the Inbound page inside a project (or a use case within a project) in the NevarMail dashboard — there is no /api/v1 equivalent yet, so rules can only be created, edited, or deleted through the dashboard's session-authenticated routes below (not with an API key).

List rules

GET /api/inbound/rules

Update a rule

PUT /api/inbound/rules/:id
{
  "priority": 5,
  "isEnabled": false
}

Delete a rule

DELETE /api/inbound/rules/:id

Test routing

Test how an email would be routed without actually processing it:

POST /api/inbound/test
{
  "from": "customer@example.com",
  "to": "support@yourdomain.com",
  "subject": "Help with my order",
  "body": "I need assistance with order #1234"
}

{
  "matchedRules": [
    {
      "ruleId": "...",
      "ruleName": "Forward support emails",
      "actions": [{ "type": "webhook", "url": "https://your-app.com/webhooks/support" }]
    }
  ],
  "totalRulesEvaluated": 5
}

This is useful for verifying your rules work as expected before enabling them in production.

Route incoming email with rules

On this page