moemail/packages/cli

MoeMail CLI

Agent-first CLI for MoeMail temporary email service

Install

npm i -g @moemail/cli

Quick Start

1. Configure endpoint and API key

moemail config set api-url https://moemail.app
moemail config set api-key YOUR_API_KEY

Config is read from ~/.moemail/config.json, or overridden by the MOEMAIL_API_URL / MOEMAIL_API_KEY environment variables.

2. Create a temporary email

moemail create --expiry 1h

3. Wait for messages

moemail wait --email-id <email_id> --timeout 120

Command Reference

Command	Description	Key Flags
config set	Set api-url or api-key	config set <api-url|api-key> <value>
config list	Show current configuration	—
create	Create a temporary email address	--name <prefix>, --domain <domain>, --expiry <1h|24h|3d|permanent>, --json
list	List mailboxes, or messages in a mailbox	--email-id <id>, --cursor <cursor>, --json
wait	Wait for incoming messages	--email-id <id>, --timeout <seconds>, --interval <seconds>, --json
read	Read email message content	--email-id <id>, --message-id <id>, --format <text|html>, --json
send	Send email from temporary address	--email-id <id>, --to <address>, --subject <text>, --content <text>, --json
delete	Delete a mailbox, or a single message	--email-id <id>, --message-id <id>
skill install	Install AI agent skill	--platform <claude|codex|all>

Agent Workflow Example

The CLI is designed to support agent-first automation. Here's a typical workflow:

# Create temporary email and extract details
EMAIL=$(moemail create --domain moemail.app --expiry 1h --json)
EMAIL_ID=$(echo $EMAIL | jq -r '.id')
ADDRESS=$(echo $EMAIL | jq -r '.address')

# Use ADDRESS for signup or service registration...

# Wait for verification email
MSG=$(moemail wait --email-id $EMAIL_ID --timeout 120 --json)
MSG_ID=$(echo $MSG | jq -r '.messageId')

# Read message content
CONTENT=$(moemail read --email-id $EMAIL_ID --message-id $MSG_ID --json)

# Extract verification code from CONTENT...

# Cleanup
moemail delete --email-id $EMAIL_ID

AI Agent Skill

The CLI ships with a built-in skill file that teaches AI agents how to use MoeMail. Install it to your agent platform:

# Auto-detect installed platforms (Claude Code, Codex)
moemail skill install

# Install to a specific platform
moemail skill install --platform claude
moemail skill install --platform codex

# Install to all supported platforms (skip detection)
moemail skill install --platform all

After installation, AI agents will automatically know how to create temporary emails, wait for messages, and read content using the MoeMail CLI.

JSON Output

All commands support --json flag for structured output, making them ideal for agent automation:

• Success: Command output in JSON format to stdout
• Errors: Error messages written to stderr
• Exit Codes:
  • 0: Command succeeded
  • 1: Runtime error (invalid input, service error)
  • 2: Configuration or authentication error (missing api-url/api-key, invalid credentials)

Project Links

• Main Project: https://github.com/beilunyang/moemail
• Issues & Feedback: https://github.com/beilunyang/moemail/issues

License

MIT