open-mail-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Open Mail CLI - Agent Email Toolkit

Open Mail CLI - Agent 邮件工具包

This skill equips the agent with a full-featured email client accessible via the

mail-cli

command. The agent can send, receive, search, organize, and automate emails entirely from the terminal through IMAP/SMTP protocols, with offline-first local storage. It also provides a local HTTP API server for programmatic integration.

该技能为Agent提供了一个功能完整的邮件客户端，可通过

mail-cli

命令访问。Agent完全可以通过IMAP/SMTP协议从终端发送、接收、搜索、整理和自动化邮件，同时支持离线优先的本地存储。它还提供了一个本地HTTP API服务器，用于程序化集成。

Installation

安装

bash

npm install -g open-mail-cli

bash

npm install -g open-mail-cli

Requirements: Node.js >= 18.0.0

要求：Node.js >= 18.0.0

undefined

undefined

Getting Started

快速开始

1. Configure an Email Account

1. 配置邮件账户

bash

undefined

bash

undefined

Interactive wizard (recommended)

交互式向导（推荐）

mail-cli config

Or manual setup

或手动设置

mail-cli account add --email user@gmail.com --name "My Gmail"
--imap-host imap.gmail.com --imap-port 993
--smtp-host smtp.gmail.com --smtp-port 465
--username user@gmail.com --password "app-password" --test

undefined

undefined

2. Sync, Read, and Send

2. 同步、查看与发送

bash

mail-cli sync                # Fetch emails from server
mail-cli list --unread       # Browse unread emails
mail-cli list --format json --fields id,subject,from  # Structured output for parsing
mail-cli read <email-id>     # Read a specific email
mail-cli send --to user@example.com --subject "Hello" --body "Content"

bash

mail-cli sync                # 从服务器获取邮件
mail-cli list --unread       # 浏览未读邮件
mail-cli list --format json --fields id,subject,from  # 用于解析的结构化输出
mail-cli read <email-id>     # 查看特定邮件
mail-cli send --to user@example.com --subject "Hello" --body "Content"

Capabilities Overview

功能概述

Choose the reference that matches the task at hand. Each reference includes purpose, scenarios, best practices, and full command syntax.

选择与当前任务匹配的参考文档。每个参考文档包含用途、场景、最佳实践和完整命令语法。

Output Control & Error Handling

输出控制与错误处理

Reference: references/output-and-errors.md

Control output format (

--format json/markdown/html

), select specific fields (

--fields

), and handle errors via standardized exit codes and JSON error output. Use this when the agent needs to parse command output programmatically or handle failures gracefully.

参考：references/output-and-errors.md

控制输出格式（

--format json/markdown/html

）、选择特定字段（

--fields

），并通过标准化退出码和JSON错误输出来处理错误。当Agent需要以程序化方式解析命令输出或优雅处理失败时使用此功能。

Webhooks & HTTP API

Webhooks与HTTP API

Reference: references/webhooks-and-api.md

Register webhooks for email events, trigger scripts on new mail, and use the local HTTP API server with OpenAPI documentation. Use this when the agent needs real-time event-driven workflows or REST API integration.

参考：references/webhooks-and-api.md

为邮件事件注册webhooks、收到新邮件时触发脚本，并使用带有OpenAPI文档的本地HTTP API服务器。当Agent需要实时事件驱动工作流或REST API集成时使用此功能。

Sending & Composing

发送与撰写

Reference: references/sending-and-replying.md

Send emails, reply to conversations, forward messages, and manage drafts. Use this when the user needs to compose or respond to emails.

参考：references/sending-and-replying.md

发送邮件、回复对话、转发消息和管理草稿。当用户需要撰写或回复邮件时使用此功能。

Reading & Searching

查看与搜索

Reference: references/reading-and-searching.md

List, filter, read, and search emails. View conversations as threads. Use this when the user wants to check inbox, find specific emails, or follow a conversation.

参考：references/reading-and-searching.md

列出、筛选、查看和搜索邮件。以对话线程形式查看邮件。当用户想要查看收件箱、查找特定邮件或跟进对话时使用此功能。

Organization

邮件整理

Reference: references/organization.md

Organize emails with tags, folders, stars, flags, and trash management. Use this when the user wants to categorize, prioritize, or clean up their mailbox.

参考：references/organization.md

使用标签、文件夹、星标、标记和垃圾箱管理来整理邮件。当用户想要分类、优先级排序或清理邮箱时使用此功能。

Accounts & Sync

账户与同步

Reference: references/accounts-and-sync.md

Manage multiple email accounts, configure IMAP/SMTP, run background sync daemon. Includes provider settings table (Gmail, Outlook, QQ Mail, etc.) and troubleshooting. Use this for setup, connectivity issues, or multi-account workflows.

参考：references/accounts-and-sync.md

管理多个邮件账户、配置IMAP/SMTP、运行后台同步守护进程。包含服务商设置表（Gmail、Outlook、QQ邮箱等）和故障排除指南。用于设置、连接问题或多账户工作流。

Automation

自动化

Reference: references/automation.md

Email templates with variables, signatures, desktop notifications, spam filtering, contact management, and import/export. Use this when the user wants to automate repetitive email tasks or manage contacts and spam.

参考：references/automation.md

带有变量的邮件模板、签名、桌面通知、垃圾邮件过滤、联系人管理以及导入/导出功能。当用户想要自动化重复邮件任务或管理联系人和垃圾邮件时使用此功能。

Key Principles

核心原则

Sync before read: Local storage is offline-first. Always
```
mail-cli sync
```
before listing or searching if fresh data is expected.
Confirm before send: Always verify recipient, subject, and content with the user before executing
```
send
```
,
```
reply
```
, or
```
forward
```
.
Non-destructive by default:
```
delete
```
moves to trash. Only use
```
--permanent
```
when the user explicitly requests irreversible deletion.
Use
--yes
for automation: Skip interactive confirmation prompts in automated workflows.
Use
--format json
for parsing: When the agent needs to parse output programmatically, use JSON format. Use
```
--format markdown
```
when output is consumed by an LLM.
Use
--fields
to reduce noise: Request only the fields needed (e.g.
```
--fields id,subject,from
```
) to keep output focused and reduce token usage.
Check exit codes for error handling: Exit codes indicate error category (0=success, 1=general, 2=validation, 3=network, 4=auth). Branch logic based on exit code instead of parsing error text.
Templates over repetition: If the user sends similar emails more than twice, create a template.
Tags for cross-cutting, folders for exclusive: An email can have multiple tags but belongs to one folder.

先同步再查看：本地存储采用离线优先策略。如果需要最新数据，在列出或搜索前务必执行
```
mail-cli sync
```
。
发送前确认：在执行
```
send
```
、
```
reply
```
或
```
forward
```
命令前，务必与用户确认收件人、主题和内容。
默认非破坏性操作：
```
delete
```
命令会将邮件移至垃圾箱。仅当用户明确要求不可逆删除时才使用
```
--permanent
```
参数。
自动化时使用--yes：在自动化工作流中跳过交互式确认提示。
解析时使用--format json：当Agent需要以程序化方式解析输出时，使用JSON格式。当输出供LLM使用时，使用
```
--format markdown
```
。
使用--fields减少冗余：仅请求所需字段（例如
```
--fields id,subject,from
```
），以保持输出聚焦并减少令牌使用量。
通过退出码处理错误：退出码指示错误类别（0=成功，1=常规错误，2=验证错误，3=网络错误，4=认证错误）。根据退出码分支逻辑，而非解析错误文本。
用模板替代重复操作：如果用户发送相似邮件超过两次，请创建模板。
标签用于交叉分类，文件夹用于专属分类：一封邮件可拥有多个标签，但只能属于一个文件夹。