The whole email operation, in your terminal.
npm install -g lumail gives you every endpoint the app has, sending included. Add the lumail skill and any agent with a terminal — Claude Code, Codex, Cursor — knows every command, every flag and every output format. You sign in through your browser, and no token ever lands in a dotfile.
Full API, sending included
One browser sign-in
JSON and CSV on every command
Read lumail.io/cli/install and set up the Lumail CLI for me.Your agent reads the install guide, installs the CLI, walks you through the browser sign-in, drops the lumail skill into its skills directory, and verifies with a real read command.
Ask in English, watch it run in your shell.
The skill teaches your agent the whole command surface, so it picks the right command and flags instead of guessing at an API. Every call is a line in your terminal you can read, cancel or re-run yourself.
Add [email protected] to my newsletter with the vip tag.
Export every subscriber tagged trial-2026 as CSV.
Show me all draft campaigns, then send the Launch week one.
Send an order confirmation to this address from [email protected].
Sign in once. Nothing to paste.
lumail auth login opens your browser, runs the OAuth flow, and writes a self-refreshing credential to ~/.config/lumail/oauth.json with mode 0600. API tokens still exist for CI, but they are no longer the default path.
- 01
Install and run auth login
One command opens lumail.io in your browser and waits on a loopback callback. There is no client ID to configure and no secret to export.
- 02
You pick the organization
Sign in to Lumail and choose exactly which organization the CLI may reach. Only owners and admins can authorize one.
- 03
The credential refreshes itself
The token lands in ~/.config/lumail/oauth.json and renews on its own. Nothing to rotate, nothing to remember.
For CI and named service accounts, lumail auth set lum_... still works with a classic API token. Prefer auth login everywhere a human is present — it is the only path with no long-lived secret on disk.
Everything the app can do.
Unlike the OAuth plugin, which deliberately hides anything that reaches an inbox, the CLI is the full API. That is the point — and the reason the safety rule lives in the skill instead of in the transport.
Available from the CLI
Create, update, delete, unsubscribe and tag subscribers
List, create, update, delete and send campaigns
Send transactional email with Markdown, HTML or Tiptap content
Verify an address before you send to it
Create tags and custom events, and read a subscriber's timeline
Run any V2 tool and print the result as text, JSON or CSV
Still out of reach
Another organization in your account
Billing and organization settings
Sending from a domain you have not verified
Exceeding your plan's rate and quota limits
The skill's safety contract is explicit: an agent must never run a send, publish, unsubscribe or delete without your confirmation in that conversation, and must quote the exact command back before anything irreversible. Because every call is a terminal line, you see it happen.
One install, one sign-in, one skill.
The CLI is published on npm as lumail — the same package as the TypeScript SDK. The skill is a single Markdown file your agent reads at the start of every relevant task.
Let your agent do it
Paste this into Claude Code, Codex, or any agent with a terminal. It reads the install guide at lumail.io/cli/install, installs the CLI, runs the browser login, installs the skill, and verifies with a real read command.
Read lumail.io/cli/install and set up the Lumail CLI for me.Or run it yourself
Four commands. Use pnpm or bun in place of npm if that is what you already have.
- 01
Install the CLI
Global install puts lumail on your PATH. If you would rather not install globally, prefix every command below with npx.
npm install -g lumail - 02
Sign in through your browser
A Lumail tab opens. Sign in, pick the organization the CLI may reach, and approve the access. The credential is written to ~/.config/lumail/oauth.json.
lumail auth login - 03
Install the lumail skill
The skill teaches your agent every command, every output format and the safety rules. Claude Code reads ~/.claude/skills; Codex and other agents read ~/.agents/skills. If you already have the Lumail plugin installed, the skill ships with it — skip this step.
pnpm dlx skills add Melvynx/lumail-opensource -g - 04
Verify
auth test must succeed and the campaigns call must return JSON. An empty list is a valid answer on a new organization.
lumail auth test lumail campaigns list --json
Package details
- Package
lumail- Registry
- npm
- Auth
- OAuth 2.1 + PKCE, browser flow
- Credential
~/.config/lumail/oauth.json- Formats
text, --json, --format csv- Skill
lumail
Want tools instead of commands?
The Claude Code and Codex plugins expose Lumail as MCP tools the agent calls directly — narrower on purpose, since they cannot send. They install alongside the CLI and work side by side.
claude plugin install lumail@lumailFull access, visible access.
The CLI can do everything, which makes the guardrails a matter of what you can see and revoke rather than what the transport hides.
One organization per sign-in
You choose the organization during auth login, and the credential carries it. Other organizations in your account stay unreachable until you sign in again.
Every action is a command you can read
An agent driving the CLI cannot do anything off-screen. The command, its flags and its output all land in your terminal before anything else happens.
Revoke without touching your machine
lumail auth remove clears the local credential, and revoking the app from Lumail settings kills access on the very next request.
Frequently asked questions
What is the Lumail CLI?
A command-line client for the full Lumail API, published on npm as lumail. It covers subscribers, tags, campaigns, transactional email, events and the V2 tools, and prints results as text, JSON or CSV.
What does the lumail skill add?
The skill is a Markdown file that teaches an agent every CLI command, its flags, its output formats and the safety rules. Without it an agent has to guess; with it, 'add [email protected] with the vip tag' becomes the right command on the first try.
Do I need an API token?
No. lumail auth login runs a browser OAuth flow and writes a self-refreshing credential to ~/.config/lumail/oauth.json. API tokens via lumail auth set still exist for CI and named service accounts.
Can the CLI send a campaign?
Yes. lumail campaigns send and lumail emails send both work — this is the difference from the OAuth plugin, which does not register those tools at all. The skill requires an agent to confirm with you before running anything irreversible.
Which agents does it work with?
Any agent that can run a shell command. The skill installs into ~/.claude/skills for Claude Code and ~/.agents/skills for Codex and other agents that read a shared skills directory.
Do I need a paid plan?
No. The free plan includes API and CLI access, with 3,000 emails a month. Rate limits are counted per organization and rise with your plan.
How do I remove it?
lumail auth remove clears the credential, npm uninstall -g lumail removes the CLI, and deleting ~/.claude/skills/lumail or ~/.agents/skills/lumail removes the skill. Revoking the app from Lumail settings cuts access immediately.
Stop clicking through a dashboard.
Install the CLI, sign in once, add the skill, and your agent runs your email operation from the same terminal as everything else.
Read lumail.io/cli/install and set up the Lumail CLI for me.