Skip to content

Filter Rules & Automation

Filter Rules & Automation

DodaMail includes a deterministic, client-side Filter Rules Engine (rules.ts). Rules allow you to automatically sort, label, star, archive, or forward incoming messages based on complex criteria without relying on server-side proprietary features.

The Rule Builder Architecture

To access rules, navigate to Settings -> Rules. Here you can inspect all active automation routines, toggle rules on or off, adjust rule execution precedence, or create new filters.

Rule Precedence & Execution Order

Rules evaluate sequentially from top to bottom. You can use the Move Up (▲) and Move Down (▼) arrow buttons next to each rule to adjust execution order. If a rule specifies a terminal action (such as moving to Trash or Spam), processing terminates for that message unless configured otherwise.

Creating a New Filter Rule

Click + Create New Rule to open the Rule Builder dialog:

Control-by-Control Breakdown of Rule Configuration

Control Name Control Type Default State Description & Behavior
Rule Name Text Input Empty A descriptive title for your rule (e.g., Sort Invoices to Accounting, Flag Jira Alerts, Mute Marketing Newsletters).
Rule Active Toggle Switch Toggle Enabled (On) Quickly enable or disable the rule without deleting its underlying condition logic.
Match Logic Selector Radio / Segmented Match ALL (AND)
  • Match ALL (AND): Every defined condition must evaluate to true for actions to trigger.
  • Match ANY (OR): If any single condition matches, actions trigger immediately.
Apply to Incoming Mail Checkbox Checked When enabled, runs automatically against every new message during IMAP synchronization.

Condition Builder Controls

You can stack multiple conditions to pinpoint specific incoming messages:

Control Type Available Options Description
Field Selector Dropdown From
To
Cc
Subject
Body
Has Attachments		 The component of the email header or payload to evaluate.
Operator Selector Dropdown Contains
Does not contain
Equals exactly
Starts with
Ends with
Matches Regex		 The comparison method. Matches Regex supports standard POSIX/ECMAScript regular expressions for advanced pattern matching.
Value Input Text Input Empty The exact string, keyword, or regex pattern to search for (e.g., [CRITICAL], @github.com, invoice).
"+ Add Condition" Button Enabled Adds another condition row to the evaluation criteria.
Remove Condition (Trash) Button Enabled Removes that specific condition row.

Action Builder Controls

When a message satisfies your condition criteria, DodaMail executes all configured actions:

Action Type Parameters Required Description
Move to Folder Target Folder Dropdown (Archive, Spam, Trash, Projects, etc.) Moves the conversation out of the primary Inbox into the designated folder.
Apply Label Label Dropdown (Finance, Urgent, Dev, etc.) Tags the message with a colored visual label without removing it from its folder.
Star Message Toggle / State (Add Star or Remove Star) Flags the thread with a high-priority follow-up star.
Mark as Read Action Marks the thread read immediately, suppressing unread notification badges.
Mark as Spam Action Classifies the thread as junk and moves it to the Spam folder.
Forward to Email Destination Email Address Transparently forwards a copy of the incoming message to another email address via your default SMTP server.
Play Sound Alert Audio Chime Dropdown (Chime, Ping, Subtle Bell) Plays an audible desktop alert when this rule triggers.

Manual Execution: “Run Rule Now on Folder”

Rules don’t just apply to new incoming mail; you can retroactively organize existing mailboxes:

  1. In Settings -> Rules, select any rule and click the Run Now (Play Icon) button.
  2. Select the target folder to process (e.g., Inbox or All Inboxes).
  3. Click Execute: DodaMail scans the selected folder against the rule’s criteria and outputs a progress modal displaying how many threads matched and were updated.

Gmail Filter XML Importer (gmailFilterImporter.ts)

If you are migrating to DodaMail from Gmail, you don’t need to rebuild your filter rules manually. DodaMail includes a built-in Gmail Filter XML Importer.

Migration Procedure:

  1. In Gmail, navigate to Settings -> Filters and Blocked Addresses.
  2. Select your desired filters and click Export. This downloads a mailFilters.xml file.
  3. In DodaMail, go to Settings -> Rules and click Import from Gmail XML.
  4. Select the downloaded mailFilters.xml file.
  5. DodaMail parses the XML schema, translates Gmail search criteria into DodaMail conditions, maps Gmail labels to DodaMail tags, and presents a Review & Confirm Dialog.
  6. Click Confirm Import: All filters are converted into native DodaMail rules and immediately activated.