Thunderbird

Use Thunderbird's local profile data as the source of truth for offline mail inspection. Prefer read-only access and search the raw local storage directly rather than relying on UI automation.

Run the bundled script from the skill directory, or use an absolute path resolved from the skill root:

• python scripts/search_thunderbird.py ...

If the current working directory is not the skill directory, resolve scripts/search_thunderbird.py relative to this SKILL.md location before running it.

Quick start

1. Detect available profiles:
   • python scripts/search_thunderbird.py --list-profiles
2. List accounts in one profile:
   • python scripts/search_thunderbird.py --profile default-release --list-accounts
3. Search one mailbox account directly:
   • python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --query invoice --limit 10
4. Narrow content search when needed:
   • --subject-only to search only the subject line
   • --body-only to search only the body/preview text
   • --exclude \x3Ctext> to remove noisy matches
5. Return only unread inbox messages when needed:
   • python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --unread-only --limit 20
6. Extract, filter, or sort more when needed:
   • --show-body
   • --unread-only
   • --subject-only
   • --body-only
   • --exclude wordpress
   • --has-attachment
   • --attachment-name invoice
   • --list-attachments
   • --save-attachments ./out
   • --today
   • --yesterday
   • --since 2026-03-11
   • --until 2026-03-12T08:00:00+01:00
   • --sort-by date|from|subject|to
   • --sort-order asc|desc
   • --json

Workflow

1. Pick the profile

Use --list-profiles first if the profile is unknown. The script now checks common Thunderbird profile roots on Windows and Linux automatically. Accept either:

• absolute profile path
• exact profile directory name
• unique profile-name fragment

If multiple profiles match, stop and choose explicitly.

2. Pick the account when possible

For account-specific requests, do not scan every mailbox first.

Use:

• --list-accounts to inspect the profile
• --account \x3Cemail-or-fragment> to restrict work to one Thunderbird account
• --folder inbox|sent|archive|drafts|junk|trash|spam to narrow further

This is usually both faster and easier than scanning the whole profile.

3. Search local storage

Use scripts/search_thunderbird.py for most tasks. It scans common Thunderbird storage roots:

• Mail/
• ImapMail/

It supports:

• mbox folders such as Inbox, Sent, Archives
• Maildir folders containing cur/ and new/
• common profile discovery on Windows and Linux (%APPDATA%/Thunderbird/Profiles, ~/.thunderbird, ~/.mozilla/thunderbird)

4. Return useful results

By default, summarize:

• source mailbox path
• date
• from
• to
• subject
• body preview

Prefer focused summaries for the user. Use --show-body only when the full message text is necessary.

Common tasks

List profiles

python scripts/search_thunderbird.py --list-profiles

List accounts inside a profile

python scripts/search_thunderbird.py --profile default-release --list-accounts

Search one account inbox by keyword

python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --query contract --limit 20

Find messages from a sender inside one account

python scripts/search_thunderbird.py --profile default-release --account [email protected] --from [email protected] --limit 20

Find messages by subject fragment and return JSON

python scripts/search_thunderbird.py --profile default-release --account [email protected] --subject invoice --json --limit 20

Return only unread inbox messages

python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --unread-only --limit 20

Search only in subject or only in body

python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --query invoice --subject-only --limit 20
python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --query password --body-only --limit 20

Exclude noisy matches

python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --query update --exclude wordpress --limit 20

Find messages with attachments or save them

python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --has-attachment --list-attachments --limit 20
python scripts/search_thunderbird.py --profile default-release --account [email protected] --attachment-name invoice --save-attachments .\out --limit 20

Sort messages by sender or subject

python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --sort-by from --sort-order asc --limit 20

Filter messages by time range

python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --since 2026-01-01 --until 2026-01-02T08:00:00+01:00 --sort-by date --sort-order desc --limit 20

Use day shortcuts

python scripts/search_thunderbird.py --profile default-release --account [email protected] --folder inbox --yesterday --sort-by date --sort-order desc --limit 20

Extract full body text for a narrow match

python scripts/search_thunderbird.py --profile default-release --account [email protected] --query "reset password" --show-body --limit 5

Interpretation rules

• Treat .msf files as indexes, not message sources.
• Prefer the raw mbox file when a mailbox file and .msf both exist.
• Remember that IMAP results reflect cached local messages, not necessarily the full server mailbox.
• If a message is not found, mention that local Thunderbird storage may not contain it or may not have synced it.
• When the user names an email address, prefer --account before broader searches.
• --unread-only depends on Thunderbird folder indexes (.msf) for mbox folders; if unread state is unavailable, say so instead of guessing.
• --since and --until accept YYYY-MM-DD or ISO-8601 timestamps. Bare --since dates are interpreted as UTC midnight, while bare --until dates are interpreted as UTC end-of-day.
• --today and --yesterday are UTC-based shortcuts and cannot be combined with --since or --until.
• --subject-only and --body-only only change how --query is matched; do not combine them with each other.
• --has-attachment filters to messages with attachments; --attachment-name filters by attachment filename.
• --save-attachments \x3Cdir> writes matching attachments to disk and implicitly enables attachment-aware filtering when needed.

Attachment interaction policy

When the user asks for an attachment, do not save or open it immediately unless they already said what they want done.

Default follow-up:

• Should I save it or open it?

If the user says save:

• ask where to save it if they did not already specify a location
• then use --save-attachments \x3Cdir>
• return the final saved path(s)

If the user says open:

• first extract the attachment to a temporary or user-requested location
• then open it with the system default app from the CLI
• prefer the platform default opener instead of inventing app-specific commands
• mention the file path you opened

If the attachment is text-like and the user likely wants contents rather than launching an external app, it is also acceptable to read or summarize it directly after asking.

Reference

Read references/storage-layout.md when you need a quick map of Thunderbird's on-disk structure.