DEV Community

Elastic Email
Elastic Email

Posted on Originally published at elasticemail.com

Official Elastic Email CLI

#cli #emailapi #showdev #opensource

Terminal window running npm install -g elastic-email-cli, then auth set-key, then an emails send command, over a photo of a developer at a laptop with paper plane icons trailing from the terminal.

This is our first post here, so a quick introduction.
We build Elastic Email, a platform and API for transactional email and marketing campaigns. This week we published a CLI for it, MIT-licensed and developed in the open, and one design decision inside it is the reason we are writing this instead of a plain release note.

A CLI for an API like ours gets used in two places that want opposite things.
A person exploring an account wants color, structure, arrow keys, and a wizard that stops them from sending a campaign to the wrong list. A CI job wants parseable output, and an exit code it can branch on. Serving both usually means two tools, or one tool with a --quiet flag that everyone forgets to pass.
So we put the decision in the CLI instead. It checks for a TTY and adapts.

On a terminal, a bare elastic-email opens an interactive TUI: arrow keys through templates, lists, contacts, segments, delivery events, and sender domains, plus a guided send wizard with verified-domain hints on the sender field. The same bare command, when run in a pipe or in a CI runner, prints plain help, because a script that receives a bare invocation needs it.

The rest follows from there. Every command accepts --json. Piped output drops the banner and the decorations. Exit codes are stable and specific, so a job can distinguish a missing API key from a malformed address and respond differently.

Getting started

npm install -g elastic-email-cli
elastic-email auth set-key
elastic-email emails send --to you@example.com --subject "Hello" --text "It works!" --from me@yourdomain.com
Enter fullscreen mode Exit fullscreen mode

You need Node.js 20 or newer and an Elastic Email API key.

About the API key

The key resolves in a fixed order: the --api-key flag, then the ELASTIC_EMAIL_API_KEY environment variable, then a local config file. auth set-key writes that file in plaintext at ~/.elastic-email-cli/config.json with 0600 permission. This is convenient on a personal machine, and the environment variable is the better answer on shared machines and CI runners, which is why it takes precedence over the file. In logs and error output, the key appears only in masked form.

Beyond sending, the Elastic Email CLI covers templates, contacts, lists, segments, suppressions, delivery events, address verification, sender domain (SPF, DKIM, MX, and DMARC), and account statistics. The full command reference lives in the repository.

Repo: https://github.com/ElasticEmail/elasticemail-cli

It’s MIT-licensed. If a command you expected is missing, feel free to reach out to us with feedback.

Top comments (0)