Fluxomail CLI

Install the CLI (via the SDK package):

npm i -g @fluxomail/sdk

Environment

FLUXOMAIL_API_KEY: server API key for your organization
Optional: FLUXOMAIL_BASE_URL (defaults to https://api.fluxomail.com/api/v1)

Usage

# One‑shot (recommended for CI)
npx -y @fluxomail/sdk fluxomail --help
pnpm dlx @fluxomail/sdk fluxomail --help
bunx @fluxomail/sdk fluxomail --help

# Global
fluxomail send \
  --api-key $FLUXOMAIL_API_KEY \
  --to [email protected] \
  --subject "Hello" \
  --text "Hi there" \
  --idempotency tx-123

# Send with CC/BCC and attachment
fluxomail send \
  --api-key $FLUXOMAIL_API_KEY \
  --to [email protected] \
  --subject "Hello" \
  --text "Hi there" \
  --cc [email protected],[email protected] \
  --bcc [email protected] \
  --attach ./report.pdf:application/pdf:Q3-Report.pdf

fluxomail events list \
  --api-key $FLUXOMAIL_API_KEY \
  --types email.delivered,email.opened \
  --limit 50

fluxomail events tail \
  --api-key $FLUXOMAIL_API_KEY \
  --types email.*

# Resumable backfill with checkpoint
fluxomail events backfill \
  --api-key $FLUXOMAIL_API_KEY \
  --types email.* \
  --limit 100 \
  --checkpoint-file .fluxomail.ckpt

# Get a send's timeline
fluxomail timelines get \
  --api-key $FLUXOMAIL_API_KEY \
  --send-id send_abc123 \
  --limit 100

# Quick auth check
fluxomail whoami --api-key $FLUXOMAIL_API_KEY

# Scaffolds (creates directories as needed)
fluxomail init next ./my-next-app      # writes pages/api/fluxomail/token.ts
fluxomail init next-app ./my-next-app  # writes app/api/fluxomail/token/route.ts
fluxomail init worker ./my-worker      # writes worker.js

Options

Global: --api-key, --base, --version
Send: --to, --from, --subject, --text, --html, --idempotency, --cc, --bcc, --attach
Events list: --types, --limit, --since, --cursor
Events tail: --types, --since
Events backfill: --types, --limit, --since, --checkpoint-file, --max-pages
Timelines get: --send-id, --limit, --cursor

Additional options

Global: --token-cmd <cmd> for short‑lived tokens, --quiet to suppress stdout
Config file: .fluxomailrc in project or home directory, or --config <path>
- Keys: apiKey, base, version, tokenCmd
Send: --header k:v (repeatable) to add custom message headers

Formatting & IO

--format: control output
- events list: json|jsonl|pretty (default pretty)
- events tail/backfill: json|jsonl (default jsonl)
- timelines get: json|pretty (default pretty)
--output <file>: write output to a file (tail/backfill append lines)
--quiet: suppress stdout (use with --output for silent runs)

Dynamic tokens

--token-cmd <cmd>: run a shell command that prints a short‑lived token to stdout. The CLI uses it for initial auth and automatic refresh.

The CLI uses the same robust defaults as the SDK: API date versioning, request IDs, and sensible timeouts. .fluxomailrc example

{
  "apiKey": "YOUR_API_KEY",
  "base": "https://api.fluxomail.com/api/v1",
  "version": "2025-09-01",
  "tokenCmd": "printf token-123"
}

API documentation

Endpoints