Documentation

How to connect a mailbox, what the assistant can and cannot do with it, and how the connector treats the mail it reads. Written from the code, so it can be checked against it.

Last updated 5 September 2026.

Connect a mailbox

Create an account at imap2ai.com/app. The free plan needs no card.
Add the mailbox: its address and password, plus the IMAP and SMTP hosts if they are not the usual ones. The connection is tested before anything is saved, and a failure tells you which setting is wrong. With two-factor authentication turned on you will usually need an app-specific password from your provider.
Copy the connector URL. It is shown once. Treat it like a password: anyone holding it can reach that mailbox through the assistant. We keep only its SHA-256, which is why it cannot be shown again; you can revoke it in the dashboard at any time and mint a new one.
Paste it into your AI assistant. There are two ways a client takes a remote MCP server, and yours does one of them. A settings screen — Claude and ChatGPT both have Settings → Connectors → add a custom connector, with the URL as the server address and authentication left off. Or a config file — Cursor, VS Code with Copilot, Windsurf, Cline and Zed take an entry in an mcp.json, and the dashboard hands you that JSON already filled in when it shows you the URL. A Claude connector covers chat, Claude Code and Cowork from one account.

Then ask. “What came in overnight that still needs a reply?” is a good first question. Drafts the assistant writes appear in your mail app’s Drafts folder, not in the chat.

Attachments

The assistant can put a file on a draft two ways. It can re-send something already in the mailbox — a customer's spec, a supplier's rate sheet — which costs nothing and has no practical size limit. Or it can attach something it wrote itself, which it has to spell out character by character, so that one is for small text files rather than documents.

For a file on your own computer, upload it from the mailbox page in the dashboard: it goes into a folder in your own mailbox, and from there the assistant attaches it like any other. Mailing the file to yourself first works just as well and always has. Either way the real ceiling is the receiving mail server, which usually refuses a message over 25 MB.

Which mailboxes work

Any mailbox that still allows IMAP and SMTP with a password: Gmail, Zoho, Fastmail, and any cPanel, Dovecot or Plesk mailbox from a web host. Microsoft 365 and Outlook.com do not work — Microsoft requires OAuth for IMAP and this connector does not speak it. An app password will not get around that; the mail server rejects the sign-in.

The eleven tools

Each tool declares to the client whether it only reads or can change the mailbox, and whether what it changes can be undone. Your client uses that to decide when to ask you first.

List folders · reads: Every folder in the mailbox, with its IMAP flags and the server’s delimiter.
List messages · reads: Headers in a folder, newest first: sender, subject, date, size, flags. Nothing is downloaded but headers.
Read messages · reads: Full messages as clean text — HTML converted, quoted history separated, inline signature images dropped. Reading never marks a message as read.
Search messages · reads: By sender, recipient, subject, body or date, in any folder. Accented text is searched correctly.
Find replies · reads: Every message, across folders, that replies to or references a given one.
Download attachment · reads: One attachment from a message, up to 8 MB.
Create draft · writes: Saves a reply into the Drafts folder, threaded under the original, for a person to review and send from their own mail app.
Send message · writes: Sends immediately over SMTP and files a copy in Sent. Off by default; a per-mailbox switch you turn on deliberately.
Move messages · writes: Files messages into another folder — a workflow stage, an archive, or Trash. The message survives in the destination.
Set flags · writes: Marks messages read, unread, starred or answered, or adds a custom keyword. It refuses the \Deleted flag.
Create folder · writes: Creates a folder, for example a stage in a workflow. Creating one that exists is not an error.

What it will not do

Erase a message. There is no delete tool, and the flag tool refuses \Deleted, which is how IMAP bins mail. Moving a message to Trash is the closest it can get, and the message is still there until your provider empties Trash.
Send on its own. Sending is off when you connect a mailbox and stays off until you turn it on for that mailbox. Until then, every reply is a draft and a person presses Send.
Keep your mail. Each request opens a fresh connection to your mail server, returns the result and holds nothing. The call log records which tool ran, when, and whether it worked — never a subject, a sender, a body or a folder name.

Plans and limits

Limits are per mailbox, per day, reset at midnight UTC. A “call” is one tool call by your assistant; the protocol handshake a client performs when it connects is not counted. Prices are final — the operator is not registered for VAT.

Free: 1 mailbox, 20 calls a day. Free, no card.
Pro: 3 mailboxes, 2,000 calls a day — €9 a month, or €86.4 a year.
Business: 10 mailboxes, 10,000 calls a day — €29 a month, or €278.4 a year.

When a mailbox has used its allowance, the assistant is told so in plain words, when it resets, and where a larger plan lives — rather than a bare error.

Security, and mail as hostile input

A mailbox is the one system whose contents are written by strangers. Anything the assistant reads may have been crafted to steer it, and anything it sends back to the mail server may have originated in such a message. The connector is built on that assumption:

Nothing from a message reaches the server’s command line unchecked. Folder names are validated before they are sent to IMAP — a name containing a line break or a NUL byte is refused outright, not escaped, because quoting does not neutralise those and they would end the command and start another. Message identifiers are integers. Search text is sent as a length-prefixed literal, so it cannot be mistaken for a command.
The dangerous flag is refused. A message cannot talk the assistant into marking mail deleted, because the tool will not set that flag for anyone.
Sending is opt-in per mailbox, so a planted instruction to “reply to everyone” produces a draft, which a person sees before it goes anywhere.
The instructions the server gives your assistant never contain mail. They describe the tools; message content arrives only as the result of a tool you invoked, where your client shows it to you.
Credentials are sealed. Your mailbox password is encrypted with AES-256-GCM under a key held only in the server’s environment, and is decrypted only for the duration of a request. The connector URL is stored as a SHA-256 hash. The operator screen shows counts and error codes, never either of them.

What the assistant reads is, by definition, sent to the assistant’s provider — Anthropic for Claude, OpenAI for ChatGPT, whoever operates the client you chose. We cannot see which one that is. The privacy policy says exactly what is stored where and for how long.

Support

Write to info@imap2ai.com or call +386 40 202 488. One person runs this and answers. Include the mailbox address and what the dashboard said; never include the connector URL or a password — nobody supporting you needs either.