Description

CLI to manage enterprise Outlook emails via Exchange Web Services (EWS). Use ews-mail.py to list, read, reply, forward, search, send, move, delete emails and...

README (SKILL.md)

EWS Email CLI

Name: Ews Email
Author: guyun94

A CLI for enterprise Exchange (EWS) email. Use when the user asks about email, inbox, messages, or mail.

Setup

1. 环境变量

在 ~/.openclaw/config.yaml 中配置：

env:
  EWS_SERVER: "your-exchange-server.com"
  EWS_EMAIL: "[email protected]"

2. 存储密码

macOS（自动使用 Keychain，无需额外配置）

pip3 install keyring exchangelib
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py setup

Linux 云服务器（无桌面环境）

脚本会自动检测 Linux 无桌面环境，切换到 EncryptedKeyring 后端（AES 加密文件存储）。

# 安装依赖
pip3 install keyring exchangelib keyrings.alt

# 设置 master password 环境变量（用于加解密 EWS 密码）
# 在 ~/.openclaw/config.yaml 中添加：
#   env:
#     KEYRING_CRYPTFILE_PASSWORD: "你自己定义的一个强密码"
#
# 或在 systemd service / 启动脚本中 export：
export KEYRING_CRYPTFILE_PASSWORD="你自己定义的一个强密码"

# 存储 EWS 密码（会用 AES 加密写入本地文件）
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py setup

# 验证
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py folder-list

重启后只要 KEYRING_CRYPTFILE_PASSWORD 环境变量还在，密码就能正常解密读取，无需重新输入。

3. 验证安装

python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py folder-list

SECURITY RULES

NEVER attempt to read, display, or output the EWS password.
NEVER run commands that could expose keyring contents.
NEVER include passwords in any output, log, or message.
The password is managed exclusively through the setup command.

IMPORTANT: Reading Email Content

To read the FULL content/body of an email, you MUST follow these two steps:

First run envelope-list to get the message list (this gives you numeric IDs)
Then run message-read \x3CID> to get the FULL email body/content

envelope-list only shows subject lines and metadata. It does NOT contain the email body. You MUST run message-read to get the actual email content. NEVER guess or summarize based on subject alone. NEVER say you cannot read email content — you CAN, by running message-read.

Script Location

~/.openclaw/skills/ews-email/scripts/ews-mail.py

Commands

List Emails (step 1 — metadata only)

python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py envelope-list
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py envelope-list --page 2 --page-size 20
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py envelope-list --folder "Sent"

Read Email Body (step 2 — REQUIRED for content)

python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py message-read \x3CID>

Search Emails

python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py envelope-list from [email protected]
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py envelope-list subject keyword

Send / Reply / Forward

python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py message-send --to "email" --subject "subject" --body "body"
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py message-send --to "[email protected]" --cc "[email protected]" --subject "Hi" --body "msg"
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py message-reply \x3CID> --body "reply text"
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py message-reply \x3CID> --body "reply text" --all
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py message-forward \x3CID> --to "email" --body "FYI"

Other Commands

python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py folder-list
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py message-move \x3CID> "Archive"
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py message-delete \x3CID>
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py attachment-download \x3CID> --dir ~/Downloads
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py flag-add \x3CID> --flag seen
python3 ~/.openclaw/skills/ews-email/scripts/ews-mail.py flag-remove \x3CID> --flag seen

Tips

Message IDs are numeric and come from the most recent envelope-list output.
Always run envelope-list first before message-read, message-reply, etc.
Long email bodies are truncated at 8000 chars.
Use --page and --page-size to navigate large inboxes.

Usage Guidance

This skill appears to be a legitimate EWS email CLI, but exercise caution before installing from an unknown source: 1) Verify and reconcile the env var requirements: set EWS_SERVER and EWS_EMAIL as documented (and KEYRING_CRYPTFILE_PASSWORD on headless Linux) — the registry entry omitted those. 2) Inspect the full script yourself (or run it in an isolated environment) since the package has no homepage and an unknown owner. 3) Be aware it will store an encrypted password via your system keyring (or an AES-encrypted keyring file if headless); protect the KEYRING_CRYPTFILE_PASSWORD and avoid putting it in world-readable config. 4) Note the script writes a cache at ~/.openclaw/.ews-mail-cache.json — protect that file. 5) If you need higher assurance, run the tool in a sandboxed account/container or ask the publisher for a verifiable source (homepage or signed release) before granting access to your mailbox.

Capability Analysis

Type: OpenClaw Skill Name: ews-email Version: 1.2.0 The skill bundle provides a legitimate CLI for managing Exchange (EWS) emails using the exchangelib and keyring libraries. It follows security best practices by storing credentials in the system keyring (or an encrypted file on headless Linux) rather than plain text, and the SKILL.md includes explicit safety instructions for the AI agent to prevent credential leakage. No evidence of data exfiltration, malicious execution, or obfuscation was found in ews-mail.py or the documentation.

Capability Assessment

ℹ Purpose & Capability

The code implements an Exchange Web Services CLI (listing, reading, sending, moving, deleting messages) which matches the name/description. However the registry metadata says "Required env vars: none" while the SKILL.md and script clearly require EWS_EMAIL and EWS_SERVER (and optionally KEYRING_CRYPTFILE_PASSWORD on headless Linux). That registry/instruction mismatch is inconsistent.

✓ Instruction Scope

Runtime instructions are scoped to email management: installing keyring/exchangelib, storing a password in the system keyring or encrypted keyring, and running the script to list/read/send/modify mail. The script reads/writes an on-disk cache (~/.openclaw/.ews-mail-cache.json) and uses the system keyring; it does not contact unexpected external endpoints beyond the Exchange server.

✓ Install Mechanism

This is instruction-only with one included Python script; required Python packages are standard (keyring, exchangelib, optional keyrings.alt). No remote downloads or obscure install URLs are used.

⚠ Credentials

Declared primaryEnv is EWS_EMAIL (appropriate). But SKILL.md and the script also require EWS_SERVER and may require KEYRING_CRYPTFILE_PASSWORD on headless Linux; these were not listed in the top-level 'Required env vars'. The script explicitly avoids storing the EWS password in env/config and instead uses the keyring, which is good, but you should confirm where KEYRING_CRYPTFILE_PASSWORD will be stored (env or config) because that master password protects the encrypted keyring file.

✓ Persistence & Privilege

The skill is not always-enabled and does not request elevated privileges. It stores a local cache (~/.openclaw/.ews-mail-cache.json) and uses the system keyring; it does not modify other skills or system-wide agent settings.

Version History

v1.2.0

v1.2.0: Linux headless server support - auto EncryptedKeyring with KEYRING_CRYPTFILE_PASSWORD

v1.1.0

**EWS Email 1.1.0 introduces secure keyring-based password storage and improved security practices.** - Passwords are now stored securely using the system keyring; plain text config files are no longer used. - New `setup` command added for storing credentials via the keyring. - Updated installation requirements: now depends on `keyring` and `exchangelib` Python packages. - Enhanced documentation to clarify secure setup and provide explicit security rules about handling passwords. - Environment variable configuration simplified; passwords are never output or logged.

v1.0.0

Initial release of ews-email CLI. - Manage enterprise Outlook emails using Exchange Web Services (EWS). - List, search, read (full content/bodies), send, reply, forward, move, and delete emails. - Download attachments, flag/unflag messages, and browse folders via the command line. - Requires environment variables: EWS_SERVER, EWS_EMAIL, EWS_PASSWORD. - Important: Reading full email content requires a separate `message-read <ID>` call after listing with `envelope-list`.

Metadata

Slug ews-email

Version 1.2.0

License MIT-0

All-time Installs 1

Active Installs 1

Total Versions 3

Frequently Asked Questions

What is Ews Email?

CLI to manage enterprise Outlook emails via Exchange Web Services (EWS). Use ews-mail.py to list, read, reply, forward, search, send, move, delete emails and... It is an AI Agent Skill for Claude Code / OpenClaw, with 488 downloads so far.

How do I install Ews Email?

Run "/install ews-email" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Ews Email free?

Yes, Ews Email is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Ews Email support?

Ews Email is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Ews Email?

It is built and maintained by guyun94 (@guyun94); the current version is v1.2.0.

More Skills

Ews Email