b99b872791
Extract the HTTP client and config into a new @moemail/core package shared by the CLI and a new @moemail/mcp server, so both frontends talk to the same MoeMail API through one code path. - core: api client (now throws typed ConfigError/AuthError/PermissionError/ QuotaError instead of process.exit), config, msToIso, and a transport- agnostic pollForNewMessage helper. - cli: consume @moemail/core; route command errors through a shared fail() that preserves exit codes (config/auth = 2, else = 1). Bump to 1.0.0. - mcp: new stdio MCP server exposing 8 tools (create/list/read/wait/send/ delete); wait_for_email is bounded and returns a timeout status to retry. Configured via MOEMAIL_API_KEY / MOEMAIL_API_URL env. Release 1.0.0. Docs: - Fix packages/cli/README.md (config set, send --content not --body, full flag table). - Add MCP section to both root READMEs; complete the CLI command list (send, list, message-level delete). - SKILL.md: --json works before or after the subcommand. - Ignore bun.lock in package gitignores. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2.9 KiB
name, description
| name | description |
|---|---|
| moemail | Use when an AI agent needs a temporary/disposable email address — for receiving verification emails, testing email integrations, or any task requiring a temporary inbox via the moemail CLI |
MoeMail — Temporary Email for AI Agents
Overview
MoeMail provides disposable email addresses with an agent-first CLI (moemail). Create inboxes, wait for messages, read content, and send emails programmatically.
Install
Install the MoeMail CLI globally when it is not already available:
npm i -g @moemail/cli
Then confirm the binary is available:
moemail --help
Setup
Configure once per environment:
moemail config set api-url https://moemail.app
moemail config set api-key YOUR_API_KEY
Or via environment variables: MOEMAIL_API_URL, MOEMAIL_API_KEY.
Core Workflow: Receive an Email
# 1. Create inbox — capture ONCE, parse both fields
RESULT=$(moemail --json create --expiry 1h)
ID=$(echo "$RESULT" | jq -r '.id')
EMAIL=$(echo "$RESULT" | jq -r '.address')
# 2. Use $EMAIL wherever needed (registration, forms, etc.)
# 3. Wait for message (exits when message arrives or times out)
MSG=$(moemail --json wait --email-id "$ID" --timeout 120)
MSG_ID=$(echo "$MSG" | jq -r '.messageId')
# 4. Read full message content
moemail --json read --email-id "$ID" --message-id "$MSG_ID"
Command Reference
| Command | Required Options | Notable Options |
|---|---|---|
config set |
<key> <value> |
keys: api-url, api-key |
create |
— | --name, --domain, --expiry (1h|24h|3d|permanent) |
list |
— | --email-id (lists messages in mailbox), --cursor |
wait |
--email-id |
--timeout (default 120s), --interval (default 5s) |
read |
--email-id, --message-id |
--format (text|html) |
send |
--email-id, --to, --subject, --content |
— |
delete |
--email-id |
— |
--json is a global flag — it works before or after the subcommand:
moemail --json create --expiry 24h # both work
moemail create --expiry 24h --json
JSON Output Shapes
create: { "id": "...", "address": "user@domain.com", "expiresAt": "2025-..." }
wait: { "messageId": "...", "from": "...", "subject": "...", "receivedAt": "2025-..." }
read: { "id": "...", "from": "...", "to": "...", "subject": "...", "content": "plain text", "html": "...", "receivedAt": "..." }
send: { "success": true, "remainingEmails": 10 }
Common Mistakes
| Mistake | Fix |
|---|---|
Calling create twice to get id + address |
Call once, save to variable, parse both fields |
| Timeout too short for slow services | Use --timeout 300 for unreliable senders |
| Inbox expired mid-test | Use --expiry permanent for long-running workflows |
Using content field for HTML emails |
Check both content (plain text) and html fields |