Does this send or reply to email?

The documented commands cover reading, searching, OTP extraction, marking/archiving/deleting messages, and address lifecycle operations. No send or reply endpoint is documented in the skill.

How does OTP extraction work?

`shellmail.sh otp` returns the latest code immediately; `--wait ` blocks up to that long for a new one, and `--from ` filters by sender domain.

What happens when I delete my account?

The address enters a 14-day hold window and can only be reclaimed through the original recovery email.

Coding

ShellMail - Email Built for AI Agents

Try it

Read, search, and pull OTP codes from a shellmail.ai inbox, with inbox and address management.

What it does

An email client wrapper around the shellmail.ai API. List inbox messages (with an --unread filter), read full messages, extract OTP codes (optionally waiting up to 30s and filtering by sender domain), and search by keyword, OTP flag, or sender. Mark messages as read, archive, or delete them, and run a health check. On the account side, create a new address (manually or with the `auto` keyword for a random name like swift-reef-4821), recover an existing inbox through its recovery email, or permanently delete the account — deleted addresses enter a 14-day hold. All calls use Bearer token auth against https://shellmail.ai.

When to use it

Polling for verification/OTP codes from automated sign-ups
Checking the unread inbox on a shellmail.ai address
Searching past mail by sender or for OTPs
Reclaiming a deleted address within the 14-day hold window

The skill document

ShellMail

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
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

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

Commands

{baseDir}/scripts/shellmail.sh

Check Inbox

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

Read Email

{baseDir}/scripts/shellmail.sh read

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 
{baseDir}/scripts/shellmail.sh archive 
{baseDir}/scripts/shellmail.sh delete 
{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}

Questions people ask

Does this send or reply to email?: The documented commands cover reading, searching, OTP extraction, marking/archiving/deleting messages, and address lifecycle operations. No send or reply endpoint is documented in the skill.
How does OTP extraction work?: `shellmail.sh otp` returns the latest code immediately; `--wait <seconds>` blocks up to that long for a new one, and `--from <domain>` filters by sender domain.
What happens when I delete my account?: The address enters a 14-day hold window and can only be reclaimed through the original recovery email.

Related skills

Agent Email Inbox - Anima

Give your AI agent its own real email inbox - an address it owns, that sends and receives, with replies threading back to the agent instead of a human's mailbox. Provisioned in about a minute, free tier, no card. Use when an agent needs to send mail as itself, read what comes back, or act on inbound email.