Tech docs

These pages explain how the code of email-mcp works and why it is built this way. They are for a developer who knows Go and does not know this code. Each page names the files that it covers, and links to the code at the version of this site.

email-mcp is an MCP server. MCP (Model Context Protocol) is the open standard that lets an AI (artificial intelligence) app call the tools of another program. The agent is the AI program that calls the tools. To learn how a person installs and uses email-mcp, read the user manual.

Start with the Architecture overview. It shows the whole program on one page.

If you want to know

The questions use a few terms. A tenant is the owner of a set of accounts. IMAP (Internet Message Access Protocol) is the protocol for reading mail. Stdio (standard input and output) and HTTP (HyperText Transfer Protocol) are the two ways that a client talks to the server. Stdin is the standard input of a program. A level is a number from 0 to 5 that says what the agent may do with an account. A scope is a permission that an access token carries. The undo window is the time that a send waits before it goes out, while it can still be cancelled. The master key is the key that protects the other keys. A migration is a numbered file that changes the structure of the database. Full autonomy means that both confirmation switches of an account are off, so they ask nothing before a send or a move to the Trash. Other checks can still ask. Ctrl-C is the keys that stop a program in a terminal: hold the Ctrl key and press C. SMTP (Simple Mail Transfer Protocol) is the protocol for sending mail. A provider is the service behind a mail account. A backend is the part of the program that talks to the mail server of one account. A certificate is the signed proof of identity that a mail server shows when a connection starts. An authority is a body that signs certificates, so that a client can trust them. A pin is the fingerprint of a certificate that the person chose to trust. HTML (HyperText Markup Language) is the language of web pages and of many mails.

If you want to know… read…
What are the main parts, and what does each one do? Architecture overview
Which code can an agent reach, and which code only a person can reach? Architecture overview
Who is the caller, and what is a tenant in a local install? Architecture overview
What starts when I run serve, and what can run at the same time? Architecture overview
Why can several processes use one database? Architecture overview
Where does this code live? Map of packages
What may a package import? Map of packages
Which package do I change for this feature? Map of packages
Which library does what, and why is go-imap pinned? Map of packages
What happens between the request of the client and the IMAP server? One tool call, step by step
Where is the permission checked? One tool call, step by step
Where is the call recorded in the activity log? One tool call, step by step
Where is text from the mail cleaned? One tool call, step by step
Where do errors become the texts that the agent sees? One tool call, step by step
What differs between stdio and HTTP? One tool call, step by step
What happens when an agent calls send_message? The send flow
When is the person asked? The send flow
How is the person asked? The send flow
How does the “yes” of the person bind to the exact message? The send flow
What is the undo window? The send flow
Who can cancel a send, and until when? The send flow
What if the program stops, or the connection breaks, during a send? The send flow
How is a double send prevented? The send flow
What can an agent do at each level? Permissions
Who changes a level, and how? Permissions
What do token scopes change? Permissions
What are the limits, and when do they apply? Permissions
What is full autonomy, and what does it need? Permissions
What can never be done, at any level? Permissions
Where are the files, and who may read them? Storage and secrets
Which fields are encrypted, hashed or plain? Storage and secrets
What is the master key, and where does it live? Storage and secrets
How does the first start make the key, and what if two programs start at once? Storage and secrets
How do I rotate the master key? Storage and secrets
How long is data kept? Storage and secrets
How do I add a migration? Storage and secrets
What does the activity log record, and where do the entries come from? Activity log and program log
What is never recorded? Activity log and program log
How long are activity log entries kept? Activity log and program log
What goes in the program log, and where does it go? Activity log and program log
How do I add a log line safely? Activity log and program log
What does app.Open build, and in what order? Startup and shutdown
What background work runs? Startup and shutdown
What happens when I press Ctrl-C? Startup and shutdown
What happens when the client closes stdin? Startup and shutdown
How long can a stop take, and why? Startup and shutdown
What happens at the next start after a crash? Startup and shutdown
Why does a short command not wait for the queue? Startup and shutdown
What must a mail provider implement? The mail backend
How does the program keep one backend for each account, and see a change that another process made? The mail backend
How does the backend keep and reuse connections? The mail backend
How does the backend secure a connection and check a certificate? The mail backend
When may a person trust a certificate that no authority signed, when an account is new? The mail backend
When may a person replace or remove a pin? The mail backend
How are messages, folders and tags addressed? The mail backend
How does a change to many messages stay safe, and what if it fails half way? The mail backend
How does a send reach the SMTP server? The mail backend
How does the program find the server settings of an address? Connecting an account
How does an account get connected and tested? Connecting an account
What do the web portal and the commands share when they connect an account? Connecting an account
What happens when a mail server refuses the stored login? Connecting an account
Which limits and lifetimes does the mail backend have? The mail backend
What would I change to add a provider? The mail backend
What steps does mail take on the way in and on the way out? Mail content
What is removed from incoming text, and why? Mail content
Which parts of a message does an agent read? Mail content
How is HTML turned into text? Mail content
What limits stop a hostile message from using all the memory? Mail content
Why is there a copy of the HTML parser of golang.org/x/net? Mail content
How do I change the hidden-text rules safely? Mail content
How is an outgoing message built, and what does it refuse? Building mail
How is a saved draft made ready to send? Building mail
Why does the preview start with the text that goes out? Building mail
How are the commands registered and tested? The command line
Which commands open the parts of the program (the App), and how does each one close it? The command line
How do the commands handle passwords, prompts and exit codes (the number that a program gives back when it ends)? The command line
Which use cases and which kind of caller do the commands share with the web portal? The command line
How do I add a command? The command line
Which checks run before a request of serve --http reaches a tool, and in what order? Local HTTP mode
How do the access tokens of local HTTP work? Local HTTP mode
Why is the HTTP server stateless (it keeps nothing between two requests), and what does that change? Local HTTP mode
Who gets the question in the chat, and who gets the link to the approval page? Local HTTP mode
How are the size, the time and the number of HTTP requests bounded? Local HTTP mode
How does the HTTP server stop? Local HTTP mode
When does the web portal start, and where does it listen? The web portal
How does a person sign in to the web portal, and why does it have its own host name? The web portal
Which checks run on a request to the web portal, and in what order? The web portal
How are the pages, the styles and the one script of the web portal served? The web portal
How does the web portal reach the service? The web portal
How do I add a page to the web portal? The web portal
What protects the person from an agent that follows bad instructions? Security design
Where is each security rule enforced? Security design
Which test fails if a security rule breaks? Security design
Which values does the server sign, and how? Security design
What must I check when I change security code? Security design
How do I build, test and lint the code? Local development
Which Go version do I need? Local development
What does CI (continuous integration: the checks that GitHub runs on each pull request and on each push to main) run? Local development
Which files and tests do I change to add a tool, a command, a migration or a package? Local development
Which conventions does the code follow? Local development
Which page of the docs do I update when I change the code? Local development
Which kinds of test exist, and what does each one prove? Testing
How do I test code that talks to IMAP, SMTP or the web portal (the pages that email-mcp shows in the browser)? Testing
What is in internal/e2e? Testing
What are the build tags (words that a Go file asks for before it is built), and what does the interop test (the test against real mail servers) need? Testing
Which tests run in CI, in the nightly interop run and in the release? Testing
What must be set up once, before the first release? Making a release
What do I do for each release? Making a release
How does the version go up? Making a release
What do I do when a release fails? Making a release
How can I try the build without publishing? Making a release
How is the docs site published? Making a release
What does this term, short name or unit mean? Glossary

Code covered by this page