Inbox rules

Inbox rules are server-side filters for new inbound email. They run even when your email client is closed, so each mailbox can sort messages, mark them, trigger webhooks, or create AI draft replies as soon as mail arrives.

Last updated July 13, 2026

Where to manage rules

In the dashboard, open Mailboxes, choose a mailbox, and select Inbox rules. The dialog shows the mailbox address, existing rules, available folder targets, and recent rule activity.

You can also manage rules through the mailboxes API. Call GET /v1/mailboxes/:id/rules first to read existing rules and folder IDs, then replace the full rule set with PUT /v1/mailboxes/:id/rules.

How rules run

Rules belong to one mailbox and run on every new inbound message for that mailbox.
Rules run from top to bottom. Disabled rules are skipped.
A rule matches when its conditions pass. Choose all when every condition must match, or any when one matching condition is enough.
Condition groups can be nested when a rule needs mixed all and any logic.
If Stop after this rule is enabled, lower rules are skipped after the current rule matches.

Conditions

Text and address matching is case-insensitive.

Condition	Matches
from_is	Sender email exactly matches an address.
from_contains	Sender email contains text, such as a domain.
recipient_is	Envelope recipient exactly matches an address.
plus_tag_is	The plus tag in an address like `support+vip@example.com` matches a value.
subject_contains	Subject contains text.
has_attachment	The message includes an attachment.
list_unsubscribe_exists	The message has a `List-Unsubscribe` header.

Actions

Move to. Move the message to Inbox, Archive, Junk, Trash, or a custom folder.
Mark as read. Add the seen flag to the message.
Star. Add the flagged flag to the message.
Draft an AI reply. Create a reply draft for review in Needs You. The agent never sends the reply on its own.
Send webhook. Queue a mailbox.rule_matched webhook event for active webhooks subscribed to that event.

Example rule

This rule catches mail sent to support+vip@example.com, moves it to a custom folder, stars it, and stops lower rules from running.

{
  "id": "4f5a9d74-b0f1-49a7-bbfb-1f2af841f5b2",
  "name": "VIP support",
  "enabled": true,
  "position": 0,
  "match_mode": "all",
  "stop": true,
  "conditions": [
    { "type": "plus_tag_is", "value": "vip" },
    { "type": "recipient_is", "value": "support+vip@example.com" }
  ],
  "actions": [
    { "type": "move", "target": { "kind": "custom", "folder_id": "fld_123" } },
    { "type": "star" }
  ]
}

Limits

Each mailbox can have up to 50 rules.
Each rule can have up to 10 condition leaves and 5 actions.
Condition groups can nest up to 3 levels deep.
Rule names and rule IDs must be unique within a mailbox.
A rule can have only one move action and one AI draft reply action.

Notes

Inbox rules do not forward or reject mail. Use mailbox forwarding for verified receive-only copies, or use Sieve when you need raw server-side filtering scripts beyond the dashboard and API features.
If a rule uses a sender condition and has a webhook or AI draft reply action, Shipmail only runs that automation when the inbound message passes DMARC. This prevents spoofed sender addresses from triggering external workflows or agent drafts.
Deleting a custom folder that is used by a rule is blocked until you update the rule.
Updating rules through the API replaces the full rules array. Read the existing rules first if you are changing one rule programmatically.