Send Email from the CLI

The mopheus email subcommand family lets you configure SMTP credentials and send email directly from the CLI, so you no longer need a separate mail / sendmail tool on your Linux servers. The SMTP password is encrypted at rest using the same tokencrypto envelope as your CLI token — it is never written to disk in plaintext.

Overview

Workspace Delegation vs. Local Profile

• Workspace Mode: When running inside a repository associated with a Mopheus workspace or passing --workspace <slug-or-id>, configuration is stored securely on the Mopheus server under workspace.settings["email_smtp"], encrypted at rest using envcipher. Sending an email delegates dispatch directly to the server API (POST /api/v1/workspaces/:slug/email/send), eliminating the need to distribute SMTP credentials to peripheral worker machines or daemons.
• Local Mode: When run outside a workspace or with --local, SMTP credentials are encrypted locally in ~/.mopheus/profiles/<name>/config.json via tokencrypto envelopes, and mail is dispatched directly from the client machine.

Configure SMTP Credentials

# Save to active workspace (server-side encrypted, requires workspace admin/manage scope)
mopheus email config \
  --workspace dev-space \
  --host smtp.example.com \
  --port 587 \
  --user alice@example.com \
  --password 'your-smtp-password' \
  --sender alice@example.com \
  --display-name "Alice Bot"

# Save to local profile with implicit TLS
mopheus email config \
  --local \
  --host smtp.example.com \
  --port 465 \
  --user alice@example.com \
  --password 'your-smtp-password' \
  --use-tls

If --password is omitted in an interactive terminal, the CLI prompts without echoing. In non-interactive mode (CI, scripts) the flag is required when setting a new password.

Re-run mopheus email config to update only the fields you pass — flags you omit keep their existing values on the server or in the local profile.

Inspect Configuration

# View workspace email configuration (shows hasPassword: true without exposing credentials)
mopheus email config get --workspace dev-space

# View local profile configuration
mopheus email config get --local

Send an Email

# Delegate dispatch to active workspace (auto-detected or via --workspace)
mopheus email send \
  --workspace dev-space \
  --to team@example.com \
  --subject "Build Succeeded" \
  --body "All unit and integration checks passed."

# Direct dispatch using local SMTP configuration
mopheus email send \
  --local \
  --to alice@example.com \
  --subject "Status report" \
  --body "All systems green."

# Body from file
mopheus email send \
  --to alice@example.com \
  --cc bob@example.com \
  --subject "FYI" \
  --body-file ./message.txt

# With attachments (streamed without Base64 expansion)
mopheus email send \
  --to team@example.com \
  --subject "Weekly report" \
  --body "See attached PDF." \
  --attachment ./report.pdf \
  --attachment ./summary.csv

The --to, --cc, --bcc, and --attachment flags are repeatable for multiple recipients / files. --body and --body-file are mutually exclusive.

Guardrails & Safety Limits

When sending through a workspace:

• Attachment limits: Maximum 20MB total payload size and 15MB per individual attachment file. Exceeding this limit returns HTTP 413 (EMAIL_ATTACHMENT_TOO_LARGE).
• Rate limiting: Enforced by a sliding-window limiter with a burst cap of 10 emails/minute and a maximum of 100 emails/hour per workspace. If the limit is exceeded, HTTP 429 (EMAIL_RATE_LIMITED) is returned with a Retry-After header indicating remaining wait time.
• Pre-flight local validation checks attachment sizes before uploading to minimize wasted bandwidth.

Encryption at Rest

• Workspace Configuration: The SMTP password is encrypted on the server using envcipher (AES-GCM-256 with the server master key) and saved in PostgreSQL under workspace.settings["email_smtp"]. Passwords are never sent across the wire in GET responses (only hasPassword: true is returned).
• Local Profile Configuration: The SMTP password is stored under emailPassword in ~/.mopheus/config.json (or ~/.mopheus/profiles/<name>/config.json) as a tokencrypto envelope. The key is derived from (machineID, userID) via Argon2id, so the on-disk value is unreadable on a different machine or under a different OS user.

See Also

• mopheus config — general CLI configuration (server_url, token, workspace-id, embedding).
• mopheus auth status — show the current authentication context.