List all mail folders in the Yandex mailbox.

Returns list of folders with:

• name: Human-readable folder name (decoded from IMAP UTF-7)

• imap_name: Raw IMAP folder name (use this for other operations like search_emails)

• attrs: IMAP folder attributes, e.g. ["\HasNoChildren", "\Trash"]

Search emails in a folder.

IDs returned are IMAP UIDs (stable within a folder's UIDVALIDITY), not sequence numbers — they will not change after other messages are deleted.

Args: folder: Mailbox folder (default: INBOX). Use list_folders() to see available folders. Accepts either ASCII names, raw IMAP names from list_folders(), or human-readable non-ASCII names (e.g. "Корзина") — the latter are auto-encoded to IMAP modified UTF-7. query: IMAP search query. Examples: - "ALL" - all emails - "UNSEEN" - unread emails - "FROM sender@example.com" - from specific sender - "SUBJECT hello" - subject contains "hello" - "SINCE 01-Dec-2024" - emails since date - "BEFORE 31-Dec-2024" - emails before date - Can combine: "UNSEEN FROM boss@company.com" limit: Maximum number of emails to return (default: 20) offset: Number of newest-first results to skip, for pagination (default: 0)

Returns list of email summaries with id (UID), subject, from, date.

Read full email content by ID.

Args: folder: Mailbox folder containing the email email_id: Email ID from search_emails() result

Returns email with subject, from, to, date, body_text, body_html, attachments list.

Download an email attachment to disk.

Args: folder: Mailbox folder containing the email email_id: Email ID from search_emails() result filename: Attachment filename to download (from read_email attachments list) save_dir: Directory to save the file (default: ~/Downloads)

Returns dict with saved file path and size.

Send an email via Yandex SMTP.

Args: to: Recipient email address (comma-separated for multiple) subject: Email subject body: Email body (plain text or HTML based on html flag) cc: CC recipients (optional, comma-separated) bcc: BCC recipients (optional, comma-separated) html: If True, body is treated as HTML (default: False) attachments: Optional list of absolute file paths to attach. Each attachment is resolved and must be a regular file. SECURITY: this tool can read any file accessible to the MCP server process and exfiltrate it via email — the MCP client should surface every send_email call for user approval. All attached paths are logged to yandex_mail_mcp.log for audit. save_to_sent: If True (default), append a copy of the sent message to the Sent folder via IMAP APPEND. Yandex does not reliably auto-save SMTP-sent messages to Sent; this ensures a copy exists. Failure to save is non-fatal and logged as a warning.

Returns confirmation with recipients, attached file names, and saved_to_sent (decoded Sent folder name or None).

Move an email to another folder.

Args: folder: Source folder containing the email email_id: Email ID to move destination: Destination folder name

Returns confirmation of move.

Delete an email (move to Trash).

Trash folder is discovered via the IMAP \Trash SPECIAL-USE attribute (RFC 6154) with fallbacks to common localized names. If no trash folder is found or copy fails, the email is permanently deleted.

Args: folder: Folder containing the email email_id: Email ID to delete

Returns confirmation of deletion.

Set or clear IMAP flags on a message.

Common IMAP system flags (backslash-prefixed): \Seen, \Flagged, \Answered, \Draft, \Deleted. Custom user keywords have no backslash.

Args: folder: Folder containing the email email_id: UID of the email (from search_emails result) add: Flags to add (e.g. ["\Seen", "\Flagged"]) remove: Flags to remove

Returns confirmation with the flags added/removed.

Mark an email as read (adds \Seen).

Mark an email as unread (removes \Seen).

Star or unstar an email via the \Flagged IMAP flag.

Mark an email as answered (adds \Answered).

Get counts and state for a folder via IMAP STATUS (RFC 3501).

Returns dict with keys (when available):

• folder: input folder name

• messages: total messages

• unseen: unread messages

• recent: recent messages

• uidnext: next UID to be assigned

• uidvalidity: UID validity identifier (if this changes, stored UIDs are no longer valid and must be re-fetched)

Create a new mail folder. Name can be human-readable (Cyrillic supported — auto-encoded to IMAP modified UTF-7).

Rename a mail folder. Both names are auto-encoded to UTF-7.

Delete a mail folder.

WARNING: This is destructive. Behavior on non-empty folders is server-dependent (RFC 3501 §6.3.4 permits servers to return NO); some servers reject the operation, others delete the contents without moving them to Trash. The MCP client should surface this call for user approval.

Reply to an email with correct threading headers (RFC 5322).

Fetches the original message's Message-ID, References, Subject, From, Reply-To, To and Cc headers, and builds a reply with:

• In-Reply-To pointing at the original Message-ID

• References chaining the previous thread plus the original Message-ID

• Subject with a deduped "Re: " prefix

• Recipients: original Reply-To (or From); if reply_all, also original To + Cc with our own address removed

Args: folder: Folder containing the original email email_id: UID of the email to reply to body: Reply body text (plain or HTML) reply_all: If True, include original To + Cc recipients html: If True, body is HTML attachments: Optional list of file paths to attach save_to_sent: If True (default), save the reply to the Sent folder

Forward an email to new recipients.

Unlike reply_email, this is a new thread: no In-Reply-To or References headers are set, and the subject gets a deduped "Fwd: " prefix.

Args: folder: Folder containing the original email email_id: UID of the email to forward to: Forward recipients (comma-separated) body: Optional introduction text prepended to the forwarded content cc: CC recipients (comma-separated) bcc: BCC recipients (comma-separated) html: If True, intro body is HTML (affects inline display only) attachments: Additional files to attach alongside the original as_attachment: If True (default), original message is attached as message/rfc822 (preserves all original headers and structure). If False, headers + body are inlined as quoted text in the body. save_to_sent: If True (default), save a copy to the Sent folder

Set or clear IMAP flags on multiple messages in a single operation.

More efficient than looping set_flags: one UID STORE per chunk of ~500 UIDs, not one per message. Validates every flag the same way set_flags does (rejects flags with whitespace, parens, etc.).

Args: folder: Folder containing the messages email_ids: List of UIDs to update add: Flags to add (e.g. ["\Seen"]) remove: Flags to remove

Returns count of UIDs touched per add/remove operation.

Mark multiple emails as read (adds \Seen).

Mark multiple emails as unread (removes \Seen).

Star or unstar multiple emails via the \Flagged flag.

Move multiple messages to another folder in a single IMAP session.

Uses atomic UID MOVE (RFC 6851) in chunks when the server advertises it, falls back to COPY+STORE+EXPUNGE per chunk otherwise.

Delete multiple messages at once.

If permanent=False (default), moves to Trash (discovered via \Trash SPECIAL-USE with localized fallbacks). If permanent=True or no Trash folder is found, marks +FLAGS \Deleted and EXPUNGEs immediately.

Deleting from within the Trash folder is always permanent regardless of the flag.

Inspect an email's headers and MIME structure WITHOUT downloading bodies.

Uses FETCH BODYSTRUCTURE + header subset — returns in milliseconds even for huge messages with attachments. Ideal for:

• Previewing large emails without tying up bandwidth

• Deciding which attachment to download (see fetch_part)

• Bulk processing many messages efficiently

Returns subject/from/to/date/size plus a list of MIME parts, each with:

• part: part number (e.g. "1", "2", "2.1") — pass to fetch_part

• type: MIME type (e.g. "text/plain", "application/pdf")

• size: part size in bytes (may be None)

• charset: for text parts

• filename: for attachments (RFC 2231 / MIME decoded)

• disposition: "inline" or "attachment"

Fetch a specific MIME part of an email by part number.

Part numbers come from inspect_email's parts list (e.g. "1", "2.1"). For text parts with decode=True (default), returns the decoded string body. For binary parts or decode=False, returns base64-encoded bytes so the result is JSON-safe.

Args: folder: Folder containing the email email_id: UID of the email part_number: Part identifier from inspect_email (e.g. "1", "2.1") decode: If True, decode text parts to str; otherwise return base64

Returns dict with content (str or base64) + encoding marker.

Empty the Trash folder.

Discovers Trash via \Trash SPECIAL-USE with localized fallbacks, selects it, marks all messages +FLAGS \Deleted, and EXPUNGEs. Returns the count of deleted messages.

Get unread and total message counts across ALL selectable folders.

Iterates LIST, skips \Noselect folders, calls STATUS on each. Much more efficient than calling get_folder_status per folder from the client side because everything happens in one IMAP session.

Returns a dict keyed by human-readable folder name, each value containing {messages, unseen}. Also includes a _summary key with totals.