- name
- thunderbird
- description
- Read and search local Mozilla Thunderbird mail storage on disk. Use when working with Thunderbird profiles, extracting emails from local folders or IMAP cache, locating messages by sender/recipient/subject/body, checking which account a mailbox belongs to, or answering inbox questions for a specific Thunderbird account such as "do I have unread mail today?" or "search mail for user@example.com".
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
- Detect available profiles:
- python scripts/search_thunderbird.py --list-profiles
- List accounts in one profile:
- python scripts/search_thunderbird.py --profile default-release --list-accounts
- Search one mailbox account directly:
- python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --query invoice --limit 10
- Narrow content search when needed:
- --subject-only to search only the subject line - --body-only to search only the body/preview text - --exclude <text> to remove noisy matches
- Return only unread inbox messages when needed:
- python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --unread-only --limit 20
- 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-accountsto inspect the profile--account <email-or-fragment>to restrict work to one Thunderbird account--folder inbox|sent|archive|drafts|junk|trash|spamto 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/andnew/ - 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-profilesList accounts inside a profile
python scripts/search_thunderbird.py --profile default-release --list-accountsSearch one account inbox by keyword
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --query contract --limit 20Find messages from a sender inside one account
python scripts/search_thunderbird.py --profile default-release --account user@example.com --from billing@example.com --limit 20Find messages by subject fragment and return JSON
python scripts/search_thunderbird.py --profile default-release --account user@example.com --subject invoice --json --limit 20Return only unread inbox messages
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --unread-only --limit 20Search only in subject or only in body
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --query invoice --subject-only --limit 20
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --query password --body-only --limit 20Exclude noisy matches
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --query update --exclude wordpress --limit 20Find messages with attachments or save them
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --has-attachment --list-attachments --limit 20
python scripts/search_thunderbird.py --profile default-release --account user@example.com --attachment-name invoice --save-attachments .\out --limit 20Sort messages by sender or subject
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --sort-by from --sort-order asc --limit 20Filter messages by time range
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --since 2026-01-01 --until 2026-01-02T08:00:00+01:00 --sort-by date --sort-order desc --limit 20Use day shortcuts
python scripts/search_thunderbird.py --profile default-release --account user@example.com --folder inbox --yesterday --sort-by date --sort-order desc --limit 20Extract full body text for a narrow match
python scripts/search_thunderbird.py --profile default-release --account user@example.com --query "reset password" --show-body --limit 5Interpretation rules
- Treat
.msffiles as indexes, not message sources. - Prefer the raw mbox file when a mailbox file and
.msfboth 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
--accountbefore broader searches. --unread-onlydepends on Thunderbird folder indexes (.msf) for mbox folders; if unread state is unavailable, say so instead of guessing.--sinceand--untilacceptYYYY-MM-DDor ISO-8601 timestamps. Bare--sincedates are interpreted as UTC midnight, while bare--untildates are interpreted as UTC end-of-day.--todayand--yesterdayare UTC-based shortcuts and cannot be combined with--sinceor--until.--subject-onlyand--body-onlyonly change how--queryis matched; do not combine them with each other.--has-attachmentfilters to messages with attachments;--attachment-namefilters by attachment filename.--save-attachments <dir>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 <dir> - 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.