mailgun-cli

CLI for Mailgun domain management, DNS records, routes, and event logs.

Prerequisites

• Node.js 18+
• Mailgun API key (Settings → API Keys in the Mailgun dashboard)

Setup

cd ~/tools/mailgun-cli
npm install
npm run build
npm link

# Configure credentials
cp .env.example .env
# Edit .env and add your MAILGUN_API_KEY

Commands

Domains

# List all domains
mailgun-cli domains list

# Add a new domain
mailgun-cli domains add example.com
mailgun-cli domains add example.com --wildcard

# Show domain details (includes full DNS records)
mailgun-cli domains show example.com

# Get just the DNS records you need to set
mailgun-cli dns example.com

# Verify DNS after configuration
mailgun-cli domains verify example.com

# Delete a domain
mailgun-cli domains delete example.com

Routes

# List all routes
mailgun-cli routes list

# Show a specific route
mailgun-cli routes show ROUTE_ID

# Create a route (multiple --action flags supported)
mailgun-cli routes create \
  --expression 'match_recipient(".*@example.com")' \
  --action 'forward("https://example.com/hook")' \
  --action 'stop()' \
  --description "Forward example.com to webhook"

# Delete a route
mailgun-cli routes delete ROUTE_ID

Events

# List recent events for a domain
mailgun-cli events list example.com

# Filter by event type
mailgun-cli events list example.com --event delivered
mailgun-cli events list example.com --event failed
mailgun-cli events list example.com --event accepted

# Filter by sender/recipient
mailgun-cli events list example.com --from "sender@example.com"
mailgun-cli events list example.com --to "recipient@example.com"

# Pagination
mailgun-cli events list example.com --limit 50

Typical Workflow: Adding a New Domain

1. Add the domain: mailgun-cli domains add mydomain.com
2. Get DNS records: mailgun-cli dns mydomain.com
3. Set the DNS records at your DNS provider (the output shows exactly what TXT, MX, and CNAME records to create)
4. Verify: mailgun-cli domains verify mydomain.com
5. Check: mailgun-cli dns mydomain.com — all records should show "valid": "valid"

Output Format

All commands output JSON with the standard {ok, data} envelope:

{"ok": true, "data": { ... }}
{"ok": false, "error": "message"}

Pipe through jq for pretty output or extract specific fields.