Run Script Filter - Thunderbird Add-on

A minimal Thunderbird add-on that adds a "Run Script" action to mail filters. When an email matches your filter criteria, it executes an external script with email metadata as arguments.

Features

• Execute any script (Python, Bash, etc.) when emails arrive
• Pass email metadata as command-line arguments
• Works with Thunderbird 115 - 146+
• Lightweight (~330 lines of core code)

Installation

Option 1: Install from .xpi file

1. Download run-script-filter.xpi from this repository
2. Open Thunderbird
3. Go to Menu (☰) → Add-ons and Themes (or press Ctrl+Shift+A)
4. Click the gear icon (⚙️) → Install Add-on From File...
5. Select the downloaded run-script-filter.xpi
6. Click Add when prompted
7. Restart Thunderbird (required!)

Option 2: Build from source

git clone https://github.com/user/thunderbird-run-script-addon.git
cd thunderbird-run-script-addon
zip -r run-script-filter.xpi manifest.json background.js api/ content/

Then install the generated .xpi file as described above.

Verify Installation

1. Open Thunderbird's Error Console: Menu → Developer Tools → Error Console (or Ctrl+Shift+J)
2. Look for: Run Script Filter: Filter action registered successfully!
3. Go to Tools → Message Filters → Select account → New...
4. In "Perform these actions", you should see "Run Script" in the dropdown

Usage

Creating a Filter

1. Go to Tools → Message Filters
2. Select an email account
3. Click New...
4. Set filter name (e.g., "Process Incoming Emails")
5. Set conditions:
   • For testing: Select "Match all messages"
   • For production: Set specific criteria
6. Under Perform these actions, select "Run Script"
7. Enter the action value (see format below)
8. Click OK to save

Action Value Format

/absolute/path/to/script,arg1,arg2,arg3,...

Examples:

# Simple - just run a script
/home/user/scripts/notify.sh

# With email variables
/home/user/scripts/process.py,@SUBJECT@,@AUTHOR@,@MESSAGEID@

# Trigger incremental email processing
/home/user/projects/rag-system/scripts/process_emails.py,--incremental

Available Variables

Variable	Description	Example Value
@SUBJECT@	Email subject line	"Meeting tomorrow"
@AUTHOR@	From address (full)	"John Doe john@example.com"
@MESSAGEID@	Message-ID header	"abc123@mail.example.com"
@RECIPIENTS@	To addresses	"user@example.com"
@CCLIST@	CC addresses	"cc@example.com"
@DATE@	Human-readable date	"Mon Jan 15 2024 10:30:00 GMT+0000"
@DATEINSECONDS@	Unix timestamp	"1705315800"
@MESSAGEURI@	Thunderbird internal URI	"mailbox://..."
@FOLDERNAME@	Folder name	"INBOX"
@ACCOUNT@	Account name	"imap.gmail.com"

Testing

Quick Test

1. Create a test script:

#!/bin/bash
# Save as: ~/test-email-filter.sh
echo "$(date): Email received" >> ~/email-filter-log.txt
echo "  Subject: $1" >> ~/email-filter-log.txt
echo "  From: $2" >> ~/email-filter-log.txt

2. Make it executable:

chmod +x ~/test-email-filter.sh

3. Create a filter with action value:

/home/YOUR_USERNAME/test-email-filter.sh,@SUBJECT@,@AUTHOR@

4. Test the filter:

   • Select an email in Thunderbird
   • Go to Tools → Run Filters on Selected Messages

5. Check the log:

cat ~/email-filter-log.txt

Python Test Script

#!/usr/bin/env python3
# Save as: ~/test-email-filter.py
import sys
from datetime import datetime

with open("/tmp/email-filter-log.txt", "a") as f:
    f.write(f"\n{'='*50}\n")
    f.write(f"Time: {datetime.now()}\n")
    for i, arg in enumerate(sys.argv):
        f.write(f"  Arg {i}: {arg}\n")

Troubleshooting

"Run Script" not appearing in filter actions

1. Restart Thunderbird after installing the add-on
2. Check Error Console (Ctrl+Shift+J) for errors
3. Verify the add-on is enabled in Add-ons Manager

Script not running

Issue	Solution
Script not found	Use full absolute path (not ~ or relative)
Permission denied	Make executable: chmod +x /path/to/script
No output	Add shebang: #!/usr/bin/env python3 or #!/bin/bash
Still not working	Check Error Console for Run Script Filter: messages

Debug Tips

Add this to your script to verify it's being called:

#!/usr/bin/env python3
import sys
with open("/tmp/debug.txt", "a") as f:
    f.write(f"Called with: {sys.argv}\n")

How It Works

┌─────────────────────────────────────────────────────────────┐
│                     THUNDERBIRD                              │
├─────────────────────────────────────────────────────────────┤
│  1. Add-on loads background.js                              │
│  2. WindowListener injects code into messenger window       │
│  3. DomContentScript patches filter editor UI               │
│  4. Custom filter action "Run Script" is registered         │
│  5. When filter matches → nsIProcess executes your script   │
└─────────────────────────────────────────────────────────────┘

File Structure

thunderbird-run-script-addon/
├── manifest.json              # Add-on metadata & permissions
├── background.js              # Registers WindowListener & DomContentScript
├── api/
│   ├── WindowListener/        # Injects scripts into TB windows
│   │   ├── implementation.js
│   │   └── schema.json
│   └── DomContentScript/      # Patches filter editor UI
│       ├── implementation.js
│       └── schema.json
├── content/
│   ├── inject.js              # Loaded into messenger window
│   ├── runscript-filter.js    # Main filter action logic
│   └── filter-editor.js       # Adds text input to filter UI
├── run-script-filter.xpi      # Packaged add-on (ready to install)
├── test-script.py             # Example Python test script
└── test-script.sh             # Example Bash test script

Compatibility

Thunderbird Version	Status
115.x (ESR)	✅ Tested
128.x	✅ Tested
140.x+	✅ Should work

Credits

This add-on uses the WindowListener and DomContentScript experimental APIs from FiltaQuilla by R Kent James and Axel Grude.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

This add-on incorporates code from FiltaQuilla (GPL-3.0), specifically the WindowListener and DomContentScript experimental APIs.

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.