Mailofly CLI - Mailofly

The Mailofly CLI is the official command-line interface for Mailofly. It covers the full API surface and is built for developers, AI agents, and CI/CD pipelines.

Installation

npm (Recommended)
npx
cURL
PowerShell (Windows)

npm install -g @mailofly/cli

npx @mailofly/cli --help

curl -fsSL https://mailofly.com/install.sh | bash

irm https://mailofly.com/install.ps1 | iex

Authentication

The CLI resolves your API key using the following priority chain:

Priority	Source	How to set
1 (highest)	`--api-key` flag	`mailofly --api-key mf_live_xxx emails send ...`
2	`MAILOFLY_API_KEY` env var	`export MAILOFLY_API_KEY=mf_live_xxx`
3 (lowest)	Saved credentials	`mailofly login`

If no key is found from any source, the CLI errors with code auth_error. Authenticate by storing your API key locally. The key is validated against the Mailofly API before being saved.

mailofly login

In a terminal, the command prompts for your key via masked input. In non-interactive environments (CI, pipes), use the --key flag:

mailofly login --key mf_live_xxxxxxxxxxxxx

Credentials are saved to your configuration directory (~/.config/mailofly/credentials.json on macOS/Linux or %APPDATA%\mailofly\credentials.json on Windows).

Flag	Description
`--key <key>`	API key to store (required in non-interactive mode)

`mailofly logout`

Remove your saved API key and profile:

mailofly logout

Switch between profiles

If you work across multiple Mailofly teams or accounts, switch between profiles without logging in and out:

mailofly auth switch staging

Use the global --profile flag on any command to run it with a specific profile:

mailofly domains list --profile production

Other profile management commands:

Command	Description
`mailofly auth list`	List all saved authentication profiles
`mailofly auth switch [name]`	Switch the active profile
`mailofly auth rename [old] [new]`	Rename a profile
`mailofly auth remove [name]`	Remove a profile
`mailofly whoami`	Show current authentication status

Emails

Send, retrieve, cancel, and manage email delivery.

`mailofly emails send`

Send an email. Provide all options via flags for scripting, or pass template variables and attachments.

mailofly emails send \
  --from "Acme <onboarding@yourdomain.com>" \
  --to user@example.com \
  --subject "Hello from Mailofly" \
  --text "It works!"

Flag	Required	Description
`--from <address>`	Yes *	Sender email address (must be from a verified domain)
`--to <addresses...>`	Yes	One or more recipient email addresses (space-separated)
`--subject <subject>`	Yes *	Email subject line
`--text <text>`	One of text/html	Plain text body
`--text-file <path>`	One of text/html	Path to a plain text file (use `-` for stdin)
`--html <html>`	One of text/html	HTML body as a string
`--html-file <path>`	One of text/html	Path to an HTML file (use `-` for stdin)
`--cc <addresses...>`	No	CC recipients
`--bcc <addresses...>`	No	BCC recipients
`--reply-to <address>`	No	Reply-to email address
`--scheduled-at <datetime>`	No	Schedule for later (ISO 8601 or natural language)
`--tags <name=value...>`	No	Email tags as name=value pairs
`--headers <key=value...>`	No	Custom headers as key=value pairs
`--template <id>`	No	Template ID to use
`--var <key=value...>`	No	Template variables as key=value pairs

* Not required when using --template, which provides them.

Examples

# HTML body from a local file
mailofly emails send \
  --from "Acme <onboarding@yourdomain.com>" \
  --to user@example.com \
  --subject "Welcome to Acme" \
  --html-file ./welcome.html

# Multiple recipients with CC, BCC, and reply-to
mailofly emails send \
  --from "Acme <onboarding@yourdomain.com>" \
  --to user1@example.com user2@example.com \
  --subject "Project Update" \
  --text "The project has been deployed." \
  --cc team@example.com \
  --bcc archive@example.com \
  --reply-to support@yourdomain.com

# Send with a pre-configured template and dynamic variables
mailofly emails send \
  --from "Acme <onboarding@yourdomain.com>" \
  --to user@example.com \
  --template tmpl_welcome_v1 \
  --var "name=Alice" --var "company=Acme"

`mailofly emails batch`

Send up to 100 emails in a single API request from a JSON file:

mailofly emails batch --file ./emails.json

Flag	Required	Description
`--file <path>`	Yes	Path to JSON file containing array of email objects (use `-` for stdin)

Each email in the JSON array supports the same fields as mailofly emails send:

emails.json

[
  {
    "from": "Acme <onboarding@yourdomain.com>",
    "to": ["alice@example.com"],
    "subject": "Hello Alice",
    "html": "<h1>Welcome Alice!</h1>",
    "scheduled_at": "in 1 hour"
  },
  {
    "from": "Acme <onboarding@yourdomain.com>",
    "to": ["bob@example.com"],
    "subject": "Hello Bob",
    "html": "<p>Welcome Bob!</p>"
  }
]

Other email commands

mailofly emails list               # List sent emails
mailofly emails get <id>           # Retrieve a sent email by ID
mailofly emails cancel <id>        # Cancel a scheduled email
mailofly emails update <id>        # Update a scheduled email's send time

Receiving

Process inbound emails and attachments:

mailofly emails receiving list     # List received (inbound) emails
mailofly emails receiving get <id> # Retrieve a received email with full details

Domains

Manage your sending and receiving domains.

mailofly domains create --name mail.example.com --dkim-selector mailofly
mailofly domains list              # List all domains
mailofly domains get <id>          # Retrieve domain with DNS verification records
mailofly domains verify <id>       # Trigger DNS verification
mailofly domains delete <id>       # Delete a sending domain

API Keys

Create, list, and revoke API keys for programmatic access.

mailofly api-keys create --name "Production Backend"
mailofly api-keys list             # List all API keys
mailofly api-keys delete <id>      # Delete an API key

Broadcasts

Create and send broadcast campaigns to target audience segments.

# Create and send a broadcast immediately
mailofly broadcasts create \
  --name "Product Update" \
  --subject "Introducing Mailofly CLI" \
  --from "Acme <onboarding@yourdomain.com>" \
  --segment-id seg_prod_users \
  --html-file ./broadcast.html \
  --send

# Manage broadcasts
mailofly broadcasts list           # List all broadcasts (alias: mailofly campaigns list)
mailofly broadcasts get <id>       # Retrieve broadcast details
mailofly broadcasts send <id>      # Send a draft broadcast
mailofly broadcasts delete <id>    # Delete a broadcast

Contacts

Manage contacts and segment memberships.

# Create a contact
mailofly contacts create --email user@example.com --first-name Alex --last-name Smith

# List and manage contacts
mailofly contacts list             # List audience contacts
mailofly contacts list --segment-id seg_vip --limit 50
mailofly contacts get <id>         # Retrieve a contact by ID
mailofly contacts delete <id>      # Delete a contact
mailofly contacts add-segment <id> <segment-id>     # Add contact to segment
mailofly contacts remove-segment <id> <segment-id>  # Remove contact from segment

Segments

Group contacts into targetable segments for broadcasts and automated sends.

mailofly segments create --name "VIP Customers"
mailofly segments list             # List all segments
mailofly segments get <id>         # Retrieve a segment by ID
mailofly segments contacts <id>    # List contacts in a segment
mailofly segments delete <id>      # Delete a segment

Templates

Create and manage reusable email templates.

mailofly templates create \
  --name "Welcome Onboarding" \
  --subject "Welcome to the team!" \
  --html-file ./template.html

mailofly templates list            # List all templates
mailofly templates get <id>        # Retrieve a template by ID
mailofly templates delete <id>     # Delete a template

Logs

View API request logs and delivery audit trails.

mailofly logs list                 # List recent API request logs
mailofly logs list --limit 50 --page 2
mailofly logs get <id>             # Retrieve a log entry with full details
mailofly logs open [id]            # Open logs in the dashboard

Webhooks

`mailofly webhooks create`

mailofly webhooks create \
  --endpoint https://example.com/api/webhooks/mailofly \
  --events email.sent email.delivered email.bounced

Flag	Required	Description
`--endpoint <url>`	Yes	HTTPS URL to receive events
`--name <name>`	No	Webhook display name
`--events <types...>`	No	Event types to subscribe to (default: `all`)

Other webhook commands

mailofly webhooks list             # List all webhook endpoints
mailofly webhooks get <id>         # Retrieve a webhook configuration
mailofly webhooks delete <id>      # Delete a webhook endpoint

Automations

Manage workflow automations, execution runs, and DAG step pipelines.

`mailofly automations list`

List all automations with their current status, trigger type, and step count:

mailofly automations list
mailofly automations list --status active --limit 50

Flag	Required	Description
`--status <status>`	No	Filter by status (`active`, `draft`, `disabled`, `archived`)
`--limit <number>`	No	Limit results (default `20`)

`mailofly automations get <id>`

Inspect details of a workflow automation, including triggers, step definitions, and DAG connections:

mailofly automations get auto_12345

`mailofly automations create`

Create a new automation workflow directly or from a JSON DAG definition:

# Create a draft workflow triggered by a signup event
mailofly automations create --name "User Welcome Flow" --event user.signup

# Create from a workflow DAG definition file
mailofly automations create --file ./workflow.json

Flag	Required	Description
`-n, --name <name>`	Yes *	Name of the automation (* if not using `--file`)
`-e, --event <event>`	No	Trigger event name (default `user.signup`)
`-f, --file <path>`	No	Path to full DAG JSON configuration file

`mailofly automations stop <id>`

Deactivate an automation and cancel any currently pending runs:

mailofly automations stop auto_12345

`mailofly automations duplicate <id>`

Clone an existing automation into a new draft workflow:

mailofly automations duplicate auto_12345

`mailofly automations delete <id>`

Permanently remove an automation:

mailofly automations delete auto_12345

Execution runs

Inspect execution history, status, and step logs for an automation:

# List runs for an automation
mailofly automations runs list auto_12345 --status running

# Inspect detailed step execution history for a specific run
mailofly automations runs get auto_12345 run_67890

Events

Publish custom business events to trigger workflow automations or satisfy wait-for-event steps.

`mailofly events send`

Publish an event into Mailofly:

mailofly events send \
  --name user.signed_up \
  --contact user@example.com \
  --data '{"plan":"pro","referrer":"google"}'

Flag	Required	Description
`-n, --name <event>`	Yes	Event name matching automation triggers
`-c, --contact <email>`	Yes	Contact email address or ID
`-d, --data <json>`	No	JSON object containing event properties
`-p, --payload <json>`	No	Alias for `--data`

Other event commands

mailofly events list --limit 25     # List recent ingested event records
mailofly events get <id>           # Retrieve event details and JSON payload

Utility

Diagnose your environment and inspect authentication status.

`mailofly doctor`

Run environment and connectivity diagnostics. Verifies your CLI version, API key, credential storage, and domain connection status.

mailofly doctor

Check	Pass	Warn	Fail
CLI Version	Running latest	Update available	N/A
API Key	Key found (shows masked key + source)	N/A	No key found
Credential Storage	Configuration file exists	File not created yet	N/A
API Validation	Verified domains exist	Key valid but 0 domains connected	API key invalid or unreachable

# JSON output for automated health checks
mailofly doctor --json

{
  "ok": true,
  "checks": [
    { "name": "CLI Version", "status": "pass", "message": "v1.0.0 (latest)" },
    { "name": "API Key", "status": "pass", "message": "mf_live_...9421 (source: env)" },
    { "name": "Credential Storage", "status": "pass", "message": "C:\\Users\\User\\AppData\\Roaming\\mailofly\\credentials.json" },
    { "name": "API Validation", "status": "pass", "message": "2 domain(s) connected (2 verified, 0 pending)" }
  ]
}

Exits 0 when all checks pass or warn. Exits 1 if any check fails.

Other utility commands

Command	Description
`mailofly whoami`	Show current authentication status
`mailofly open [destination]`	Open the Mailofly dashboard in your web browser (e.g. `mailofly open domains`)

Global options

These flags work on every command:

mailofly [global options] <command> [command options]

Flag	Description
`--api-key <key>`	Override API key for this invocation
`-p, --profile <name>`	Profile to use (overrides `MAILOFLY_PROFILE` env var)
`--base-url <url>`	Override API base URL (default: `https://api.mailofly.com`)
`--json`	Force JSON output even in interactive terminals
`-q, --quiet`	Suppress spinners and status output (implies `--json`)
`-v, --version`	Print version and exit
`-h, --help`	Show help text

Output behavior

The CLI has two output modes that switch automatically:

Mode	When	Stdout	Stderr
Interactive	Terminal (TTY)	Formatted text & tables	Status and errors
Machine	Piped, CI, or `--json`	JSON	Nothing

Pipe to another command and JSON output activates automatically:

mailofly doctor | jq '.checks[].name'
mailofly emails send \
  --from "Acme <onboarding@yourdomain.com>" \
  --to user@example.com \
  --subject "Hello" \
  --text "Test message" | jq '.id'

Errors always exit with code 1 and output structured JSON in machine mode:

{
  "error": {
    "message": "No API key found. Authenticate using 'mailofly login'",
    "code": "auth_error"
  }
}

CI/CD

Set MAILOFLY_API_KEY as an environment variable, with no mailofly login needed:

# GitHub Actions
env:
  MAILOFLY_API_KEY: ${{ secrets.MAILOFLY_API_KEY }}
steps:
  - run: |
      npx @mailofly/cli emails send \
        --from "Deploy <deploy@yourdomain.com>" \
        --to team@yourdomain.com \
        --subject "Deployment Succeeded" \
        --text "Commit ${{ github.sha }} deployed successfully."

Configuration

Item	Path	Notes
Config directory	`~/.config/mailofly/`	Respects `$XDG_CONFIG_HOME` on Linux, `%APPDATA%` on Windows
Credentials file	`credentials.json`	Stores profiles and base URL settings

API Reference

Explore the full Mailofly REST API documentation and endpoints.

​Installation

​Authentication

​mailofly login

​mailofly logout

​Switch between profiles

​Emails

​mailofly emails send

​Examples

​mailofly emails batch

​Other email commands

​Receiving

​Domains

​API Keys

​Broadcasts

​Contacts

​Segments

​Templates

​Logs

​Webhooks

​mailofly webhooks create

​Other webhook commands

​Automations

​mailofly automations list

​mailofly automations get <id>

​mailofly automations create

​mailofly automations stop <id>

​mailofly automations duplicate <id>

​mailofly automations delete <id>

​Execution runs

​Events

​mailofly events send

​Other event commands

​Utility

​mailofly doctor

​Other utility commands

​Global options

​Output behavior

​CI/CD

​Configuration