List all Proton folders and labels available over the Bridge. Call this first to learn exact folder/label names for filing and tagging.

Message counts plus UIDNEXT and UIDVALIDITY for a folder. UIDs are only valid within one UIDVALIDITY generation, so check this before acting on uids noted earlier.

Messages that have arrived since the last poll. The very first poll emits nothing and just records where the mailbox ends, so turning this on does not replay the backlog. Marks nothing as read.

Commit a checkpoint returned by poll_folder with advance=false. Repeating it is harmless.

Search a folder. Combine any of: text, from, subject, since (DD-Mon-YYYY), unread_only, flagged_only. Returns uids + envelopes, newest first. Set include_locations to also report which labels and folders each message carries.

Search every mailbox at once and collapse duplicates by Message-ID, reporting where each message lives. Use when you do not know which folder something is in.

Headers plus SPF/DKIM/DMARC verdicts and Proton metadata, for judging whether a message is what it claims to be. Pass raw=true for the unparsed header block.

Read the full headers and body text of one message by uid within a folder.

List a message's attachments, separating real DOCUMENTS from inline cid: images and PGP keys (hidden by default). Call before claiming a message has no attachment — read_message shows body text only and never reveals files.

Extract an attachment's TEXT inline — PDFs via pypdf, plus text/csv/json/ics/eml. Use for invoices, decks, reports. Binary/image types must use save_attachment instead.

Look at an image attachment. Returns it as a viewable image, which is the only way to see a photo or a scan when the client cannot read local files. Images only, use read_attachment for text and PDFs.

Write attachment(s) to disk and return the path(s). Use for images, scanned PDFs, or anything not text-extractable. EPHEMERAL by default — files self-delete after the TTL.

Immediately delete all ephemeral saved attachments. Call after reading a saved file so nothing lingers on disk.

Pull every message of a conversation from All Mail, showing which ones carry documents. ESSENTIAL: Proton's UI groups conversations but IMAP exposes single messages, so an inbox 'Re:' can look attachment-free while the thread's original holds the PDFs. Run this before concluding what a thread needs.

Mark many messages read/unread/starred in one pass. Far cheaper than one call per message.

Apply one existing label to many messages. Messages stay where they are.

File or Trash many messages at once. GATED: preview with dry_run=true, show the user, then call with confirmed=true.

Reply to one message with correct threading. Replies to the Reply-To address when there is one, so alias mail stays masked. Pass draft=true to save it for review, or confirmed=true to send.

Reply to everyone on a message, with your own addresses removed from Cc and duplicates dropped. Same draft and confirmation rules as reply.

Write a draft into the Proton Drafts folder. Never sends. For a reply, pass in_reply_to (the original Message-ID).

Replace a draft's contents. Threading headers are carried over, the new version is saved before the old one is binned. Omit a field to keep what the draft already had.

Move a draft to Trash. GATED. Nothing here deletes permanently.

Send a saved draft as written, then move it to Trash. GATED. Sender and recipient checks run again at send time.

Report how to unsubscribe from a message using its List-Unsubscribe header, and optionally send the email form. Reports only unless send=true. Web links are never fetched for you.

Mark a message read/unread or star/unstar.

Tag a message with an existing label. The message stays where it is.

Take a label off a message. The message itself stays where it is. GATED: removing a label ends in an expunge against the label mailbox, so confirm it or preview with dry_run=true first.

Take one label off many messages at once. The messages stay where they are. GATED, like remove_label.

File a message: move it into another folder (e.g. 'Folders/', 'Archive', 'Trash').

Create a new label or folder. GATED: it changes your folder and label structure, so confirm the exact name and type with the user, then call with confirmed=true.

Delete a label outright. Every message that carried it stays exactly where it is and simply loses the tag — no mail is deleted. Labels only; folders are where messages live and are not deletable here. GATED.

Delete several labels in one pass. Messages keep their place and lose the tags. Labels only, GATED.

Send a new email. GATED: the agent must show the user the exact To/Subject/Body, get an explicit yes, then call with confirmed=true. Never call unattended.

Forward an existing message to someone on demand. GATED like send: confirm recipient with the user, then call with confirmed=true.