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. A first page carries requestedScope and coverage. Requested folders are not proof that every message body is available or indexed.

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.

Read a saved draft and its revision without opening a composer.

Pass exactly one reference. Protected or oversized drafts return metadata with editable=false; a preview must never be used as a replacement body. Unsaved changes in an open Thunderbird window are not this saved snapshot.

Update the saved draft only if its reviewed revision is still current.

Omitted fields stay unchanged; an empty recipient list clears that field. Body replaces the complete body, including any signature, in its existing format. Sender identity cannot change. If the user's composer is open, return DRAFT_BUSY and leave the window for the user to save or close. Reuse request_key to retrieve an operation without applying it twice. changes accepts subject, body, to, cc, bcc, add_attachments and remove_attachment_refs. Separate fields are aliases; use one form only.

Send exactly the saved draft revision the user reviewed, or queue it.

A changed or open draft is refused. Reuse request_key after interruption; unknown means sending may have occurred and must not be retried with a new key. mode=later queues in Outbox, not at a scheduled date.

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 search of indexed mail, with stable snapshot pagination.

Start with query, optionally scoped to a folder. Continue with only cursor=nextCursor and limit; a snapshot expires after five minutes or a Thunderbird restart. offset remains for older callers. Coverage is indexed mail only, never a claim that the whole mailbox was searched. partialReasons explains retrieval limits or unavailable index terms. alternativeSearch suggests a literal subject search without running it or silently changing the original query's meaning. Older add-ons retain live offset pages with snapshotSupported=false.

Read a conversation oldest first, across indexed folders and accounts.

Start with one message identifier. Continue with only cursor=nextCursor and limit. A snapshot holds at most 1,000 messages and expires after five minutes; a truncated conversation is explicitly reported.

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.

Inspect a queued, completed or uncertain operation without repeating it.

List this profile's local, body-free operation history for the last seven days.

Stop steps not yet started. A send already dispatched cannot be recalled.

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.

Continue with cursor=nextCursor. gap and resyncRequired explain lost history; an old-session cursor is rejected. Legacy since=latestSeq is supported but cannot identify a previous daemon session.

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.

Lines the bridge writes with console.* (source: "console") are included alongside the error console's own entries, merged by time.

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.

Preview changes to up to 500 messages without changing mail.

A plan fixes the exact messages and expires after 15 minutes. Mark changes read/flagged state and tags; move supports concrete folders in one account. Any invalid message prevents applying the plan. History and undo metadata stay local for seven days; message bodies are never stored in the journal. changes accepts read, flagged, add_tags and remove_tags. The separate fields are aliases; do not combine them with a changes object.

Apply a preview once and return its operation id for tb_operation_status.

Repeating the same plan returns the existing operation, never a second job. Conflicts are reported per message. An uncertain outcome stops further work.

Undo confirmed batch changes whose touched fields have not changed again.

Messages changed by someone else are reported as conflicts. Unknown results are never guessed. Repeating the call returns the existing undo operation.

Find possible follow-ups using outgoing mail and indexed reply headers.

A candidate is not proof that a reply is required. By default inspect the last 30 days for conversations waiting at least seven days. Human replies close a conversation; automatic replies, mailing lists and self-only mail are excluded. Results name their evidence and incomplete coverage. No message is sent and no reminder is created. Continue with only cursor and limit; snapshots expire after five minutes.

Preview attachment downloads from up to 100 selected messages.

The existing absolute directory, source attachments and safe collision-free names are frozen for 15 minutes. Filters use filename substrings and exact MIME types, not PDF contents. Limits are 200 attachments, 25 MiB per file and 250 MiB total. Invalid selections must be corrected before saving.

Save a frozen attachment plan once, without overwriting existing files.

Returns an operation id for tb_operation_status. Repeating the same plan returns the existing job. Results identify each source, path and checksum; successfully written files are not automatically deleted on cancellation.