> ## Documentation Index > Fetch the complete documentation index at: /docs/llms.txt > Use this file to discover all available pages before exploring further. # Mailofly CLI > The official command-line tool for Mailofly. Send emails, manage your account, and develop locally from the terminal. 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 > [tab] npm (Recommended) > > ```bash theme={null} > npm install -g @mailofly/cli > ``` > [tab] npx > > ```bash theme={null} > npx @mailofly/cli --help > ``` > [tab] cURL > > ```bash theme={null} > curl -fsSL https://mailofly.com/install.sh | bash > ``` > [tab] PowerShell (Windows) > > ```powershell theme={null} > 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`. ### `mailofly login` Authenticate by storing your API key locally. The key is validated against the Mailofly API before being saved. ```bash theme={null} mailofly login ``` In a terminal, the command prompts for your key via masked input. In non-interactive environments (CI, pipes), use the `--key` flag: ```bash theme={null} 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 ` | API key to store (required in non-interactive mode) | ### `mailofly logout` Remove your saved API key and profile: ```bash theme={null} mailofly logout ``` ### Switch between profiles If you work across multiple Mailofly teams or accounts, switch between profiles without logging in and out: ```bash theme={null} mailofly auth switch staging ``` Use the global `--profile` flag on any command to run it with a specific profile: ```bash theme={null} 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. ```bash theme={null} mailofly emails send \ --from "Acme " \ --to user@example.com \ --subject "Hello from Mailofly" \ --text "It works!" ``` | Flag | Required | Description | | :- | :- | :- | | `--from
` | Yes \* | Sender email address (must be from a verified domain) | | `--to ` | Yes | One or more recipient email addresses (space-separated) | | `--subject ` | Yes \* | Email subject line | | `--text ` | One of text/html | Plain text body | | `--text-file ` | One of text/html | Path to a plain text file (use `-` for stdin) | | `--html ` | One of text/html | HTML body as a string | | `--html-file ` | One of text/html | Path to an HTML file (use `-` for stdin) | | `--cc ` | No | CC recipients | | `--bcc ` | No | BCC recipients | | `--reply-to
` | No | Reply-to email address | | `--scheduled-at ` | No | Schedule for later (ISO 8601 or natural language) | | `--tags ` | No | Email tags as name=value pairs | | `--headers ` | No | Custom headers as key=value pairs | | `--template ` | No | Template ID to use | | `--var ` | No | Template variables as key=value pairs | \* Not required when using `--template`, which provides them. #### Examples ```bash theme={null} # HTML body from a local file mailofly emails send \ --from "Acme " \ --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 " \ --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 " \ --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: ```bash theme={null} mailofly emails batch --file ./emails.json ``` | Flag | Required | Description | | :- | :- | :- | | `--file ` | 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`: ```json emails.json theme={null} [ { "from": "Acme ", "to": ["alice@example.com"], "subject": "Hello Alice", "html": "

Welcome Alice!

", "scheduled_at": "in 1 hour" }, { "from": "Acme ", "to": ["bob@example.com"], "subject": "Hello Bob", "html": "

Welcome Bob!

" } ] ``` ### Other email commands ```bash theme={null} mailofly emails list # List sent emails mailofly emails get # Retrieve a sent email by ID mailofly emails cancel # Cancel a scheduled email mailofly emails update # Update a scheduled email's send time ``` ## Receiving Process inbound emails and attachments: ```bash theme={null} mailofly emails receiving list # List received (inbound) emails mailofly emails receiving get # Retrieve a received email with full details ``` ## Domains Manage your sending and receiving domains. ```bash theme={null} mailofly domains create --name mail.example.com --dkim-selector mailofly mailofly domains list # List all domains mailofly domains get # Retrieve domain with DNS verification records mailofly domains verify # Trigger DNS verification mailofly domains delete # Delete a sending domain ``` ## API Keys Create, list, and revoke API keys for programmatic access. ```bash theme={null} mailofly api-keys create --name "Production Backend" mailofly api-keys list # List all API keys mailofly api-keys delete # Delete an API key ``` ## Broadcasts Create and send broadcast campaigns to target audience segments. ```bash theme={null} # Create and send a broadcast immediately mailofly broadcasts create \ --name "Product Update" \ --subject "Introducing Mailofly CLI" \ --from "Acme " \ --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 # Retrieve broadcast details mailofly broadcasts send # Send a draft broadcast mailofly broadcasts delete # Delete a broadcast ``` ## Contacts Manage contacts and segment memberships. ```bash theme={null} # 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 # Retrieve a contact by ID mailofly contacts delete # Delete a contact mailofly contacts add-segment # Add contact to segment mailofly contacts remove-segment # Remove contact from segment ``` ## Segments Group contacts into targetable segments for broadcasts and automated sends. ```bash theme={null} mailofly segments create --name "VIP Customers" mailofly segments list # List all segments mailofly segments get # Retrieve a segment by ID mailofly segments contacts # List contacts in a segment mailofly segments delete # Delete a segment ``` ## Templates Create and manage reusable email templates. ```bash theme={null} mailofly templates create \ --name "Welcome Onboarding" \ --subject "Welcome to the team!" \ --html-file ./template.html mailofly templates list # List all templates mailofly templates get # Retrieve a template by ID mailofly templates delete # Delete a template ``` ## Logs View API request logs and delivery audit trails. ```bash theme={null} mailofly logs list # List recent API request logs mailofly logs list --limit 50 --page 2 mailofly logs get # Retrieve a log entry with full details mailofly logs open [id] # Open logs in the dashboard ``` ## Webhooks Register endpoints and listen for email delivery events. ### `mailofly webhooks create` Register a webhook endpoint: ```bash theme={null} mailofly webhooks create \ --endpoint https://example.com/api/webhooks/mailofly \ --events email.sent email.delivered email.bounced ``` | Flag | Required | Description | | :- | :- | :- | | `--endpoint ` | Yes | HTTPS URL to receive events | | `--name ` | No | Webhook display name | | `--events ` | No | Event types to subscribe to (default: `all`) | ### Other webhook commands ```bash theme={null} mailofly webhooks list # List all webhook endpoints mailofly webhooks get # Retrieve a webhook configuration mailofly webhooks delete # 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: ```bash theme={null} mailofly automations list mailofly automations list --status active --limit 50 ``` | Flag | Required | Description | | :- | :- | :- | | `--status ` | No | Filter by status (`active`, `draft`, `disabled`, `archived`) | | `--limit ` | No | Limit results (default `20`) | ### `mailofly automations get ` Inspect details of a workflow automation, including triggers, step definitions, and DAG connections: ```bash theme={null} mailofly automations get auto_12345 ``` ### `mailofly automations create` Create a new automation workflow directly or from a JSON DAG definition: ```bash theme={null} # 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 ` | Yes \* | Name of the automation (\* if not using `--file`) | | `-e, --event ` | No | Trigger event name (default `user.signup`) | | `-f, --file ` | No | Path to full DAG JSON configuration file | ### `mailofly automations stop ` Deactivate an automation and cancel any currently pending runs: ```bash theme={null} mailofly automations stop auto_12345 ``` ### `mailofly automations duplicate ` Clone an existing automation into a new draft workflow: ```bash theme={null} mailofly automations duplicate auto_12345 ``` ### `mailofly automations delete ` Permanently remove an automation: ```bash theme={null} mailofly automations delete auto_12345 ``` ### Execution runs Inspect execution history, status, and step logs for an automation: ```bash theme={null} # 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: ```bash theme={null} mailofly events send \ --name user.signed_up \ --contact user@example.com \ --data '{"plan":"pro","referrer":"google"}' ``` | Flag | Required | Description | | :- | :- | :- | | `-n, --name ` | Yes | Event name matching automation triggers | | `-c, --contact ` | Yes | Contact email address or ID | | `-d, --data ` | No | JSON object containing event properties | | `-p, --payload ` | No | Alias for `--data` | ### Other event commands ```bash theme={null} mailofly events list --limit 25 # List recent ingested event records mailofly events get # 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. ```bash theme={null} 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 | ```bash theme={null} # JSON output for automated health checks mailofly doctor --json ``` ```json theme={null} { "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: ```bash theme={null} mailofly [global options] [command options] ``` | Flag | Description | | :- | :- | | `--api-key ` | Override API key for this invocation | | `-p, --profile ` | Profile to use (overrides `MAILOFLY_PROFILE` env var) | | `--base-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: ```bash theme={null} mailofly doctor | jq '.checks[].name' mailofly emails send \ --from "Acme " \ --to user@example.com \ --subject "Hello" \ --text "Test message" | jq '.id' ``` Errors always exit with code `1` and output structured JSON in machine mode: ```json theme={null} { "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: ```yaml theme={null} # GitHub Actions env: MAILOFLY_API_KEY: ${{ secrets.MAILOFLY_API_KEY }} steps: - run: | npx @mailofly/cli emails send \ --from "Deploy " \ --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 | > [card] [API Reference](/docs/api/index.md) > > Explore the full Mailofly REST API documentation and endpoints. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.