MailerSend CLI

A command-line interface for the MailerSend API. Send emails and SMS, manage domains, templates, webhooks, recipients, suppressions, and more — all from your terminal.

The CLI also includes an interactive TUI dashboard for monitoring your email activity, analytics, domains, and suppressions in real time.

GitHub Repositoryopen in new window

Installation

Homebrew (macOS)

brew install --cask mailersend/tap/mailersend

GitHub Releases

Download pre-built binaries for Linux, macOS, and Windows from the releases pageopen in new window.

Go install

go install github.com/mailersend/mailersend-cli@latest

From source

Requires Go 1.25+.

git clone https://github.com/mailersend/mailersend-cli.git
cd mailersend-cli
go build -o mailersend .

Move the binary to somewhere on your $PATH:

sudo mv mailersend /usr/local/bin/

Nix

Run directly without installing:

nix run git+ssh://git@github.com/mailersend/mailersend-cli.git

Or install into your profile:

nix profile install git+ssh://git@github.com/mailersend/mailersend-cli.git

Authentication

The CLI supports two authentication methods: OAuth (recommended) and API token.

OAuth (recommended)

mailersend auth login

This opens your browser to authorize the CLI with your MailerSend account. OAuth tokens are automatically refreshed when they expire.

API Token

mailersend auth login --method token

You'll be prompted to enter your MailerSend API token. You can generate one from your MailerSend dashboardopen in new window under API Tokens.

Environment variable

You can also set the API token via environment variable:

export MAILERSEND_API_TOKEN="mlsn.your_token_here"

Token resolution order: MAILERSEND_API_TOKEN env var > --profile flag > active profile > first profile.

Multiple profiles

Manage multiple profiles for different accounts or environments:

# Add profiles
mailersend profile add --name staging
mailersend profile add --name production

# List profiles
mailersend profile list

# Switch active profile
mailersend profile switch staging

# Use a specific profile for one command
mailersend domain list --profile production

Auth status and logout

# Check auth status
mailersend auth status

# Log out
mailersend auth logout

Global flags

Every command supports these flags:

Flag	Description
`--json`	Output raw JSON instead of formatted tables
`--verbose`, `-v`	Print HTTP request and response details
`--profile <name>`	Use a specific auth profile
`--help`, `-h`	Show help for any command

Commands

Email

# Send an email
mailersend email send \
  --from "sender@yourdomain.com" \
  --from-name "Sender Name" \
  --to "recipient@example.com" \
  --to-name "Recipient" \
  --subject "Hello" \
  --text "Plain text body" \
  --html "<h1>HTML body</h1>"

# Send from a file
mailersend email send \
  --from "sender@yourdomain.com" \
  --to "recipient@example.com" \
  --subject "Newsletter" \
  --html-file ./newsletter.html \
  --text-file ./newsletter.txt

# Send using a template
mailersend email send \
  --from "sender@yourdomain.com" \
  --to "recipient@example.com" \
  --template-id "x2p0347z969lzdrn"

# Schedule an email (unix timestamp)
mailersend email send \
  --from "sender@yourdomain.com" \
  --to "recipient@example.com" \
  --subject "Scheduled" \
  --text "This is scheduled" \
  --send-at 1735689600

# With tracking and tags
mailersend email send \
  --from "sender@yourdomain.com" \
  --to "recipient@example.com" \
  --subject "Tracked" \
  --text "Body" \
  --track-opens --track-clicks \
  --tags "campaign,welcome"

Send email flags

Flag	Type	Required	Description
`--from`	string	yes*	Sender email address. *Not required if `--template-id` is set with a default sender.
`--from-name`	string	no	Sender display name
`--to`	string	yes	Recipient email address
`--to-name`	string	no	Recipient display name
`--cc`	string	no	CC email address
`--bcc`	string	no	BCC email address
`--reply-to`	string	no	Reply-to email address
`--subject`	string	yes*	Email subject. *Not required if `--template-id` is set with a default subject.
`--text`	string	yes*	Plain text body. *Only required if no `--html` or `--template-id` is present.
`--html`	string	yes*	HTML body. *Only required if no `--text` or `--template-id` is present.
`--html-file`	string	no	Path to file containing HTML body
`--text-file`	string	no	Path to file containing plain text body
`--template-id`	string	yes*	Template ID. *Only required if no `--text` or `--html` is present.
`--tags`	string	no	Comma-separated email tags
`--send-at`	int	no	Unix timestamp for scheduled sending (max now + 72 hours)
`--track-clicks`	bool	no	Enable click tracking
`--track-opens`	bool	no	Enable open tracking
`--track-content`	bool	no	Enable content tracking

Bulk email

# Send bulk email from a JSON file
mailersend bulk-email send --file emails.json

# Check bulk email status
mailersend bulk-email status <bulk_email_id>

The JSON file should contain an array of email objects matching the email API request format:

[
  {
    "from": {"email": "sender@yourdomain.com"},
    "to": [{"email": "recipient1@example.com"}],
    "subject": "Bulk Email 1",
    "text": "Hello from bulk"
  },
  {
    "from": {"email": "sender@yourdomain.com"},
    "to": [{"email": "recipient2@example.com"}],
    "subject": "Bulk Email 2",
    "text": "Hello from bulk"
  }
]

Domains

# List domains
mailersend domain list
mailersend domain list --limit 10 --verified

# Get domain details
mailersend domain get yourdomain.com

# Add a new domain
mailersend domain add --name yourdomain.com

# Show DNS records
mailersend domain dns yourdomain.com

# Verify domain
mailersend domain verify yourdomain.com

# Update domain settings
mailersend domain update-settings yourdomain.com \
  --track-clicks --track-opens

# Delete a domain
mailersend domain delete yourdomain.com

Recipients

# List recipients
mailersend recipient list --limit 20

# List recipients for a specific domain
mailersend recipient list --domain yourdomain.com

# Get recipient details
mailersend recipient get <recipient_id>

# Delete a recipient
mailersend recipient delete <recipient_id>

Sender identities

# List identities
mailersend identity list --limit 10
mailersend identity list --domain yourdomain.com

# Create an identity
mailersend identity create \
  --domain yourdomain.com \
  --name "Support" \
  --email "support@yourdomain.com"

# Get identity (by ID or email)
mailersend identity get <id>
mailersend identity get support@yourdomain.com

# Update an identity
mailersend identity update <id> --name "Customer Support"

# Delete an identity
mailersend identity delete <id>

Templates

# List templates
mailersend template list
mailersend template list --limit 10 --domain yourdomain.com

# Get template details
mailersend template get <template_id>

# Delete a template
mailersend template delete <template_id>

Messages

# List messages
mailersend message list --limit 10

# Get message details
mailersend message get <message_id>

# List scheduled messages
mailersend message scheduled list --domain yourdomain.com

# Get scheduled message
mailersend message scheduled get <message_id>

# Cancel a scheduled message
mailersend message scheduled delete <message_id>

Activity

# List activity for a domain
mailersend activity list \
  --domain yourdomain.com \
  --date-from 2025-01-01 \
  --date-to 2025-01-31

# Filter by event type
mailersend activity list \
  --domain yourdomain.com \
  --date-from 2025-01-01 \
  --date-to 2025-01-31 \
  --event delivered,opened

# Get activity details
mailersend activity get <activity_id>

Analytics

# Analytics by date
mailersend analytics date \
  --date-from 2025-01-01 \
  --date-to 2025-01-31 \
  --event sent,delivered,opened \
  --group-by days

# Analytics by country
mailersend analytics country \
  --date-from 2025-01-01 \
  --date-to 2025-01-31

# Analytics by user agent name
mailersend analytics ua-name \
  --date-from 2025-01-01 \
  --date-to 2025-01-31

# Analytics by user agent type
mailersend analytics ua-type \
  --date-from 2025-01-01 \
  --date-to 2025-01-31

Webhooks

# List webhooks
mailersend webhook list --domain yourdomain.com

# Create a webhook
mailersend webhook create \
  --domain yourdomain.com \
  --name "My Webhook" \
  --url "https://example.com/webhook" \
  --events "activity.sent,activity.delivered"

# Get webhook details
mailersend webhook get <webhook_id>

# Update a webhook
mailersend webhook update <webhook_id> --name "Updated Webhook"

# Delete a webhook
mailersend webhook delete <webhook_id>

Suppressions

Manage blocklist, hard bounces, spam complaints, unsubscribes, and on-hold entries.

# List suppressions (works for all types)
mailersend suppression blocklist list --limit 10
mailersend suppression hard-bounces list --limit 10
mailersend suppression spam-complaints list --limit 10
mailersend suppression unsubscribes list --limit 10
mailersend suppression on-hold list --limit 10

# Filter by domain
mailersend suppression blocklist list --domain yourdomain.com

# Add to blocklist (by recipient email)
mailersend suppression blocklist add \
  --domain yourdomain.com \
  --recipients "spam@example.com"

# Add to blocklist (by pattern)
mailersend suppression blocklist add \
  --domain yourdomain.com \
  --patterns "*@spamdomain.com"

# Add hard bounce / spam complaint / unsubscribe
mailersend suppression hard-bounces add \
  --domain yourdomain.com \
  --recipients "bounce@example.com"

# Delete specific entries
mailersend suppression blocklist delete --ids id1,id2

# Delete all entries for a domain
mailersend suppression blocklist delete --all --domain yourdomain.com

Inbound routes

# List inbound routes
mailersend inbound list --domain yourdomain.com --limit 10

# Create an inbound route
mailersend inbound create \
  --domain yourdomain.com \
  --name "My Inbound Route" \
  --match-filter-type match_all \
  --inbound-domain yourdomain.com \
  --inbound-priority 0 \
  --catch-filter-type catch_all \
  --forwards "https://example.com/inbound"

# Get route details
mailersend inbound get <route_id>

# Update a route
mailersend inbound update <route_id> --name "Updated Route"

# Delete a route
mailersend inbound delete <route_id>

API tokens

# List tokens
mailersend token list --limit 10

# Get token details
mailersend token get <token_id>

# Create a token
mailersend token create \
  --name "My Token" \
  --domain yourdomain.com \
  --scopes "email_full,domains_read"

# Update token name
mailersend token update <token_id> --name "Renamed Token"

# Pause / unpause a token
mailersend token update-status <token_id> --status pause
mailersend token update-status <token_id> --status unpause

# Delete a token
mailersend token delete <token_id>

Account users

# List users
mailersend user list

# Get user details
mailersend user get <user_id>

# Update a user
mailersend user update <user_id> --role admin

# Delete a user
mailersend user delete <user_id>

# List invites
mailersend user invite list

# Create an invite
mailersend user invite create --email "newuser@example.com" --role "custom"

# Get invite details
mailersend user invite get <invite_id>

# Resend an invite
mailersend user invite resend <invite_id>

# Cancel an invite
mailersend user invite cancel <invite_id>

SMTP users

All SMTP commands require --domain.

# List SMTP users
mailersend smtp list --domain yourdomain.com

# Get SMTP user details
mailersend smtp get <smtp_user_id> --domain yourdomain.com

# Create an SMTP user
mailersend smtp create --domain yourdomain.com --name "My SMTP User"

# Update an SMTP user
mailersend smtp update <smtp_user_id> \
  --domain yourdomain.com \
  --name "Updated SMTP"

# Delete an SMTP user
mailersend smtp delete <smtp_user_id> --domain yourdomain.com

Email verification

# Verify a single email
mailersend verification verify user@example.com

# Verify asynchronously
mailersend verification verify-async user@example.com

# Check async verification status
mailersend verification status <verification_id>

# List verification lists
mailersend verification list list

# Get verification list details
mailersend verification list get <list_id>

# Create a verification list
mailersend verification list create \
  --name "My List" \
  --emails "user1@example.com,user2@example.com"

# Create from a file (one email per line)
mailersend verification list create \
  --name "My List" \
  --emails-file ./emails.txt

# Start verification
mailersend verification list verify <list_id>

# Start and wait for completion
mailersend verification list verify <list_id> --wait

# Get verification results
mailersend verification list results <list_id>

# Filter by status
mailersend verification list results <list_id> --status valid

API quota

mailersend quota

SMS

Note

SMS commands require SMS to be enabled on your MailerSend account.

Send SMS

mailersend sms send \
  --from "+1234567890" \
  --to "+0987654321" \
  --text "Hello from CLI"

SMS messages

mailersend sms message list --limit 10
mailersend sms message get <message_id>

SMS phone numbers

mailersend sms number list --limit 10
mailersend sms number get <number_id>
mailersend sms number update <number_id> --paused
mailersend sms number update <number_id> --paused=false
mailersend sms number delete <number_id>

SMS activity

mailersend sms activity list --limit 10
mailersend sms activity list \
  --sms-number-id <id> \
  --date-from 2025-01-01 \
  --date-to 2025-12-31

SMS recipients

mailersend sms recipient list --limit 10
mailersend sms recipient get <recipient_id>
mailersend sms recipient update <recipient_id> --status opt_out

SMS inbound routes

mailersend sms inbound list --limit 10
mailersend sms inbound create \
  --sms-number-id <id> \
  --name "My SMS Route" \
  --forward-url "https://example.com/sms-hook"
mailersend sms inbound get <route_id>
mailersend sms inbound update <route_id> --name "Updated SMS Route"
mailersend sms inbound delete <route_id>

SMS webhooks

mailersend sms webhook list --sms-number-id <id>
mailersend sms webhook create \
  --sms-number-id <id> \
  --name "My SMS Webhook" \
  --url "https://example.com/sms-webhook" \
  --events "sms.sent,sms.delivered"
mailersend sms webhook get <webhook_id>
mailersend sms webhook update <webhook_id> --name "Updated SMS Webhook"
mailersend sms webhook delete <webhook_id>

Interactive dashboard

Launch the TUI dashboard for a visual overview of your MailerSend account:

mailersend dashboard

The dashboard provides real-time views for domains, activity, analytics, messages, and suppressions — all navigable with keyboard shortcuts.

Domain name resolution

Any flag that accepts --domain will accept both a domain name (e.g. yourdomain.com) or a raw domain ID (e.g. q3enl6kk0z042vwr). When a domain name is provided, it is automatically resolved to the corresponding ID.

JSON output

Add --json to any command to get raw JSON output, useful for scripting and piping to tools like jq:

# Pipe to jq
mailersend domain list --json | jq '.[].name'

# Extract an ID
mailersend identity create \
  --domain yourdomain.com \
  --name "Test" \
  --email "test@yourdomain.com" \
  --json | jq -r '.data.id'

The CLI also respects the NO_COLOR environment variable to disable colored output.

Shell completion

Generate shell completions for your shell:

# Bash
source <(mailersend completion bash)

# Zsh
mailersend completion zsh > "${fpath[1]}/_mailersend"

# Fish
mailersend completion fish | source

# PowerShell
mailersend completion powershell | Out-String | Invoke-Expression

# MailerSend CLI

# Installation

# Homebrew (macOS)

# GitHub Releases

# Go install

# From source

# Nix

# Authentication

# OAuth (recommended)

# API Token

# Environment variable

# Multiple profiles

# Auth status and logout

# Global flags

# Commands

# Email

# Send email flags

# Bulk email

# Domains

# Recipients

# Sender identities

# Templates

# Messages

# Activity

# Analytics

# Webhooks

# Suppressions

# Inbound routes

# API tokens

# Account users

# SMTP users

# Email verification

# API quota

# SMS

# Send SMS

# SMS messages

# SMS phone numbers

# SMS activity

# SMS recipients

# SMS inbound routes

# SMS webhooks

# Interactive dashboard

# Domain name resolution

# JSON output

# Shell completion