Description

Email API for AI agents. Check inbox, read emails, extract OTP codes, search messages via ShellMail. Trigger on "check email", "inbox", "otp", "verification...

README (SKILL.md)

ShellMail

Name: ShellMail - Email Built for AI Agents
Author: aaronbatchelder

Email for AI agents via shellmail.ai. Create inboxes, receive mail, extract OTPs automatically.

⚠️ Security & Privacy Notice

This skill requires a sensitive SHELLMAIL_TOKEN that grants full access to your inbox and OTPs.

When you set up this skill for the first time, you'll be instructed to save the token into agent configuration using gateway config.patch. This means:

The agent will retain persistent access to your ShellMail inbox
The token remains active until you explicitly revoke it or remove it from config
Only proceed if you fully trust shellmail.ai and understand these privacy implications

Best practices:

Use ShellMail for agent-related activities only, not personal email
Use disposable/separate recovery emails when possible
Review the gateway config.patch command output before confirming
Revoke access when you no longer need this skill

First-Time Setup

If no token is configured:

Ask user for desired email name (e.g., "atlas") and a recovery email
- Or use auto for the name to generate a random address (e.g., "swift-reef-4821")
Run: {baseDir}/scripts/shellmail.sh create \x3Cname> \x3Crecovery_email>
If the address is already taken:
- If the user says it was their old address: try creating with the same recovery email — deleted addresses are held for 14 days and can be reclaimed
- Otherwise: suggest a different name or use auto
- Do NOT suggest recovery unless the user confirms it's their previous inbox
Save the returned token:

gateway config.patch {"skills":{"entries":{"shellmail":{"env":{"SHELLMAIL_TOKEN":"sm_..."}}}}}

⚠️ Important: Before running this command, explain to the user:

This saves the token into agent configuration for persistent access
The agent will retain access to their inbox/OTPs until the token is removed or revoked
They should only proceed if they trust shellmail.ai and understand the privacy implications
Show them the exact command and ask for confirmation before executing

Tell user to save the token safely — it won't be shown again
Suggest user send a test email to their new address to verify it's working
Once they confirm, run inbox to show the test email arrived

Token Recovery

Only use recovery if the user explicitly says they lost access to an existing inbox they own:

{baseDir}/scripts/shellmail.sh recover \[email protected]> \x3Crecovery_email>

This sends a new token to the recovery email on file. Do not suggest this for "address taken" errors.

Commands

{baseDir}/scripts/shellmail.sh \x3Ccommand>

Check Inbox

{baseDir}/scripts/shellmail.sh inbox
{baseDir}/scripts/shellmail.sh inbox --unread

Read Email

{baseDir}/scripts/shellmail.sh read \x3Cemail_id>

Get OTP Code

# Get latest OTP
{baseDir}/scripts/shellmail.sh otp

# Wait up to 30 seconds for OTP
{baseDir}/scripts/shellmail.sh otp --wait 30

# Filter by sender
{baseDir}/scripts/shellmail.sh otp --wait 30 --from github.com

Search Emails

{baseDir}/scripts/shellmail.sh search --query "verification"
{baseDir}/scripts/shellmail.sh search --otp
{baseDir}/scripts/shellmail.sh search --from stripe.com

Other Commands

{baseDir}/scripts/shellmail.sh mark-read \x3Cid>
{baseDir}/scripts/shellmail.sh archive \x3Cid>
{baseDir}/scripts/shellmail.sh delete \x3Cid>
{baseDir}/scripts/shellmail.sh health

Common Patterns

User says "check my email":

{baseDir}/scripts/shellmail.sh inbox --unread

User says "get the verification code":

{baseDir}/scripts/shellmail.sh otp --wait 30

User says "wait for GitHub OTP":

{baseDir}/scripts/shellmail.sh otp --wait 30 --from github.com

Revoking Access

If the user wants to revoke the skill's access to their ShellMail inbox:

Remove Token from Config

gateway config.patch '{"skills":{"entries":{"shellmail":{"env":{"SHELLMAIL_TOKEN":""}}}}}'

Delete Account Entirely

{baseDir}/scripts/shellmail.sh delete-account

Note: Deleted addresses enter a 14-day hold window and can only be reclaimed by the original owner using the recovery email.

API Reference

Base URL: https://shellmail.ai

All endpoints use Authorization: Bearer $SHELLMAIL_TOKEN

Endpoint	Method	Description
`/api/mail`	GET	List emails (?unread=true&limit=50)
`/api/mail/:id`	GET	Read full email
`/api/mail/:id`	PATCH	Update {is_read, is_archived}
`/api/mail/:id`	DELETE	Delete email
`/api/mail/otp`	GET	Get OTP (?timeout=30000&from=domain)
`/api/mail/search`	GET	Search (?q=text&from=domain&has_otp=true)
`/api/addresses`	POST	Create {local, recovery_email}

Usage Guidance

This skill appears to do exactly what it says — it's a thin CLI wrapper around shellmail.ai that needs a bearer token to read/send mail and extract OTPs. Key things to consider before installing: 1) The SHELLMAIL_TOKEN grants full access to the inbox and OTPs; only store it if you trust shellmail.ai and the agent. 2) The skill's setup asks you to persist the token into the agent config (gateway config.patch) — that will give the agent ongoing access until you remove or revoke the token. Follow the SKILL.md advice: show the user the exact config.patch command and get explicit confirmation before executing. 3) Prefer using disposable or non-personal recovery emails and test with non-sensitive accounts. 4) If you want lower blast radius, avoid persisting the token (use session-based tokens or remove the token when finished) or revoke the token after use. 5) The script requires curl and python3 (and optionally jq); it makes only expected calls to shellmail.ai. If you need more assurance, review the upstream project at the provided GitHub link and confirm the token handling and retention policy on shellmail.ai.

Capability Analysis

Type: OpenClaw Skill Name: shellmail Version: 1.0.12 The shellmail skill provides a legitimate interface for AI agents to interact with the ShellMail API for managing emails and extracting OTPs. The bash script (scripts/shellmail.sh) is a well-structured wrapper using curl and safe JSON construction via jq or python3. The agent instructions in SKILL.md include explicit security warnings and require the agent to obtain user confirmation before persisting the sensitive SHELLMAIL_TOKEN using the gateway configuration, showing alignment with its stated purpose without hidden malicious behavior.

Capability Assessment

✓ Purpose & Capability

Name/description (email/OTP access) match the shipped script and declared requirements: the skill needs curl and python3 and a SHELLMAIL_TOKEN to call shellmail.ai endpoints. No unrelated credentials, binaries, or endpoints are requested.

ℹ Instruction Scope

SKILL.md instructs the agent to create/recover addresses, check inbox, read emails, extract OTPs, and to save the returned SHELLMAIL_TOKEN into agent configuration using gateway config.patch. Those steps are within the skill's purpose, but the instructions explicitly ask to persist a sensitive token and to collect a recovery email (PII) during setup; the README warns about this and instructs to request explicit user confirmation before saving the token.

✓ Install Mechanism

No install spec (instruction-only) and a small included shell wrapper; nothing is downloaded or extracted at install time. Risk from installation is low.

✓ Credentials

Only SHELLMAIL_TOKEN is required (plus optional SHELLMAIL_API_URL). These are proportionate to an email/OTP access skill. No unrelated secret or system credentials are requested.

ℹ Persistence & Privilege

always:false (no forced inclusion). However, SKILL.md explicitly instructs storing the SHELLMAIL_TOKEN into the agent's config (gateway config.patch), which grants persistent access to the inbox/OTPs until revoked. This persistence is functionally necessary but materially increases the skill's long‑term access; the skill warns users to confirm before saving the token.

Version History

v1.0.12

- Added version field to SKILL.md (now version 1.2.2). - Introduced a metadata block specifying requirements for openclaw, including required environment variables and binaries. - No functional or user-facing changes detected to documentation or usage instructions.

v1.0.11

- Added a dedicated security and privacy notice highlighting risks of granting inbox/OTP access to agents. - Expanded first-time setup instructions with stronger warnings and best practices for token usage. - Clarified token storage: users must confirm before saving tokens in agent config and should only proceed if they trust shellmail.ai. - Added guidance on revoking access (removing token from config or deleting account). - Improved recovery and address claim instructions to reflect safer and clearer processes.

v1.0.10

shellmail 1.0.10 - Adding email sending support

v1.0.9

shellmail 1.0.8 Security: - Fix RCE vulnerability in create/recover commands - JSON now built safely via jq or python sys.argv - User input never interpolated into shell commands

v1.0.8

shellmail 1.0.8 Security: - Fix RCE vulnerability in create/recover commands - JSON now built safely via jq or python sys.argv - User input never interpolated into shell commands

v1.0.7

shellmail 1.0.6 Security: - Fix shell injection vulnerability in urlencode() function - Fix shell injection vulnerability in json_escape() function - User input now passed via stdin instead of string interpolation

v1.0.6

shellmail 1.0.6 Security: - Fix shell injection vulnerability in urlencode() function - Fix shell injection vulnerability in json_escape() function - User input now passed via stdin instead of string interpolation

v1.0.5

- Added a recommendation to send a test email to new inboxes during first-time setup. - Instruct users to confirm receipt of the test email and check the inbox to verify setup is working.

v1.0.4

Updated the recover behavior in the TUI.

v1.0.3

Resolve the "registry metadata omitted the required env var" warning.

v1.0.2

## 1.0.2 ### Security - Fix shell/JSON injection vulnerabilities in skill script - Add `urlencode()` for safe URL parameter encoding - Add `json_escape()` for safe JSON string embedding - Apply encoding to all user-supplied values in URLs and JSON payloads ### Changed - `create` and `recover` commands now properly escape user input in JSON payloads - All URL parameters (`--from`, `--query`, email IDs) are now URL-encoded

v1.0.1

Declared required env vars (SHELLMAIL_TOKEN) in manifest for security compliance. Added homepage and source links.

v1.0.0

Initial release - inbox, OTP extraction, search, webhooks

Metadata

Slug shellmail

Version 1.0.12

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 13

Frequently Asked Questions

What is ShellMail - Email Built for AI Agents?

Email API for AI agents. Check inbox, read emails, extract OTP codes, search messages via ShellMail. Trigger on "check email", "inbox", "otp", "verification... It is an AI Agent Skill for Claude Code / OpenClaw, with 743 downloads so far.

How do I install ShellMail - Email Built for AI Agents?

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

Is ShellMail - Email Built for AI Agents free?

Yes, ShellMail - Email Built for AI Agents is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does ShellMail - Email Built for AI Agents support?

ShellMail - Email Built for AI Agents is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created ShellMail - Email Built for AI Agents?

It is built and maintained by Aaron Batchelder (@aaronbatchelder); the current version is v1.0.12.

More Skills

ShellMail - Email Built for AI Agents