Rules

Mail rules on the active connection, in the order they run. A rule is a set of conditions over an inbound message and a list of things to do to anything matching them: label it, archive it, forward it. Order matters: rules run top to bottom and one marked "stops here" prevents every rule below it from running. Reports whether each is enabled, which is the fact worth reading. A disabled rule is doing nothing at all. Use getRule for one in full, including its conditions and its actions. One page at a time: when more follow, the last line gives a cursor to pass back, with the same filter, for the next page.

One rule in full, by id (rul_…): every condition it tests, every action it takes, whether it stops the rules below it, and how many messages it has matched. Read this back to the person before asking for a rule to be enabled. The conditions are the part that decides what happens to their mail, and a rule reads very differently from the sentence that asked for it.

Create a mail rule on the active connection: conditions over an inbound message, and what should happen to anything matching them. THE RULE IS CREATED DISABLED. It does nothing to any mail until a person turns it on, because a rule that archives or forwards should not start doing that on the strength of a chat message. Call testRule next to show which of the last thirty days’ messages it would have caught, read the rule back, and only then ask whether to enable it with setRuleEnabled. Rules run in order and a new one goes last: reorderRules changes the order, updateRule edits a rule and deleteRule removes it.

A dry run: which of the recent messages in the inbox this rule WOULD have matched, and what it would have done to them. Changes nothing: no message is labelled, archived, forwarded or replied to, and the rule is not enabled. This is what to show a person before asking whether to turn a rule on. It scores the newest message each thread RECEIVED and never the mailbox’s own sends or replies, because a rule only ever runs on arriving mail. It reads STORED messages rather than deliveries, which costs the answer two different ways and both belong in whatever you report. Conditions on a raw header, on a mailing-list id, on the SMTP envelope, on message size or on the delivered-to address cannot be answered at all and are reported as untestable rather than counted as misses. Attachment, hour and weekday conditions ARE answered, but from stored mail rather than from the delivery. Stored mail drops images inlined into the body, which delivery counts as attachments, and keeps only the sender’s own Date: header, where delivery uses our receipt clock. Those are therefore reported as approximate, and the dates printed beside each match are the sender’s. A message that arrived encrypted has no readable body at all, so a body condition is neither matched nor missed on it. The result says how many were skipped that way, and that number belongs in whatever you report. Pass those caveats on rather than relaying the count as an exact answer.

Turn a rule on or off. ENABLING A RULE STARTS IT ACTING ON REAL MAIL IMMEDIATELY: the next message that matches it is labelled, archived, forwarded or replied to without anybody being asked, and some of those cannot be undone. Only enable a rule a person has actually been shown. Call getRule to read it back and testRule to show what it would have caught, and ask. It applies to mail that arrives from now on and does not go back over messages already in the mailbox. Disabling is the reverse and is always safe: the rule stops matching and nothing it already did is undone.

Change a rule: its name, description, conditions, actions, whether it stops the rules below it, whether it is on, or its position. What you pass replaces that part of the rule, so conditions and actions are whole lists. A rule that is on acts on the next message that matches it, so read it back with getRule and show testRule first. reorderRules sets the whole order at once.

Delete a rule for good. It stops acting on mail at once, and nothing it already did is undone. There is no bin for rules. setRuleEnabled with enabled false is the reversible way to stop one.

Set the order rules run in, first to last. ruleIds has to name every rule listRules shows you, each once. Order is part of what rules do: one that stops the rules below it hides them from every message it matches.

What the rules did, newest first: each time a rule matched a message, which actions it took and which of them failed. Narrow it to one rule with ruleId or to one conversation with threadId. One page at a time: when more follow, the last line gives a cursor to pass back, with the same filters, for the next page.