openemail rules

Returns one page of the mailbox's rules in the order they run on arriving mail: ascending position, then createdAt, then id. This is deliberately not newest first. With stopProcessing in play, the same rules in a different order file mail differently, so the order you read is the order that matters.

Paging is keyset on that same (position, createdAt, id) tuple, and the cursor is opaque: it holds where the last rule on the page sat in that order. --enabled narrows to enabled or disabled rules, and the SDK sends it as the literal word true or false.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Fetches a single rule by its rul_ id. Rules have no slug and the name is editable, so store the id if your code needs to find the rule again.

The stored conditions are normalised, so negate is always present and false unless you set it. lastMatchedAt and matchCount move each time the rule fires on an arriving message, which makes them the quickest way to see whether a rule is doing anything without reading listRuns.

Creates a rule that runs on mail arriving in the mailbox, with no API call involved once it exists. It is appended after every existing rule and is enabled unless you pass enabled: false. There is no position on create: move the rule afterwards with reorder, the only call that guarantees an exact sequence. Creating it disabled and calling test first is the safe order.

Conditions are a flat list. match: 'all' is AND, match: 'any' is OR, and negate: true inverts a single condition, so (A and B) or C takes two rules. value is always a string. has_attachment and spam take only equals with 'true' or 'false'. attachment_size, message_size, hour and weekday take a number with gt, lt or equals, and gt or lt on any other field is refused. Text comparisons ignore case, and matches is a whole value glob over * and ? that needs at least two letters or digits. A header condition must name the header it reads in header.

Actions apply in order. label and remove_label take a label id, forward takes an email address and reply takes a template id or slug. A forward is only delivered once the destination has confirmed it accepts mail forwarded from your domain, and a reply goes to each sender at most once per 24 hours and never to bounces, auto-responders or mailing lists. A rule with reject must also test envelope_from, otherwise it is a 422 reject_needs_envelope, because refusing mail on the strength of a From header bounces the mailing list rather than the author.

Merges the patch onto the stored rule and validates the whole result, so an omitted field keeps its stored value instead of collecting a default. A patch that only renames a rule cannot switch a disabled one back on, and a patch that adds a reject action is checked against the conditions already stored.

conditions and actions replace the entire array. There is no way to add or remove a single element: read the rule, change the array, and send all of it. match and --stop-processing read across the whole set, which is why element level edits are not offered.

position moves this one rule without renumbering the others. Positions are not unique and ties break by createdAt then id, so landing on an occupied position puts the older rule first. Use reorder when the exact sequence matters. Setting enabled: false is the reversible alternative to delete, and a disabled rule keeps its place in the order.

Permanently removes a rule. There is no undo, and mail it already filed stays where it put it. If you might want the rule back, update(id, { enabled: false }) switches it off and keeps its place in the order.

The run history survives. listRuns({ ruleId }) still returns what the rule did, under the name it had at the time. The other rules are not renumbered, so a gap in position is normal afterwards.

Replaces the whole order in one transaction. ruleIds must name every rule on the mailbox exactly once, and each rule's position becomes its index in the array, starting at 0. Either the whole order lands or nothing moves.

A list that leaves a rule out or names one twice is a 422 incomplete_order, because an omitted rule would have to go somewhere and there is no right answer for where. Build the list from listAll() without the enabled filter so disabled rules are included. The new order applies to the next message that arrives, and mail already filed is not revisited.

Evaluates one rule against stored mail with the same matcher delivery uses and reports what it would have caught and what it would do. It changes nothing, sends nothing and files nothing, which is why it needs only rules:read. It works on a disabled rule, so the intended sequence is create with enabled: false, test, then enable.

By default it reads up to 50 inbox threads from the last 30 days. For each thread it tests the newest message the mailbox received rather than sent, and threads that fail to load or hold only your own messages are skipped, so scanned can come in below limit. Pass --thread-ids to test specific threads from any folder instead, and days and limit are then ignored. A message an existing rule already moved out of the inbox is not in the default sample, and listRuns is the record of what really happened.

Read warnings before matched. field_unevaluable means a condition reads something stored mail no longer carries (envelope_from, header, list_id, delivered_to or message_size), so it never held here, and under negate it holds on everything. field_approximate flags attachment, hour and weekday conditions answered from stored data that can differ from delivery. body_encrypted means a body condition met mail whose body is sealed. forward_loop means a forward target leads back to this mailbox, and forward_unverified means the target is not hosted here, so the forwarded copy is rebuilt and loses its original DKIM signature.

Returns one page of the rule audit log, newest first. Each row is one rule matching one arriving message, with the actions that took effect and the ones that were refused.

Each row copies the rule's name at the moment it fired, so renamed and deleted rules still read correctly, and --rule-id works for a rule that no longer exists. --thread-id answers the other common question: why a particular message ended up where it did.

actions lists the action types that were applied, and failures lists refusals as type: reason. A non empty failures means the rule matched but the mailbox declined part of it, for example a reply suppressed because that sender was already answered in the last day, a forward to an address that has not confirmed, or a reject that could not be refused at SMTP and was filed as spam instead.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.