Skip to main content

CLI Reference

The spawnmail package provides a command-line interface for SpawnMail.

Installation​

# Global install
bun add -g spawnmail

# Or use without installing
npx spawnmail <command>

Authentication​

# Store API key locally (~/.config/spawnmail/config.json)
spawnmail login --key sk_your_api_key

# Or use environment variable
export SPAWNMAIL_API_KEY=sk_your_api_key

Config resolution order:

  1. --key / --api flags (per-command override)
  2. SPAWNMAIL_API_KEY / SPAWNMAIL_API_URL environment variables
  3. ~/.config/spawnmail/config.json
info

The CLI defaults to https://api.spawnmail.sh. To use a different API endpoint, pass --api <url> or set SPAWNMAIL_API_URL.

Commands​

spawnmail create​

Create a new disposable inbox.

# Human-friendly output
spawnmail create
# → abc123def456@spawnmail.sh

# With TTL and password
spawnmail create --ttl 300 --password secret123

# JSON output (for scripting)
spawnmail create --json
# { "id": "abc123def456", "address": "abc123def456@spawnmail.sh", ... }

spawnmail read <inbox-id>​

List emails in an inbox.

# Human-friendly
spawnmail read <inbox-id>
# → { from: "noreply@example.com", subject: "Verify your email" }

# With password
spawnmail read <inbox-id> --password secret123

# JSON output
spawnmail read <inbox-id> --json

spawnmail wait <inbox-id>​

Wait for an email to arrive (long-poll).

# Wait up to 120s (default)
spawnmail wait <inbox-id>
# → { from: "noreply@example.com", subject: "Verify your email" }

# Custom timeout
spawnmail wait <inbox-id> --timeout 30

# With password and JSON output
spawnmail wait <inbox-id> --password secret123 --json

spawnmail destroy <inbox-id>​

Delete an inbox and all its emails.

spawnmail destroy <inbox-id>
# → gone.

Shell Scripting Patterns​

Create, Wait, and Read​

INBOX_JSON=$(spawnmail create --json)
INBOX_ID=$(echo "$INBOX_JSON" | jq -r '.id')
INBOX_ADDR=$(echo "$INBOX_JSON" | jq -r '.address')
echo "Send email to: $INBOX_ADDR"

# Wait for the email (blocks up to 30s)
EMAIL=$(spawnmail wait "$INBOX_ID" --timeout 30 --json)
echo "$EMAIL" | jq '.subject'

Create and Parse ID​

INBOX_JSON=$(spawnmail create --json)
INBOX_ID=$(echo "$INBOX_JSON" | jq -r '.id')
INBOX_ADDR=$(echo "$INBOX_JSON" | jq -r '.address')
echo "Created inbox: $INBOX_ADDR"

Wait for Email (Preferred)​

# Use wait instead of polling — blocks until email arrives
EMAIL=$(spawnmail wait "$INBOX_ID" --timeout 60 --json)

Poll for Emails (Alternative)​

for i in $(seq 1 12); do
  EMAILS=$(spawnmail read "$INBOX_ID" --json)
  COUNT=$(echo "$EMAILS" | jq 'length')
  if [ "$COUNT" -gt 0 ]; then
    echo "Got $COUNT email(s)"
    break
  fi
  sleep 5
done

Extract OTP from Email​

EMAILS=$(spawnmail read "$INBOX_ID" --json)
OTP=$(echo "$EMAILS" | jq -r '.[0].body_text' | grep -oE '[0-9]{4,8}' | head -1)
echo "OTP: $OTP"
EMAILS=$(spawnmail read "$INBOX_ID" --json)
LINK=$(echo "$EMAILS" | jq -r '.[0].body_text' | grep -oE 'https?://[^ ]*verif[^ ]*' | head -1)
echo "Verify link: $LINK"

Custom API URL​

# All commands accept --api flag for custom endpoints
spawnmail create --api http://localhost:8000
spawnmail read abc123 --api http://localhost:8000