Add a new IMAP account configuration

Update an existing IMAP account. Useful for fixing SMTP settings without removing and re-adding the account.

List all configured IMAP accounts

Remove an IMAP account configuration

Connect to an IMAP account

Disconnect from an IMAP account

Test an existing account connection without re-entering credentials. Validates IMAP connectivity and returns folder count and message count.

Search for emails matching criteria (sender, recipient, subject, body text, date range, read/flagged status). Use this to FIND messages when you know something about them but not their UID — e.g. "emails from amazon last week", "unread invoices". By default searches a single folder (INBOX). Set searchAllFolders=true to scan every mailbox at once — this catches messages filed away by rules (e.g. a receipt routed to a custom folder); Trash/Spam/Drafts are skipped unless you opt in. Returns lightweight headers (uid, from, subject, date, and folder when searching across folders); call imap_get_email with a returned uid + folder to read full content. For the newest messages without criteria, prefer imap_get_latest_emails.

Read the FULL content of a single email by its UID (body, sender/recipients, date, attachment list, optional raw headers and text-attachment previews). By default the body is returned as clean Markdown in markdownContent and raw HTML is omitted so it never crosses the boundary; set bodyFormat to "html" for the legacy raw htmlContent, or "text" for plain text only. Use after imap_search_emails or imap_get_latest_emails gives you a uid. Body text is truncated to maxContentLength to protect the context window — raise it for long messages. To fetch attachment bytes, use imap_download_attachment.

Upload a file to the server for use as an email attachment. Returns a path that can be used with imap_send_email attachments. This allows sending large attachments without hitting context window limits. Max size: 26214400 bytes (configurable via IMAP_MAX_UPLOAD_SIZE). Uploads are auto-deleted after 86400000 ms (configurable via IMAP_UPLOAD_TTL_MS).

Download a single attachment from an email (folder + uid + attachment filename/contentId, as listed by imap_get_email). Images are returned inline for viewing; PDFs are saved and their text is extracted inline (extractText); other files are saved to the shared downloads directory (or savePath). Use when the user wants the actual file contents, not just the message body.

Mark an email as read

Mark an email as unread

Delete ONE email by folder + uid (moves to Trash or expunges, server-dependent). Destructive and not easily undone — confirm the user means this specific message. To remove many at once use imap_bulk_delete (known uids) or imap_bulk_delete_by_search (by criteria, supports dryRun). To file an email away instead of deleting, use imap_move_email.

Move an email from one folder to another (e.g., INBOX to Taxes, or INBOX to Archive). Optionally creates the destination folder if it does not exist.

Delete multiple emails at once with chunking and auto-reconnection. Processes deletions in batches to prevent connection timeouts.

Search for emails matching criteria and delete them all. Useful for cleaning up spam or unwanted emails.

Get the most recent emails from a folder, newest first. Use this for "what just came in?" / "show my latest inbox messages" when no search filter is needed. Returns lightweight headers (uid, from, subject, date); read a specific one with imap_get_email. To filter by sender/subject/date instead, use imap_search_emails.

Compose and send a NEW email via the account's SMTP server (a copy is saved to Sent unless disabled). Use for fresh outbound messages. To respond to an existing message use imap_reply_to_email (keeps threading); to pass a message on use imap_forward_email; to store without sending use imap_save_draft. Supports to/cc/bcc, text and/or HTML, and attachments by base64 content or by file path (see imap_upload_file for large files).

Save an email as a draft in the Drafts folder (no send). Takes the same fields as imap_send_email.

Reply to an existing email identified by folder + uid. Automatically sets the recipient to the original sender, prefixes the subject with "Re:", and preserves threading (In-Reply-To/References). Set replyAll to also include the original recipients. Use this instead of imap_send_email whenever the user is responding to a message already in a mailbox.

Forward an existing email (folder + uid) to new recipients, quoting the original message and headers. Optionally include the original attachments. Use when the user wants to pass an existing message on to someone else; use imap_reply_to_email instead to respond to the sender.

Find messages in searchFolder that belong to the same conversation threads as messages already in sourceFolder. Useful for catching replies that arrived after a thread was sorted. Works on any IMAP server (uses RFC 3501 HEADER search on In-Reply-To and References).

Locate an email by its RFC822 Message-ID across folders and return its current { folder, uid } plus basic envelope. Robust to the message having been moved or archived (IMAP UIDs are folder-relative). Pass the returned folder + uid to imap_reply_to_email or imap_get_email. Without folders, searches Gmail \All Mail when present, else INBOX → Archive → Sent → remaining folders.

List all folders/mailboxes for an account (names, hierarchy delimiter, attributes). Use this first to discover exact folder names before searching, moving, or creating subfolders — folder naming varies by provider (e.g. "Archive" vs "[Gmail]/All Mail" vs "INBOX.Archive").

Get status information about a folder

Create a new IMAP folder/mailbox. Most servers also create any missing parent folders (e.g. creating "Archives/2026/2026-05" auto-creates "Archives" and "Archives/2026"). Returns success even if the folder already exists.

Count unread (unseen) emails per folder, plus a total. Use for "how many unread do I have?" overviews. Defaults to all folders; pass a folders list to limit scope and speed it up.

Check emails in a folder for spam/disposable email domains. Returns spam analysis and domain statistics.

Find and delete emails from known spam/disposable email domains.

Get statistics about sender domains in a folder. Useful for identifying bulk senders or spam patterns.

Add a domain to the custom spam list. Emails from this domain will be flagged as spam.

Remove a domain from the custom spam list.

Add a domain to the whitelist. Emails from whitelisted domains will never be flagged as spam.

List all known spam domains (built-in and custom).

Delete all emails from a specific domain. Useful for cleaning up unwanted newsletters or spam.