Skip to main content
Creates a persistent mail rule that automatically applies to future incoming messages until it is disabled or deleted. The agent distills the user’s natural language (“automatically archive all GitHub notifications”) into structured conditions and actions; the rule then runs server-side inside the mail server on every delivery — no client or agent needs to be online. Rules are stored as a single managed Sieve script named langmail-rules in the user’s own account, so they are visible over ManageSieve and leave with the user — no proprietary rule store.
This tool is for ongoing behavior (“automatically…”, “from now on…”, “whenever I receive…”). Future automation and historical cleanup are separate concerns: by default existing mail is untouched, and the optional existingMail policy is what applies the same actions to mail already in the mailbox. Clients should ask for clarification when a request like “archive all GitHub notifications” could equally mean either.

​
Parameters

​
string
Optional human-readable rule name, e.g. "Archive GitHub Notifications".
​
string
default:"all"
How multiple conditions combine: "all" (every condition must match) or "any" (one is enough).
​
object
required
When the rule fires — at least one of (all matching is case-insensitive substring matching):
  • from — sender contains this (address, domain, or display name)
  • to — a To/Cc recipient contains this
  • subject — subject line contains this
  • bodyContains — message body contains this text
  • hasAttachment — true to match only messages that appear to carry an attachment (heuristic; some signed or inline-attachment messages may not match)
​
array
required
One or more actions, applied in order. Each is { "type": … } plus its fields:
  • archive — move out of the Inbox into the Archive folder
  • move / copy — mailbox: target folder (created if missing)
  • addTag / removeTag — tag: tag name, slugified ("Acme Corp" → acme-corp)
  • markRead / markUnread / flag
  • delete — move to Trash (not a permanent erase)
  • forward — to: address that receives a copy; the original still lands in the mailbox
  • stopProcessing — stop evaluating later rules for this message
​
object
Optional policy for also applying the actions to mail already in the mailbox:
  • mode — "none" (default), "messages" (each matching message), or "conversations" (every message in a matching thread)
  • scope — "inbox" (default) or "all" mail
  • confirmLargeApply — required true when more than 200 existing messages match; call preview_mail_rule first and confirm the count with the user
forward and stopProcessing are future-mail-only and are skipped (and reported) in a backfill.

​
Example

Call
Result

​
Notes

  • Rules are independent: every enabled rule whose conditions match a message runs, unless an earlier rule used stopProcessing.
  • A denied large backfill creates nothing — the rule is only saved once the call goes through.
  • A forwarding rule always keeps the local copy (redirect :copy in Sieve) — a rule can never make mail silently vanish.