Developers
Your mailbox,
programmable.
The Ledger Mail is a real mail server with a real API in front of it. Read and send mail from a script, connect an agent over MCP, or point any mail client at IMAP, SMTP and JMAP — with credentials you create and revoke yourself.
What you can build
Everything the web app does, your code can do too — over the same API, with the same limits.
Read and triage mail
List folders, page through messages, search a folder server-side, download an attachment, then flag, move or delete — one message or two hundred in a single call.
Automate an inbox
File receipts into a folder as they land, archive a newsletter after a week, or forward a summary to somewhere else each morning. A cron job and one token are enough.
Send from your own addresses
Send transactional mail from the account's address or any of its active aliases, with attachments and threading headers, and keep a copy in Sent.
Give an agent your mailbox
Connect an MCP client and let it list, search and read mail, and create aliases — over an OAuth token that is the user's own, not a shared key.
Three ways in
Pick by what is calling: your own code, somebody else's agent, or a mail client on a device.
A personal API token, for scripts
Create one in Settings, tick the scopes it needs, and send it as a bearer token. It is scoped, it can expire, it is revocable on its own, and it can never mint another credential. This is the right choice for anything you write and run yourself.
OAuth and MCP, for apps and agents
Software you did not write should never hold a user's password. The mail server is an OAuth 2.1 authorization server with PKCE and dynamic client registration, and the API publishes an MCP endpoint that takes those tokens — so an agent gets access the user granted and the user can see.
IMAP, SMTP and JMAP, for mail clients
Thunderbird, Apple Mail, a phone, Outlook — all of them speak the standard protocols, and so does the mail server. Sign in with an app password rather than the account password, and auto-configuration fills in the rest.
| If you are… | Use | Credential |
|---|---|---|
| Writing a script or a backend job | REST API | Personal API token |
| Shipping an app other people sign in to | OAuth 2.1 | Access token the user granted |
| Connecting an AI agent | MCP server | Access token the user granted |
| Setting up a mail app on a device | IMAP / SMTP / JMAP | App password |
Your first request
Create a token in Settings, put it in your shell, and list the mailbox's folders.
export LEDGER_TOKEN="lmk_your_token_here"curl https://api.theledgermail.com/api/v1/mail/folders \
-H "Authorization: Bearer $LEDGER_TOKEN"{
"folders": [
{ "path": "INBOX", "name": "INBOX", "delimiter": "/", "messages": 128, "unseen": 3, "specialUse": "\\Inbox" },
{ "path": "Sent", "name": "Sent", "delimiter": "/", "messages": 64, "unseen": 0, "specialUse": "\\Sent" }
]
}That call needs the mail:read scope and nothing else. From there, GET /api/v1/mail/folders/INBOX/messages pages through the inbox, and GET /api/v1/mail/messages/{uid} opens one.
Working without a token yet?
The contract is published unauthenticated at /api/openapi.json, so you can generate a client, read the shapes and write your code before you create a credential.
Keep reading
Three reference pages, each one complete on its own.