add-email-filter

name	add-email-filter
description	Add a new email filter from a screenshot. Use when: user shares a screenshot of an email and wants to add a filter rule, create a sieve filter, file/label mail, block sender, or sort emails into folders.
argument-hint	Attach a screenshot of the email to filter

Add Email Filter from Screenshot

Add a new filter entry to filters.js by extracting the sender address from a screenshot and filing it into the appropriate label.

Procedure

1. Extract Sender Info

From the attached screenshot, identify:

• Sender email address (the full From address)
• Sender name or organization (for the comment field)
• Subject line (only if needed to distinguish this filter from others with the same sender)

2. Determine Wildcard Pattern

Create the most general wildcard pattern that will match all emails from this sender:

Scenario	Pattern	Example
Single known address	exact address	[e-mail]
Unique domain, any local part	*@domain.com	*@sweetgreen.com
Subdomain varies (e.g. marketing subdomains)	*@*.domain.com	*@*.nordstrom.com
Both subdomain and local part vary	*@*.domain.com	*@*.chase.com

Prefer wildcards. Use *@domain.com or *@*.domain.com unless the domain is shared (e.g. gmail.com, outlook.com, yahoo.com, protonmail.com, icloud.com, hotmail.com, substack.com, ccsend.com, stripe.com). For shared domains, use the exact address.

3. Determine Label and Archive Behavior

Ask the user which label to file into if it's not obvious from context. Check existing sections in filters.js for the appropriate label. Common labels:

• Art, Birds, Cybersemics, Development, Dog, Education, Events, Family, Fashion, Film, Finance, Friends, Health, Legal, Products, Receipts, Taxes, Travel, Work

If the user doesn't specify whether the email should be archived, use the ask-questions tool to prompt them with these options:

• Categorize only — files into the label and keeps in inbox (e.g. ['Health'])
• Categorize and archive — files into the label and archives (e.g. ['Health', 'archive'])
• Trash — deletes the email

These correspond to different sections in filters.js (e.g. // Health vs // Health (archive)).

Compound labels are supported (e.g. ['Art', 'Legal'], ['Finance', 'archive']).

Special actions:

• ['archive'] — archive only (non-priority mail)
• ['trash'] — delete (spam-like mail that can't be unsubscribed)
• ['Label', 'archive'] — label + archive

4. Determine Placement

Filters are evaluated top-to-bottom, first match wins. Place the new entry:

• In the existing section for the target label
• If using a subject filter AND there's a more general wildcard for the same domain below, place it above that general rule
• Alphabetically within the section when no ordering constraint exists

5. Format the Entry

Use the simplest format that matches:

String shorthand (from-only, no subject, no comment needed):

'*@domain.com',

Object with from only:

{ comment: 'Sender Name', from: '*@domain.com' },

Object with from and subject:

{ comment: 'Sender Name - Context', from: '*@domain.com', subject: 'Subject fragment' },

Only include subject if needed to distinguish this filter from others or to target specific unwanted emails from an otherwise useful sender.

6. Check for Existing Filters

Before modifying filters.js, search the file for any existing filters that match the sender's domain name. Search for the bare domain (e.g. example.com) to catch exact addresses, *@domain.com, and *@*.domain.com patterns.

• If one or more matching filters already exist, list them to the user (showing the pattern, label/action, and section for each) and use the ask-questions tool to confirm whether to proceed before modifying filters.js.
• If no matching filter exists, continue to the next step.

7. Add to filters.js

Insert the new condition into the appropriate conditions array in filters.js. If no existing section matches the target label + action combination, create a new filter block following the existing pattern.

8. Confirm

After adding, summarize:

• The pattern used
• The label/action applied
• Where it was placed in the file

Do NOT commit to git. filters.js is gitignored.

9. Deploy

After confirming the change, deploy the updated filters by running npm run deploy.