Many moons in the past I had the concept I would really like for an agentic system to have the ability to entry my e-mail servers. That got here to me after I automated gathering incoming invoices for my firm with a make.com workflow. However that didn’t quantity to a lot till OpenClaw hit the world’s stage.
The second key challenge in addition to SwiftMail was SwiftMCP. These two collectively had been the primary hyperlink I had between ChatGPT and my e-mail server. SwiftMCP exposes an OpenAPI interface which you may connect with customized GPTs to question and skim your emails. And naturally as native MCP server you may connect with it with MCP from native AI shopper apps as properly.
After which OpenClaw entered my life and – virtually every thing modified. Lastly I may pursue my imaginative and prescient from two years in the past of having an organization of AI Brokers inside 5 years. All the sudden I’ve brokers working for me and a few of them may do superb work if solely they might learn my e-mail.
However OpenClaw doesn’t do MCP. The issue with LLM instruments usually is that an agentic session wants so as to add quite a lot of schema data into the context. With each server you will have capabilities for which you want many a device’s JSON schema and hold that in context in order that the LLM can select to emit device calls to them in the suitable format.
LLMs do have educated information learn how to work with scripts and CLIs although. That’s why Peter Steinberger’s principal physique of labor in 2025 revolved round constructing CLIs for many issues. And this pattern culminated within the Agent Expertise commonplace. The idea being that the agent will get a brief description of the talent into reminiscence and if he wants it he can learn up on it in SKILL.md. And most abilities additionally include scripts that the agent then can name. And since good scripts or CLIs have a --help possibility, LLMs can simply determine learn how to name them for the meant function.
This works so properly, that I actually made a ton of abilities for myself, about half of which I put up on GitHub. Python is the de issue chief when it comes to portability for abilities.
So I wanted/needed to have a CLI for e-mail. The issue for that although is that CLIs are stateless: you run them, they produce a end result after which they terminate. For one-shot e mail queries this could be okay, however often it’s important to do a number of issues in a piece circulate: checklist new emails, obtain some, flag them as seen or junk, trash them, or archive them. With a traditional CLI you would need to join, login, do the operation, logout and disconnect each time.
That felt foolish to me.
Additionally I needed to utilize IMAP IDLE the place you get a notification each time one thing modifications in your Inbox. So I needed to have a course of that you just kick off after which stays resident, holding open connections to a number of e mail servers. So how will you have each issues on the identical time?
The reply is that this: the background course of holding the connections is a daemon. And the CLI connects to it regionally and quick.
That is what I’m providing you with immediately. Submit has a easy submit command that communicates through an area bonjour+tcp MCP transport to postd working on the identical machine. The daemon is the one the place you configure the server connections. The CLI is the one that permits you to work together with the servers.
🏤Submit – Safe.Agentic.Submit.Workplace
Submit shops server configurations in ~/.submit.json. You possibly can embrace credentials instantly within the config file or retailer them securely in a non-public macOS Keychain.
Choice 1: Credentials in Config File
Easy however much less safe. Good for improvement or non-sensitive accounts.
{
"servers": {
"private": {
"credentials": {
"host": "imap.gmail.com",
"port": 993,
"username": "you@gmail.com",
"password": "your-app-password"
}
}
}
}Choice 2: Credentials in Keychain (Advisable)
Submit robotically creates and manages a non-public keychain at ~/.submit.keychain-db. The keychain is encrypted with a passphrase derived out of your Mac’s {hardware} UUID, so it’s locked to your particular machine.
{
"servers": {
"private": {
"command": "imap.gmail.com:993"
}
}
}Then add the credentials to the keychain:
# Submit will immediate for username and password
submit keychain add private --host imap.gmail.com --port 993Your credentials at the moment are saved securely. Submit will retrieve them robotically when wanted.
Fundamental Operations
For the CLI to do something the daemon must be working. Default mode is for it to run in background, with --foreground you’ll be able to have it in foreground as properly.
# Daemon Instructions
postd begin
postd standing
postd cease
postd reload
Emails are recognized by the mixture of server, mailbox and UID. Please word that UID may turn out to be invalid and in the event you transfer an e mail to a distinct mailbox it additionally will get a brand new UID. A number of the instructions default to --mailbox INBOX.
Listing Unseen Emails
# Listing latest 10 messages in INBOX
submit checklist --server private --limit 10Fetch an Electronic mail as Markdown
Submit converts HTML emails to wash, readable markdown.
# Fetch UID 12345 and show as markdown
submit fetch 12345 --server privateThe output contains headers, physique textual content transformed from HTML, and a listing of attachments. With the --json possibility you get beautify JSON for all instructions.
Downloading Attachments
# Obtain first attachment from UID 12345 to present listing
submit attachment --server private --uid 12345
# Or specify which attachment you need and a distinct output listing
submit attachment --filename bill.pdf --server private --uid 12345 --out ~/DownloadsSubmit will save every attachment with its unique filename.
Making Drafts
With submit Brokers may draft emails – however not ship them. You possibly can merely create a wealthy textual content e mail from a markdown file:
# Create a markdown file
cat > e mail.md << 'EOF'
# Undertaking Replace
Hello crew,
This is the **weekly replace**:
- Characteristic A: *accomplished*
- Characteristic B: in progress
- Characteristic C: deliberate for subsequent dash
Verify the [documentation](https://instance.com) for particulars.
Thanks!
EOF
# Draft the e-mail
submit draft --to colleague@instance.com
--subject "Weekly Replace"
--body e mail.md
# Or use inline markdown
submit draft --to colleague@instance.com
--subject "Fast word"
--body "Thanks for the **nice** work on the challenge!"Submit will use the markdown for the textual content/plain header and generate a pleasant textual content/html model.
Enabling IDLE for Actual-Time Electronic mail Processing
IDLE is an IMAP extension that retains a connection open and notifies you immediately when new mail arrives. That is good for automation.
Configure IDLE in .submit.json
Add idle: true and specify a handler script:
{
"servers": {
"private": {
"command": "imap.gmail.com:993",
"idle": true,
"idleMailbox": "INBOX",
"command": "python3 /Customers/you/process-email.py"
}
}
}Create a Easy Handler Script
Your handler receives e mail knowledge as JSON on stdin:
#!/usr/bin/env python3
import json
import sys
# Learn e mail notification
e mail = json.load(sys.stdin)
topic = e mail['headers'].get('topic', 'No topic')
sender = e mail['headers'].get('from', 'Unknown')
print(f"New e mail from {sender}: {topic}")
# Exit 0 = success, 1 = error, 2 = deliberately skipped
sys.exit(0)The daemon will watch all configured IDLE mailboxes and name your handler script each time new mail arrives. The script receives full e mail particulars (headers, markdown physique, attachments) as structured JSON.
Handler JSON Format
Right here’s what your script receives:
{
"uid": 12345,
"date": "2026-02-27T10:30:00Z",
"from": ["sender@example.com"],
"to": ["you@gmail.com"],
"topic": "Your e mail topic",
"headers": {
"from": "Sender Identify ",
"topic": "Your e mail topic",
"list-id": "",
...
},
"markdown": "# Electronic mail bodynnConverted to markdown...",
"attachments": [
{
"filename": "document.pdf",
"contentType": "application/pdf",
"size": 102400
}
]
} Your handler can then resolve what to do: archive it, ahead it, extract knowledge, set off a workflow, and so on.
A number of Scope Help
You possibly can simply have a number of completely different brokers in OpenClaw, some could be sandboxed, some aren’t. And also you don’t need each agent to have the ability to entry all configured e mail servers. That’s the rationale why Postd has the (elective) means to arrange a number of API keys that may solely entry sure servers.
Setting Up Two Scoped API Tokens in Submit
This walkthrough creates two completely different API keys, every restricted to particular mail server IDs, and permits strict token enforcement in postd.
1. Configure your servers
Outline not less than two server IDs in ~/.submit.json:
{
"servers": {
"work": {},
"private": {}
}
}Set credentials as standard (keychain or inline credentials).
2. Create two scoped tokens
Create one token for work solely:
submit api-key create --servers workCreate one token for private solely:
submit api-key create --servers privateEvery command prints a UUID token. Save each.
You possibly can examine what exists with:
submit api-key checklist3. Begin/restart daemon so scopes are loaded
postd now preloads API-key scopes at startup. Restart it after key modifications:
postd restart
# or:
postd cease && postd beginIf keychain prompts seem, authorize postd as soon as (want All the time Enable). Opposite to the non-public keychain (which is protected by a really lengthy password), the tokens are saved in your login keychain. This fashion you already know if an unknown course of tries to entry them. Due to this, it’s important to approve postd as soon as for each token you arrange.
Now you’ll be able to add the POST_API_KEY particular to every agent of their .env. Having an API key within the surroundings hides the instructions for configuration within the CLI. So if you wish to make modifications you’d must unset the important thing. However word, if there’s not less than one token configured, then all instructions accessing the daemon want you to specify the token.
- If not less than one API key exists, MCP entry requires a token.
- No token: request fails (
API key's required.). - Unknown token: request fails (
Invalid API key.). - Legitimate token, mistaken server: request fails (
not licensed for server).
You possibly can rotate tokens by simply deleting and recreating them.
submit api-key delete --token
submit api-key create --servers work,private
Engaged on a Mailroom Talent
Giant companies have a mail room, the place all new submit is being delivered, earlier than it will get sorted and routed by the corporate. With Submit now you can have the identical.
I’m engaged on a mail-room talent that already does quite a lot of sorting for me. With immediate injections being the concern of the day, some preliminary sorting might be executed programmatically. Most publication and notification emails have sure header fields or sender addresses by which they are often acknowledged.
What It Does
The mail-room talent robotically processes incoming emails in real-time as they arrive. Consider it as a wise assistant sitting in your inbox, sorting mail earlier than you even see it.
Programmatic Sorting (Rule-Primarily based)
The primary line of protection makes use of easy sample matching – no AI wanted:
Newsletters & Mailing Lists are recognized by commonplace e mail headers like Listing-ID or Listing-Unsubscribe. These get filed away to a separate archive, holding your inbox clear.
Service Notifications from identified firms (GitHub, Amazon, Apple, xAI, LinkedIn, and so on.) are acknowledged by their sender addresses and robotically archived to a notifications folder.
This rule-based sorting is quick, deterministic, and proof against immediate injection assaults – it’s simply checking headers and e mail addresses in opposition to a whitelist.
Safe AI-Powered Categorization
For emails that don’t match the straightforward guidelines, the talent makes use of AI to deal with the trickier instances. However I’m not having my OpenClaw deal with this. As an alternative I’ve a easy agent that I constructed with the OpenAI Brokers SDK do the categorization. This agent has neither information nor entry to any of my private data. I solely has a device with which it may request a markdown illustration of a file attachment.
The Aim: Inbox Zero
After processing:
- Newsletters → Archived, faraway from inbox
- Service notifications → Archived, faraway from inbox
- Spam → Moved to Junk folder
- Private & enterprise mail → Stays in inbox (unread, in your consideration)
All archived emails are saved as readable markdown recordsdata, organized by sender, with full metadata preserved. Nothing is completely deleted – every thing might be recovered if wanted.
The aim is straightforward: solely the emails that want your consideration keep in your inbox. All the things else is robotically sorted, archived, and out of your method.
Now about these newsletters and notifications: having them as markdown on my onerous drive permits me to have one other course of that picks up attention-grabbing objects and compiles a customized information briefing primarily based on what actually pursuits me.
Conclusion
Apart from its utility, Submit has rapidly turn out to be my go-to challenge for furthering improvement on SwiftMail, SwiftMCP and SwiftText. The latter I haven’t even talked about till now: It’s a set of capabilities to get markdown from PDFs, HTML recordsdata or DOCX recordsdata, and extra.
Within the mixture of those threes and dealing on real-life software of agentically dealing with my e mail proved to be an especially fertile floor for what to enhance and which capabilities are helpful. I haven’t even touched on seek for emails. I plan on placing it on homebrew along with a talent on clawhub as properly, quickly.
I may write a guide about this all, however for now, this text should suffice. I’m completely happy to speak with you about your utilization situations, get your bug stories or pull requests on GitHub.
Associated
Classes: Administrative
