Inbox Rules Engine

Inbox Rules Engine

You've joined the Mail team. inbox is the server-side mailbox behind the web and mobile clients: it files incoming mail with user rules (filters) and serves the paged, newest-first message list. This sprint you have a pagination bug from support, then two features: rule priorities with "stop processing", and a conversation view with muting.

Codebase

How your code is run

run(operations: list) -> list creates an empty mailbox, executes each operation in order and returns one output per operation.

A delivered message is {"id": int, "from": str, "to": [str], "subject": str, "received_at": int, "has_attachment": bool} (to, subject, has_attachment optional). Addresses may be "Name <addr>"; matching uses the lower-cased address. Several messages can share a received_at second. New mail lands in "Inbox" before rules run.

Unknown operations return "error: unknown operation: <name>".

Rules (existing behaviour). A rule is {"name": str (optional), "when": {...}, "then": {...}}. All conditions in when must match: from_contains, to_contains (any recipient), subject_contains (case-insensitive substrings, non-empty strings) and has_attachment (bool). Actions in then: move (folder name), add_labels (non-empty list of strings), mark_read: true, star: true. Every matching rule runs, in creation order; labels accumulate and when several rules move a message the last one wins. Rules only run at delivery. Validation errors: "error: unknown rule field: <key>", "error: unknown condition: <key>", "error: unknown action: <key>", "error: invalid value for <key>", "error: rule needs at least one condition", "error: rule needs at least one action".

Listing order (every listing): newest received_at first; messages with the same received_at are ordered by id descending (compared as integers). page returns up to limit messages of the folder in that order. next_cursor is "<received_at>:<id>" of the last message on the page, or null when nothing follows it. Passing a cursor back returns the messages that come strictly after that position in listing order; the position stays valid even if that message has since been moved.

Worked example (T = 1767225600):

[["add_rule", {"name": "receipts", "when": {"subject_contains": "receipt"}, "then": {"move": "Receipts", "add_labels": ["finance"]}}],
 ["deliver", {"id": 1, "from": "Store <orders@shop.example>", "to": ["me@example.com"], "subject": "Your receipt", "received_at": 1767225600}],
 ["deliver", {"id": 2, "from": "bob@example.com", "to": ["me@example.com"], "subject": "Lunch?", "received_at": 1767225660}],
 ["deliver", {"id": 3, "from": "carol@example.com", "to": ["me@example.com"], "subject": "Q3 plan", "received_at": 1767225720}],
 ["page", "Inbox", 10, null],
 ["unread_count", "Receipts"]]

returns

["r1",
 {"folder": "Receipts", "labels": ["finance"], "read": false, "starred": false},
 {"folder": "Inbox", "labels": [], "read": false, "starred": false},
 {"folder": "Inbox", "labels": [], "read": false, "starred": false},
 {"ids": [3, 2], "next_cursor": null},
 1]

Part 1 — Scrolling shows some messages twice and skips others

Goal: make the listing order and cursor paging behave as specified above.

Support ticket: *"After a newsletter blast, everything arrived in the same second. When I scroll, a couple of messages show up twice, others never appear, and the order changes depending on when they were delivered."*

Example. Message 1 at T, messages 2, 3 and 4 at T+60, message 5 at T+120. Paging with limit 2: ["page", "Inbox", 2, null] → {"ids": [5, 4], "next_cursor": "1767225660:4"}, then ["page", "Inbox", 2, "1767225660:4"] → {"ids": [3, 2], "next_cursor": "1767225660:2"}, then ["page", "Inbox", 2, "1767225660:2"] → {"ids": [1], "next_cursor": null}.

Part 2 — Rule priorities and "stop processing more rules"

Goal: let users control the order rules run in and stop later rules from running.

Rules

1. A rule may include "priority" (integer, may be negative; default 100). Rules run in ascending priority; equal priorities run in creation order (r2 before r10). A rule without priority therefore behaves exactly as today.
2. A rule may include "stop" (boolean, default false). If a rule with stop: true matches, it applies its actions and no further rules run for that message. A stop rule that does not match has no effect.
3. explain lists only the rules that actually ran.
4. A non-integer (or boolean) priority returns "error: invalid value for priority"; a non-boolean stop returns "error: invalid value for stop".
5. New operation ["update_rule", rule_id, changes]: changes holds any of name, when, then, priority, stop; each given key replaces that field. The updated rule is validated with the same rules and messages as add_rule; if invalid, the error is returned and the rule is unchanged. Unknown rule_id returns "error: unknown rule". Returns true. Creation order never changes, and messages already delivered are not re-filed.

Example. r1 = from @corp.example → label work; r2 = subject urgent → star and move to Priority, priority: 10, stop: true; r3 = subject invoice → move to Finance. Delivering "URGENT: invoice overdue" from boss@corp.example returns {"folder": "Priority", "labels": [], "read": false, "starred": true} and explain gives ["r2"]. Delivering "Invoice for March" from billing@corp.example returns folder Finance with label work, and explain gives ["r1", "r3"].

Part 3 — Conversation view and mute (MAIL-221)

Goal: group a folder into conversations by subject and let users mute a conversation.

Rules

1. A message's *thread key* is its subject with every leading reply/forward prefix removed, then whitespace collapsed and lower-cased. A prefix is re, fw or fwd (any case) followed by optional spaces and a colon; any number of prefixes may be chained, with optional whitespace before each one. Then every run of whitespace becomes one space, the result is trimmed and lower-cased. "Re: RE: Fwd:Budget Q3" → "budget q3"; "FW : budget q3" → "budget q3"; "Reply: Budget" and "Meeting re: budget" keep their text (lower-cased).
2. ["threads", folder, limit] groups the messages currently in that folder by thread key and returns up to limit threads (1..100, else "error: invalid limit"), each {"subject": key, "ids": [...], "unread": n}. ids are in listing order; threads are ordered by their first message in listing order. unread counts unread messages in the thread.
3. Messages whose thread key is empty ("", "Re:", whitespace...) are never grouped: each is a thread on its own.
4. ["mute_thread", message_id] mutes that message's thread key. Every message with that key currently in "Inbox" (any message, not only the given one) is moved to "Archive" and marked read. Returns how many were moved. Messages in other folders are untouched. Unknown id → "error: unknown message". If the key is empty, only that message is affected and nothing is muted for the future.
5. When a message with a muted key is delivered, muting is applied after all rules have run: if the message is still in "Inbox" it moves to "Archive" and is marked read. A rule that moved it elsewhere wins, and a rule's stop does not prevent muting. Muting is not a rule and never appears in explain. deliver returns the final state.
6. Muting only acts at mute time and at delivery; moving a muted message back to Inbox by hand keeps it there.

Example. Deliver 1 "Budget Q3" (T), 2 "Re: budget q3" (T+60), 3 "Lunch?" (T+120), 4 "RE: Fwd: Budget Q3" (T+180). ["threads", "Inbox", 10] returns [{"subject": "budget q3", "ids": [4, 2, 1], "unread": 3}, {"subject": "lunch?", "ids": [3], "unread": 1}]. ["mute_thread", 2] returns 3. Delivering 5 "re:Budget Q3" then returns {"folder": "Archive", "labels": [], "read": true, "starred": false}, and threads now returns only the "lunch?" thread.

Notes

• conditions.py, actions.py and mailbox.parse_message are known-good.
• You may use the AI assistant freely. Say what you're asking it and check what it gives you.
• Later parts must not break earlier ones; hidden tests re-check Part 1 and 2 behaviour.
• The files in tests/ are not run by the grader. Use them, extend them, or ignore them.