Description

Read and send email via IMAP/SMTP. Check for new/unread messages, fetch content, search mailboxes, mark as read/unread, and send emails with attachments, mar...

README (SKILL.md)

email-suite

Name: email-suite (imap+smtp)
Author: rashed-mamoon

Email CLI: node scripts/mail.js \x3Ccmd>. Works with Gmail, Outlook, Hostinger, any IMAP/SMTP server.

Setup

Automated (recommended)

bash setup.sh

Runs: Node.js check → npm install → provider menu → credentials → display name → signature → summary → connection test

Manual

npm install
cp env.example.txt .env   # Edit with your credentials

.env Configuration

Required

# IMAP (receiving)
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
[email protected]
IMAP_PASS=your_app_password

# SMTP (sending)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false          # true for port 465, false for 587
[email protected]
SMTP_PASS=your_app_password

Optional

[email protected]  # Default sender
FROM_NAME="Your Name"      # Display name shown to recipients
IMAP_REJECT_UNAUTHORIZED=false  # For self-signed certs
SMTP_REJECT_UNAUTHORIZED=false  # For self-signed certs

Provider Presets

Provider	IMAP Host	Port	SMTP Host	Port	Secure
Gmail	imap.gmail.com	993	smtp.gmail.com	587	false
Outlook	outlook.office365.com	993	smtp.office365.com	587	false
Hostinger	imap.hostinger.com	993	smtp.hostinger.com	465	true

Gmail/Outlook: Use App Password

Not your regular password — generate a 16-char App Password:

Gmail: myaccount.google.com/apppasswords
Outlook: Account → Security → App passwords

Essential Commands

Command	Description
`check`	Inbox from cache (~0.2s). Shows sync time. `--all` for read+unread combined.
`sync`	Fetch NEW messages only. Updates cache.
`fetch \x3Cuid>`	Read email. Shows action hints. Marks as read, updates cache.
`send --to x --subject "S" --body "B"`	Send email
`search --from "x" --since 7d`	Search cache. `--server` for full search.
`delete \x3Cuid>`	Delete permanently

Flags

--all — All messages (read + unread, combined chronological)
--limit N — Limit results
--since 7d — Time filter (7d, 1m, YYYY-MM-DD)
--before YYYY-MM-DD — Before date

Multi-ID

delete \x3Cuid1> \x3Cuid2>   # Delete multiple
mark-read \x3Cuid1> \x3Cuid2> # Mark multiple read

Send Options

--body-file x.md — Markdown auto-converted to HTML
--attach file.pdf — Attachments
reply \x3Cuid> --body "T" — Reply (auto Re: prefix)
forward \x3Cuid> --to x — Forward

Cache

.cache/inbox.json — Local cache for fast checks
sync = incremental (new msgs only)
fetch = always server, marks read, updates cache
delete / clear-cache = clears cache

Security

Never commit .env to git
chmod 600 .env to protect credentials
Use App Passwords for Gmail/Outlook (2FA required)

Usage Guidance

Before installing or running this skill: - Treat this as an email client: it requires your IMAP and SMTP credentials (or app passwords) and will store them in a local .env file. The registry metadata failing to list these env vars is an inconsistency — do not assume the skill needs no secrets. - Inspect the .env that setup.sh creates and prefer using provider app passwords (Gmail/Outlook) rather than your primary account password. Secure the file (chmod 600) and keep it out of version control. - Be aware the skill caches entire messages and attachments to .cache/inbox.json and .cache/attachments/. If those contain sensitive data, run in a controlled environment or change cache location/permissions. - Review package.json and the dependency list (multiple IMAP libraries increase attack surface). If you want tighter control, install dependencies yourself in a sandbox or audit the npm packages' versions before npm install. - The source/homepage is unknown and owner identity is minimal; if you need higher assurance, request source provenance or prefer a well-known, audited email client library. If you decide to proceed: run the setup and first tests in an isolated environment (VM or container), use app passwords, and carefully review .env and .cache contents afterward.

Capability Analysis

Type: OpenClaw Skill Name: email-suite-imap-smtp Version: 1.2.6 The email-suite-imap-smtp skill is a legitimate IMAP/SMTP email client implementation designed for CLI and AI agent use. It provides standard functionality for reading, sending, searching, and managing emails, including support for attachments and markdown-to-HTML conversion. The setup.sh script facilitates local configuration by creating a .env file for credentials and correctly recommends securing it with chmod 600. The code uses standard, reputable libraries such as nodemailer, imap, and mailparser, and shows no signs of data exfiltration, unauthorized remote execution, or malicious prompt injection.

Capability Assessment

⚠ Purpose & Capability

The skill's name and README claim an IMAP/SMTP email client and the bundled scripts clearly implement that. However the registry metadata lists no required environment variables or primary credential while the code and SKILL.md require IMAP_* and SMTP_* credentials (IMAP_HOST, IMAP_USER, IMAP_PASS, SMTP_HOST, SMTP_USER, SMTP_PASS, etc.). This inconsistency is an important red flag: the skill needs sensitive credentials but the metadata does not advertise them.

ℹ Instruction Scope

The runtime instructions (SKILL.md + setup.sh) are consistent with an email client: they prompt for provider/credentials, create a .env, run npm install, test IMAP/SMTP, and operate on mailbox data. The instructions explicitly tell users not to commit .env and to use app passwords. They also direct the agent to store a local cache (.cache/inbox.json) and attachments (.cache/attachments/) — which is expected for caching but results in persistent local copies of potentially sensitive emails and attachments.

ℹ Install Mechanism

There is no platform install spec in the registry (instruction-only), but the bundle includes a setup.sh that runs npm install (pulling dependencies from npm). Dependencies are standard for email (imap, mailparser, nodemailer, marked). A mild oddity: multiple IMAP libraries are included (imap, imap-simple, imapflow) which is unusual but not necessarily malicious — it increases dependency surface and should be reviewed. No remote downloads from untrusted URLs or URL shorteners are present.

⚠ Credentials

The code legitimately requires IMAP/SMTP credentials and other env vars (EMAIL_SIGNATURE, FROM_NAME, IMAP_REJECT_UNAUTHORIZED, SMTP_REJECT_UNAUTHORIZED). Declaring these as required in the skill metadata would be expected; omitting them in the registry metadata is incoherent and could mislead users. The number and sensitivity of env vars (account passwords/app-passwords) are proportionate for an email client but they must be transparently declared.

ℹ Persistence & Privilege

The skill is not marked always:true and does not request system-wide privileges. It writes .env, node_modules (via npm install), .cache/inbox.json, and .cache/attachments/ to the working directory. This persistent local storage is appropriate for a mail client but users should be aware that full message bodies and attachments will be stored on disk and therefore must secure those files (chmod, directory placement, backups).

Version History

v1.2.6

CHANGELOG.md with v1.2.4 documenting: - Fixed attachment detection in inbox list (📎 icon now works) - Fixed attachment content in read/download (full message parsing) - Fixed clear-cache command alias - Improved read output format for attachments

v1.2.5

**email-suite-imap-smtp v1.2.5 changelog** - Simplified configuration guide: replaced `.env.example.txt` (old dotfile) with easier-to-copy `env.example.txt`. - Updated documentation for improved clarity and quicker setup. - Added quick provider presets and security tips to reduce setup errors. - Streamlined essential commands and options overview. - Removed legacy or redundant details for a more concise readme.

v1.2.4

- Renamed sample environment file from env.example.txt to .env.example.txt. - Removed old env.example.txt, added new .env.example.txt for configuration reference. - No user-facing command or feature changes.

v1.2.3

No changes detected in this version. - Version 1.2.3 has no updates or modifications compared to the previous release.

v1.2.2

- Removed the sample cache file scripts/.cache/inbox.json from the repository. - No code or documentation changes; internal cache artifacts are no longer shipped with the skill.

v1.2.1

**Major update: Unified CLI and enhanced filtering.** - Introduced a single unified `mail.js` CLI for all IMAP/SMTP actions (check, fetch, search, send, reply, forward, etc.). - Added support for advanced search filters: date/time (`--since`, `--before`, e.g. `7d`, `1m`), multi-filter AND logic, and improved cache search. - Added new commands: `reply`, `forward`, and `stats`. - Codebase restructured: modular `utils` directory with split logic for args, format, env, IMAP, and SMTP. - Updated example environment file (`env.example.txt`). - Old commands via `imap.js` and `smtp.js` are still supported for backward compatibility.

v1.0.4

- Added actionable command hints after reading an email, showing available next actions (download, mark-read/unread, delete) with UIDs filled in. - Updated documentation to clarify incremental sync and cache usage for faster inbox checks and searches. - Added support and documentation for deleting emails (`delete`/`del` commands). - Improved description to highlight local caching (~0.2s), multi-filter search, markdown-to-HTML, and attachment handling. - Added CHANGELOG.md and env.txt; removed obsolete files (_meta.json, scripts/test-conn.js).

v1.0.3

Updated readme.md explanning **Exactly like:** Thunderbird, Outlook, Apple Mail - just CLI-based with caching for AI agents. ## Clawhub.ai False Positive Clawhub flagged this as "suspicious" - these are **false positives**: | Flag | Why | |------|-----| | "Environment variable access + network send" | Reading `IMAP_PASS` from `.env` to authenticate with email server - **legitimate** | | "File read + network send" | Saving email attachments to `.cache/attachments/` - **legitimate** | This is normal email client behavior. The skill: - ✅ Reads `.env` for Gmail/Outlook credentials - ✅ Connects to your email provider's server - ✅ Downloads attachments to your disk

v1.0.2

- Removes the sample `.env` file and the `scripts/check-inbox.js` script for security and maintenance. - Adds a `_meta.json` file. - Updates documentation to clarify IMAP/SMTP usage, streamline configuration examples, highlight local caching, and simplify command guides. - Focuses usage examples with an agent workflow section and trims repetitive setup/security warnings. - Ensures documentation now emphasizes safe credential practices without bundling sample credential files.

v1.0.1

- Added a dedicated "Security Notes" section with important instructions on protecting credentials and handling the `.env` file. - Clarified that `.env` files with real credentials must be kept out of version control and offered `.gitignore` guidance. - Provided explicit permission-setting instructions (`chmod 600 .env`) for sensitive files. - Noted that the setup helper script (`setup.sh`) creates a `.env` file and advised users to review it before use. - Removed outdated or redundant security instructions from other sections to avoid duplication.

v1.0.0

Initial release of email-suite-imap-smtp. - Read, search, and manage emails via IMAP (supports Gmail, Outlook, Hostinger, and standard servers). - Send emails via SMTP with support for attachments, markdown-to-HTML conversion, custom display names, and email signatures. - Includes command-line tools for checking, fetching, searching, downloading, and marking emails as read/unread. - Provides configuration examples for common email providers and detailed documentation for setup and usage. - Offers troubleshooting tips for connection, authentication, and certificate issues.

Metadata

Slug email-suite-imap-smtp

Version 1.2.6

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 11

Frequently Asked Questions

What is email-suite (imap+smtp)?

Read and send email via IMAP/SMTP. Check for new/unread messages, fetch content, search mailboxes, mark as read/unread, and send emails with attachments, mar... It is an AI Agent Skill for Claude Code / OpenClaw, with 231 downloads so far.

How do I install email-suite (imap+smtp)?

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

Is email-suite (imap+smtp) free?

Yes, email-suite (imap+smtp) is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does email-suite (imap+smtp) support?

email-suite (imap+smtp) is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created email-suite (imap+smtp)?

It is built and maintained by Rashed Al Mamoon (@rashed-mamoon); the current version is v1.2.6.

More Skills

email-suite (imap+smtp)