inbox-automations

# Inbox Automations and Gmail Filters ## AI filter Use `apply-ai-filter` when the user manually marks mail as unwanted or keeps a message that was filtered. It adds or removes the reversible `agent-native-filtered` label, archives or restores the conversation, and records the feedback for future classification. User comments become editable natural-language AI filter instructions; the AI filter uses Luna when available, auto-filters only above its configured confidence threshold, and keeps lower-confidence matches in the review queue. It never claims the custom label is Gmail's provider-controlled Spam system label. ## Automation rules `manage-email-rules` rules match new inbound mail against a natural-language `condition` using AI. Label/archive/notify rules use the canonical `kind=ai-filter` path shared with Mail AI filter settings; mark-read, star, and trash rules keep legacy automation behavior. Mixed action sets remain legacy rules for compatibility. For a new AI rule, call `manage-email-rules` with `action: "create"`, one plain-language `sentence`, and `mode: "tag" | "important" | "notify" | "filter" | "archive"`; tag mode also takes `tagName`. The shared create path stores the AI rule, pins tag labels as inbox tabs, and queues bounded recent-mail application. Inspect existing rules and update a matching rule before creating a duplicate. Update a rule with its `id`, revised `sentence`, and `mode` (and `tagName` for a tag). The inbox-tab cog lists AI tags first; unchecking a tag only hides its tab and never deletes its rule. For a direct request to add or change one rule, make one `manage-email-rules` create/update call and report its structured result. It saves the rule and queues recent-mail application before returning; model availability and matching run in the background. Do not call the backfill/status action or `trigger-automations` to finish the same request. A queued result is a saved rule with work continuing in the background, not a reason to retry the rule mutation. For an AI rule that marks matching mail important, use the `agent-native-important` label without archiving. For unwanted mail, pair the `agent-native-filtered` label with archive; a plain archive request can use the archive action alone. Use `notify` mode to add the `agent-native-important` label and send a core notification for each matching new message. Recent-mail backfill applies the highlighting label only; it never sends notifications for historical matches. Mail's notification bell polls saved notifications while Mail is open and can show browser system popups after permission is enabled. This isn't offline web push. Mobile app notifications are coming soon. For other prompt-driven actions such as auto-replies, use an event-triggered automation on `mail.message.received`. Its payload includes `accountEmail` and `messageId`; pass both to `get-email` to read the exact message. Mail's existing send approval setting continues to gate automated sends. Creating or updating an enabled AI-filter rule queues a backfill over recent mail (at most 200 inbox threads from the last 14 days). A queued result has `appliedCounts: null` plus `backfillRunId` and `backfillStatus`; report it as queued, not completed. When the action returns per-rule `appliedCounts`, report those exact counts. `settingsHref` opens Mail's AI filter settings for review. Rules also process new inbound mail on the per-minute cron; `trigger-automations` forces immediate processing (debounced — a just-triggered run may report "skipped, try again in 30 seconds"). Priority sort uses enabled AI Important rules as its Jev instruction. Use `record-ai-priority-feedback` when the user says a specific email should or should not be important. It stores per-email important/not-important votes; Priority treats a vote as an explicit score override for that message. Use `refine-ai-filter` when the user supplies checked recent-email corrections for an existing AI-filter rule. It rewrites and saves that rule's condition, then queues the same bounded backfill and returns its run id/status and a Settings link; do not invent correction examples or report queued work as done. ## Gmail filters are a different mechanism Gmail filters (`manage-gmail-filters`) are a distinct, provider-native mechanism from automation rules — filters run inside Gmail itself, apply before automations, and support raw Gmail criteria/actions. Gmail has no filter-update endpoint: the `replace` operation works by creating a new filter and deleting the old one. Pick the mechanism deliberately: use a Gmail filter when the rule is expressible in Gmail's own criteria and should apply even when this app isn't running; use an automation rule when the condition needs natural-language judgement. ## Related Skills - `inbox-reads-and-triage` — one-off triage and refreshing the UI afterwards. - `mail-backends` — Gmail filters require a connected Google account.