Airpost
Using Airpost

Mail rules

Sort incoming mail automatically with conditions and actions, and how the engine applies rules as mail arrives.

Rules sort mail as it arrives: file receipts into a folder, star mail from your manager, forward invoices to your accountant. Each account has its own rules. Set them up in Preferences > Rules, or from the CLI.

Rules run in the engine on your computer, not on your mail provider’s server. They don’t show up in Gmail’s filters or Outlook’s rules, and those keep working alongside them.

Create a rule

Pick the account

Choose the account at the top of Preferences > Rules, then click + New rule.

Name the rule and add conditions

Give it a Name. Choose whether Any or All conditions must match, then add conditions. Use the plus button to add more.

Add actions

Under Perform these actions:, add one or more actions. They run in the order listed.

Click Done

The rule is on as soon as you save it, and applies to mail that arrives from then on. To also apply it to what’s already in your inbox, see Running rules on existing mail.

Rules run in the order shown. Use Move up and Move down to reorder them, and the switch on each row to turn a rule off without deleting it.

Conditions

ConditionCompares
From, To, Cc, BccNames and addresses in that field
RecipientAny of To, Cc or Bcc
Reply toThe reply-to address
Attachment nameFile names of attachments
SubjectThe subject
BodyThe message body
Has attachmentTrue or false
StarredTrue or false

Text conditions take one of these comparators:

ComparatorMatches when the field
containsIncludes the value anywhere
does not containDoesn’t include it
begins withStarts with it
ends withEnds with it, for example @example.com
equalsIs exactly the value
matches expressionMatches a regular expression, for example `^(invoice

Actions

ActionAvailable onWhat it does
Mark as ReadAll accountsMarks the message read
Move to TrashAll accountsMoves the thread to Trash
StarAll accountsStars the thread
ForwardAll accountsForwards the message, with its attachments, to an address you give
Move MessageFolder-based accounts (IMAP, Microsoft)Moves the thread to a folder
Apply LabelGmailAdds a label
Move to LabelGmailReplaces the thread’s labels with one
ArchiveGmailTakes the thread out of the inbox
Mark as ImportantGmailMarks the thread important

A forward is sent straight away, without the undo window.

How rules are applied

  • Once per message. The engine runs rules on a message once, when it has both its body and a copy you received. Drafts and mail you sent to others are left alone, and so is mail dated before rules started running on the account.
  • In order, over the whole batch. Mail that arrives together is processed in batches of up to 50 messages. Each rule runs over the batch before the next one starts, so a later rule sees what an earlier one did, and can undo it (a later “Move Message” wins over an earlier one).
  • Locally first. Each action changes your local mail immediately and reaches the server in the background, the same way your own clicks do.
  • Failures stop the rule, not the others. If a rule fails (an invalid regular expression, a folder that no longer exists) the engine turns it off and records why. The rule shows Stopped in Preferences with the reason; fix the action and click Turn on.
  • No window needed. Rules run in the engine, so they keep running with the window closed. To run them after you quit, turn on Keep Airpost running in the background in Preferences > General. Mail that arrived while the engine wasn’t running isn’t checked when it starts again; use Run now below to catch up.

Running rules on existing mail

New rules apply to mail that arrives after you create them. To apply your rules to mail you already have, use Run rules on your inbox > Run now under Mail you already have.

The engine walks the inbox newest first, 50 threads at a time, showing progress as it goes. Mail that arrives during the run is still handled between batches. Click Stop to cancel; what already ran stays done. The run also stops if the account stops syncing or the engine stops.

Running rules over thousands of threads moves a lot of mail at once. Check a new rule first: search for what it should catch (for example from:shop.example) and make sure the results are what you expect, then run it.

From the CLI

airpost rules reads and writes the same rules, and the desktop picks up changes immediately.

# List rules in the order they run
airpost rules list

# Add a rule: conditions with --if, actions with --then (both repeatable)
airpost rules add --name Receipts \
  --if 'from contains shop.example' \
  --then 'move Receipts'

# Match any condition instead of all
airpost rules add --name "Team mail" --match any \
  --if 'to contains team@example.com' --if 'cc contains team@example.com' \
  --then star

# Turn a rule off and on, or run all rules over the inbox
airpost rules disable Receipts
airpost rules enable Receipts
airpost rules reprocess --wait

--if takes FIELD COMPARATOR VALUE: fields from, to, cc, bcc, recipient, reply-to, attachment-name, subject, body; comparators contains, not-contains, begins-with, ends-with, equals, matches. has-attachment and starred take true (the default) or false. --then takes mark-read, star, trash, forward ADDRESS, move FOLDER, and on Gmail also label LABEL, move LABEL, archive and important.

A rule is checked before it’s saved, so an unknown field, a bad expression or a folder that doesn’t exist is refused with an error instead of failing later. airpost rules show <rule> --json prints a rule in the shape --rule accepts, if you’d rather edit JSON.

Edge cases

  • Rules are per account. To sort mail the same way in two accounts, create the rule in each.
  • Rules don’t run on Sent or other folders. They run on mail as it arrives, and Run now walks the inbox only.
  • Turning a rule off keeps it in place and order; turning it back on clears any error it had.