IMAP Mail Skill
Send and receive email through your own IMAP/SMTP server.
A lightweight local REST API (FastAPI) runs as a bridge between the agent and your mail server — no third-party email platform needed.
Setup (first time)
1. Install dependencies
CODEBLOCK0
2. Configure credentials
Create /etc/imap-mail.env (or any path, then set IMAP_MAIL_ENV):
CODEBLOCK1
3. Start the API server
CODEBLOCK2
The API listens on http://127.0.0.1:8025 by default.
Checking Email
CODEBLOCK3
Searching Email
CODEBLOCK4
Sorting Inbox (Personal vs Forwarded)
Automatically move messages into sub-folders based on addressing:
- - Personal — inbox address is directly in
To: or INLINECODE4 - Forwarded — subject starts with
Fwd: / FW:, or X-Forwarded-* / Resent-* headers present - Forwarded takes priority over Personal when both apply
CODEBLOCK5
Messages that match neither category (e.g. BCC, bulk mail) stay in the source folder.
Folder Management
CODEBLOCK6
Sending Email
CODEBLOCK7
Contact Memory (CRM)
Persistent notes and history per contact. Flagged senders are automatically tracked — when their message arrives, the agent pulls full context and reports in detail.
CODEBLOCK8
How it works with flagged mail:
- 1. Flagged (starred) UNSEEN messages are processed separately from regular mail
- For each flagged message, the agent fetches the sender's full contact history
- Reports to user with: who wrote, what they want, full context from previous interactions
- Automatically saves a note summarizing the new message
Auto-Rules (persistent flag/action on incoming mail)
Rules are defined once and applied automatically to every new (UNSEEN) message on each mail check — until you remove them.
CODEBLOCK9
Scheduled Send
Queue emails for future delivery. The API background scheduler checks every 60 seconds.
CODEBLOCK10
IMAP IDLE (Push Notifications)
Instead of polling every N minutes, IDLE keeps a persistent connection open so the server pushes notifications immediately when new mail arrives.
Add to your env file:
CODEBLOCK11
When new mail arrives, the API POSTs to the webhook:
CODEBLOCK12
Check IDLE status:
CODEBLOCK13
VIP Sender List
Mark specific senders as VIP — their messages will have "vip": true in the API response and in IDLE webhook payloads, enabling urgent/priority handling.
Add to your env file:
CODEBLOCK14
Messages from VIP senders are flagged in all responses ("vip": true) and can be filtered:
CODEBLOCK15
API Endpoints
The local REST API at http://127.0.0.1:8025 exposes:
| Method | Path | Description |
|---|
| GET | INLINECODE12 | Check API status (includes IDLE state, VIP list) |
| GET |
/idle/status | IMAP IDLE watcher status |
| GET |
/inboxes/{inbox}/folders | List folders |
| POST |
/inboxes/{inbox}/folders | Create folder |
| DELETE |
/inboxes/{inbox}/folders/{name} | Delete folder |
| GET |
/inboxes/{inbox}/messages | List messages (
?folder=INBOX&limit=N&unseen=true) |
| GET |
/inboxes/{inbox}/messages/{uid} | Get full message (
?folder=INBOX) |
| GET |
/inboxes/{inbox}/messages/{uid}/attachments/{index} | Download attachment (base64) |
| POST |
/inboxes/{inbox}/messages | Send email |
| POST |
/inboxes/{inbox}/messages/{uid}/move | Move message (
?folder=src) |
| DELETE |
/inboxes/{inbox}/messages/{uid} | Delete message |
| POST |
/inboxes/{inbox}/sort | Sort into Personal/Forwarded folders (
?dry_run=true) |
| GET |
/inboxes/{inbox}/search | Search (
?q=&from=&subject=&since=&vip_only=true) |
| GET |
/inboxes/{inbox}/threads | List threads |
| POST |
/inboxes/{inbox}/scheduled | Schedule email for future delivery |
| GET |
/inboxes/{inbox}/scheduled | List scheduled messages |
| DELETE |
/inboxes/{inbox}/scheduled/{id} | Cancel scheduled message |
Environment Variables
| Variable | Default | Description |
|---|
| INLINECODE34 | — | IMAP server hostname |
| INLINECODE35 |
993 | IMAP port (TLS) |
|
MAIL_SMTP_HOST | — | SMTP server hostname |
|
MAIL_SMTP_PORT |
465 | SMTP port (TLS) |
|
MAIL_USER | — | Email login / address |
|
MAIL_PASS | — | Password |
|
MAIL_FROM_NAME |
Agent | Display name in From header |
|
MAIL_IDLE_WEBHOOK | — | Webhook URL for IMAP IDLE push events |
|
MAIL_IDLE_FOLDER |
INBOX | Folder to watch with IDLE |
|
MAIL_VIP_SENDERS | — | Comma-separated VIP email addresses |
|
MAIL_SCHEDULED_DB |
/tmp/imap-mail-scheduled.db | SQLite path for scheduled sends |
|
MAIL_ALLOW_SELF_SIGNED |
false | Set
true to skip TLS cert verification (self-signed certs) |
|
IMAP_MAIL_API |
http://127.0.0.1:8025 | API base URL (for scripts) |
|
IMAP_MAIL_ENV |
/etc/imap-mail.env | Path to env file |
|
IMAP_MAIL_PORT |
8025 | API listen port |
Security Notes
- - Credentials — mail login and password are stored in a local env file (e.g.
/etc/imap-mail.env), readable only by the service user. Never hardcode credentials in scripts. - SSL/TLS — all IMAP and SMTP connections use TLS by default. Certificate verification is enabled by default (
ssl.create_default_context()). Set MAIL_ALLOW_SELF_SIGNED=true only if your mail server uses a self-signed certificate and you accept the risk. - Local API only — the REST bridge listens on
127.0.0.1 (loopback) only and is not exposed to the network. - Webhook (IDLE) — if
MAIL_IDLE_WEBHOOK is set, full message contents (including body) are POSTed to that URL on new mail. Ensure the webhook URL is a trusted local endpoint.
Compatibility
Works with any standard IMAP/SMTP server:
- - Self-hosted: Dovecot, Postfix, Exim, Maddy
- Hosted: Gmail (App Password), Outlook/Hotmail, Yahoo Mail, Fastmail, ProtonMail Bridge, and any provider that supports IMAP
Note: Self-signed TLS certificates are accepted automatically.
References
IMAP 邮件技能
通过您自己的 IMAP/SMTP 服务器发送和接收电子邮件。
一个轻量级的本地 REST API（FastAPI）作为代理与邮件服务器之间的桥梁运行——无需第三方电子邮件平台。
设置（首次使用）
1. 安装依赖
bash
pip3 install fastapi uvicorn
2. 配置凭据
创建 /etc/imap-mail.env（或任意路径，然后设置 IMAPMAILENV）：
env
MAILIMAPHOST=mail.example.com
MAILIMAPPORT=993
MAILSMTPHOST=mail.example.com
MAILSMTPPORT=465
MAIL_USER=agent@example.com
MAIL_PASS=yourpassword
MAILFROMNAME=MyAgent
3. 启动 API 服务器
bash
一次性 / 前台运行
python3 {baseDir}/scripts/mail-api.py
或作为 systemd 服务运行（推荐）
参见：{baseDir}/references/systemd.md
API 默认监听 http://127.0.0.1:8025。
检查邮件
bash
列出最近的消息
python3 {baseDir}/scripts/check_inbox.py --inbox agent@example.com
仅未读消息
python3 {baseDir}/scripts/check_inbox.py --inbox agent@example.com --unseen
指定文件夹
python3 {baseDir}/scripts/check_inbox.py --inbox agent@example.com --folder Sent
读取特定消息（使用列表输出中的 UID）
python3 {baseDir}/scripts/check_inbox.py --inbox agent@example.com --message 42
读取消息并保存所有附件
python3 {baseDir}/scripts/check_inbox.py --inbox agent@example.com --message 42 --save-attachments /tmp/mail/
列出线程
python3 {baseDir}/scripts/check_inbox.py --inbox agent@example.com --threads
列出所有文件夹
python3 {baseDir}/scripts/check_inbox.py --inbox agent@example.com --folders
搜索邮件
bash
按关键词搜索（主题 + 正文）
python3 {baseDir}/scripts/search.py --inbox agent@example.com --q invoice
按发件人搜索
python3 {baseDir}/scripts/search.py --inbox agent@example.com --from alice@example.com
按主题 + 日期范围搜索
python3 {baseDir}/scripts/search.py --inbox agent@example.com --subject meeting --since 2026-01-01
查找未读消息
python3 {baseDir}/scripts/search.py --inbox agent@example.com --unseen
查找带附件的消息并保存
python3 {baseDir}/scripts/search.py --inbox agent@example.com --has-attachments --save-attachments /tmp/mail/
仅查找 VIP 发件人的消息
python3 {baseDir}/scripts/search.py --inbox agent@example.com --vip
仅查找已标记/星标消息
python3 {baseDir}/scripts/search.py --inbox agent@example.com --flagged
查找特定发件人的已标记消息
python3 {baseDir}/scripts/search.py --inbox agent@example.com --from craig@example.com --flagged
组合筛选：自某个日期以来特定发件人的未读消息
python3 {baseDir}/scripts/search.py --inbox agent@example.com --from alice@example.com --since 2026-03-01 --unseen
包含特定主题关键词的未读消息
python3 {baseDir}/scripts/search.py --inbox agent@example.com --subject invoice --unseen
在特定文件夹中搜索
python3 {baseDir}/scripts/search.py --inbox agent@example.com --q report --folder Archive
收件箱排序（个人 vs 转发）
根据寻址方式自动将消息移动到子文件夹：
- - 个人 — 收件箱地址直接在 To: 或 Cc: 中
- 转发 — 主题以 Fwd: / FW: 开头，或包含 X-Forwarded- / Resent- 标头
- 当两者都适用时，转发优先于个人
bash
预览将被移动的内容（不做更改）
python3 {baseDir}/scripts/sort_inbox.py --inbox agent@example.com --dry-run
排序所有消息
python3 {baseDir}/scripts/sort_inbox.py --inbox agent@example.com
仅排序未读消息
python3 {baseDir}/scripts/sort_inbox.py --inbox agent@example.com --unseen
自定义文件夹名称
python3 {baseDir}/scripts/sort_inbox.py --inbox agent@example.com \
--personal-folder MyInbox --forwarded-folder Forwards
排序特定源文件夹
python3 {baseDir}/scripts/sort_inbox.py --inbox agent@example.com --folder AllMail
两种类别都不匹配的消息（例如密送、群发邮件）保留在源文件夹中。
文件夹管理
bash
列出所有文件夹
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --list
创建文件夹
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --create Archive
删除文件夹
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --delete OldFolder
将消息移动到另一个文件夹（使用 check_inbox 输出的 UID）
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --move 42 --to Archive
从特定源文件夹移动
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --move 5 --to INBOX --from-folder Junk
删除消息
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --delete-msg 42
将 INBOX 中的所有消息标记为已读
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --mark-seen
将特定文件夹中的所有消息标记为已读
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --mark-seen --from-folder Sent
将一条特定消息标记为已读（使用 check_inbox 输出的 UID）
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --mark-seen-uid 42
将多条特定消息标记为已读（空格分隔的 UID）
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --mark-seen-uid 42 55 73
将特定消息标记（星标）为重要
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --flag-uid 42 55 73
标记特定发件人的所有消息
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --flag-from craig@example.com
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --flag-from igor@example.com
移除消息标记
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --unflag-uid 42
python3 {baseDir}/scripts/manage_folders.py --inbox agent@example.com --unflag-from craig@example.com
发送邮件
bash
发送纯文本邮件
python3 {baseDir}/scripts/send_email.py \
--to recipient@example.com \
--subject Hello \
--text Message body here
发送给多个收件人
python3 {baseDir}/scripts/send_email.py \
--to alice@example.com \
--to bob@example.com \
--subject Hello everyone \
--text Hi all!
回复消息（保留线程）
python3 {baseDir}/scripts/send_email.py \
--to sender@example.com \
--subject Re: Original Subject \
--text My reply \
--reply-to
联系人记忆（CRM）
每个联系人的持久化笔记和历史记录。已标记的发件人会被自动跟踪——当他们的消息到达时，代理会拉取完整上下文并详细报告。
bash
查找联系人的所有信息
python3 {baseDir}/scripts/manage_contacts.py --get craig@example.com
列出所有联系人
python3 {baseDir}/scripts/manage_
