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 |