Search the user's mail. Combine full_text with any filters below.

full_text uses Thunderbird's global index and searches headers and bodies of already-indexed messages; subject/author/body are substring matches evaluated per folder. Dates are ISO-8601. Results are summaries — call mail_get for a body. Continue with cursor=nextCursor.

List messages in one folder, newest first by default.

Use folder_list to discover folder ids. For anything selective, prefer mail_search.

Read one message. text gives headers plus the plain-text body.

summary skips the body entirely; full adds the MIME part tree and every header. Encrypted mail is decrypted when Thunderbird can.

Read up to 50 messages in one round trip — for triaging a search result.

Fetch a message's raw RFC 5322 source, for header forensics.

On IMAP this needs the message to be available offline; the tool says so rather than returning a partial.

List a message's attachments with part names, sizes and content types.

Write one attachment to a directory on this machine.

part_name comes from mail_attachments. Refuses to clobber an existing file unless overwrite=true.

Set read/flagged/junk state or adjust tags on one or more messages.

Cheap and reversible, so no confirmation is required. Tag keys come from mail_tags.

Move messages into another folder.

On IMAP the move is asynchronous — the tool waits for Thunderbird to confirm before returning, so a following search reflects the change.

Copy messages into another folder, leaving the originals in place.

Archive messages using each account's configured archive layout.

Delete messages. Moves to Trash unless permanent=true.

A permanent delete cannot be undone from Thunderbird, so prefer the default and let the user empty Trash themselves.

List the tags defined in Thunderbird, with keys, labels and colours.

Create a tag, or recolour/rename an existing one.

color is #RRGGBB. Omit key to create a new tag; pass an existing key to update it.

Remove a tag definition. Messages keep the raw keyword but lose the label.

List mail folders with their ids and message counts.

With no filters this browses: every account's root folder plus one level below it. Raise depth to walk further, or give a filter — name is a case-insensitive substring — and the whole tree is searched instead. Pass tree=true to get folders nested under children rather than flat.

Counts come from Thunderbird's own folder database. On IMAP that database can lag until the folder has been selected once in Thunderbird, so treat unread and total counts as close rather than exact.

Get one folder: counts, special use, flags and IMAP quota.

Use this to re-check a count after a move or a delete; folder_list is the cheaper way to find the id in the first place.

Report what may be done to a folder before attempting it.

Answers whether the folder can hold messages, take subfolders, be renamed, be deleted, or have messages deleted from it. Worth a call before offering the user a plan that a server would refuse.

Get the unified folder that spans every account, e.g. all inboxes at once.

Its id works anywhere a folder id is accepted, so mail_list on the unified inbox lists new mail across all accounts in one call.

Create a folder inside another folder, or at the top of an account.

Rename a folder, keeping its messages and subfolders.

Move a folder under a different parent, with its subfolders.

destination_id is the new parent folder — use an account's root folder to move it to the top level. Across accounts this copies then deletes, which on IMAP can take a while.

Copy a folder and its contents under another parent, leaving the original.

Delete a folder, its subfolders and every message in them.

Thunderbird moves the folder to Trash unless it is already inside Trash, in which case it goes for good. Check folder_get first if the count matters — the reply reports what was removed, but cannot put it back.

Mark every message in a folder as read.

There is no per-message undo for this, which is why it asks first. On IMAP the flags are pushed to the server.

Add or remove a folder from the user's favourites.

Cosmetic and reversible — it only affects the folder pane's Favourites view, so it is not gated. Prompting for something this harmless would only train the user to click through the prompts that do matter.

Permanently delete everything in one account's Trash.

This is not recoverable from Thunderbird. Give account_id and the account's configured Trash is used; give folder_id to empty a specific one. Subfolders of Trash are removed too unless remove_subfolders=false.

Permanently delete everything in one account's Junk folder.

Subfolders of Junk are emptied but kept, since they are usually filter targets the user set up deliberately. Not recoverable.

Fetch an IMAP folder's message bodies so they are available offline.

This is what mail_get_source needs before it can return raw source for an IMAP message. A large folder means a long download and real network traffic.

Reclaim the disk space left behind by deleted messages.

Deleted mail stays in the message store until the folder is compacted. Pass folder_id for one folder or account_id for all of an account's. Nothing readable is lost, but the store is rewritten, so do not interrupt it.

Write a message. Saves a reviewable draft unless mode="send".

mode="later" queues it in the Outbox instead. Recipients are one address per list entry. attachments are paths to files on this machine. A draft still asks for confirmation, because the identical call with mode="send" would deliver it. Set reply_to_message_id to thread the message under an existing one — but mail_reply is usually what you want, since it also quotes.

Reply to a message. Saves a reviewable draft unless mode="send".

Thunderbird derives the recipients, the subject and the quoted original; body goes above the quote. reply_all copies everyone, reply_to_list answers the mailing list. Passing cc replaces the addresses Thunderbird derived, so leave it unset unless that is the intent.

Forward a message. Saves a reviewable draft unless mode="send".

inline quotes the original in the body; attachment attaches it as a .eml, which preserves the headers a recipient may need. body is your covering note and goes above the forwarded text.

Save a message without sending it, as a draft or a template.

Nothing leaves the machine, so this is not gated — a draft is exactly the thing to produce when you want the user to review before anything is sent. A template is the reusable kind: Thunderbird keeps it in Templates and opens a copy when the user picks it. Recipients are optional here, unlike a send.

Open a populated compose window for the user to finish by hand.

The right answer whenever the wording matters more than the automation, or when the user declined a send: they get the draft in front of them with the cursor in it. Nothing is sent or saved, and the user sees the window appear, so this is not gated.

List messages sitting in the Outbox, unsent.

An empty list is the normal answer. Anything here was queued with mode="later", or written while Thunderbird was offline, and will go out on the next 'Send Unsent Messages'.

Ranked full-corpus search across every indexed folder and account.

Best for open questions — "what did we agree about the shipment", "anything from the accountant about VAT". Results carry a relevance score and a conversation id you can pass to search_conversation. For precise filters (one folder, unread only, a date range) use mail_search instead.

If this returns nothing unexpectedly, call search_index_status: the global indexer can be disabled or still catching up.

Every message in one thread, oldest first, across folders and accounts.

Give either a message_id from mail_search or an RFC header_message_id. This is how you reconstruct a discussion that spans Inbox, Sent and an archive folder without three separate searches.

Whether Thunderbird's global index is enabled, and how far along it is.

Call this to explain an empty search_global result. When indexing is off, mail_search with subject/author/body filters still works.

List the saved searches (virtual folders) and what each one matches.

Create a saved search that appears in the folder pane.

search_folder_ids are folders to look in (from folder_list). Each term is {"attribute": "subject", "operator": "contains", "value": "invoice"}; attributes and operators are listed in the error message if you get one wrong. match_all=false makes the terms OR together. online_search asks the IMAP server to run the search instead of using the local database.

Nothing is copied or moved — a saved search is a stored query.

Redefine an existing saved search, by name or uri.

Only what you pass is replaced; terms replaces the whole condition list rather than merging, because a partial merge has no sensible meaning for a boolean query.

Remove a saved search. The messages it listed are not touched.

A saved search only stores a query, so deleting one loses the query and nothing else — but the query itself is not recoverable, hence the prompt.

Whether Thunderbird is attached, and which halves of the add-on loaded.

Answered by the local daemon, so it works when Thunderbird is closed. Call it first whenever another tool reports that it cannot reach Thunderbird.

Block until Thunderbird attaches to the bridge, then report status.

Use it after tb_restart, or after asking the user to start Thunderbird. Fails with a message naming what is missing if nothing attaches in time.

Read buffered Thunderbird notifications: new mail, folder and account changes.

Poll with since=latestSeq from the previous call to see only what is new. The daemon keeps a few hundred events, so a long gap between polls can drop some — latestSeq jumping by more than you received is how you tell.

One report: versions, profile, which capabilities loaded, accounts, indexing.

The first thing to fetch when anything behaves oddly. It includes whether this build permits unsigned add-ons and experiment APIs, which is what explains a half-installed bridge, and the message store type per account.

Recent lines from Thunderbird's error console, newest last.

Narrow it with contains — tbmcp shows this bridge's own complaints, and an add-on id or a source filename shows someone else's. Anything shaped like a password or token is redacted inside Thunderbird before it is sent.

List installed add-ons with their enabled and signature state.

isBridge marks this server's own add-on. A signedState of 0 is expected for it: the bridge is installed unsigned, which this Thunderbird permits.

Restart Thunderbird. Every call in flight fails, including other clients'.

The bridge connection drops, so this returns before the restart happens and the result says nothing about whether it succeeded — wait with tb_wait afterwards. Unsent compose windows and unsaved drafts are lost, so ask the user before you do it; a stuck sync usually does not need it.