@dollardeploy/brevo-cli

A zero-dependency Brevo API client and a brevo-cli for managing contacts and transactional email templates.

This package contains two things:

1. api.js — a small Brevo API v3 client built on the native Node.js fetch. No axios, no SDK — nothing to install.
2. cli.js (brevo-cli) — a command line tool for managing Brevo contacts (list, add, remove, subscribe, unsubscribe) and transactional templates (list, show, add, edit).

Requirements

• Node.js >= 22 (for the global fetch API).

Configuration

| Setting | Flag | Environment variable | Default | | -------- | ------- | -------------------- | -------------------------- | | API key | --key | BREVO_API_KEY | — (required) | | Base URL | --url | BREVO_API_URL | https://api.brevo.com/v3 |

Create an API key in Brevo under Settings → SMTP & API → API Keys (it starts with xkeysib-).

export BREVO_API_KEY="xkeysib-..."

CLI Usage

brevo-cli <group> <command> [arguments] [options]

Contacts

| Command | Description | | ------------------------------ | ---------------------------------------------- | | contacts list | List contacts (auto-paginates, see below) | | contacts add <email> | Create a contact | | contacts remove <email> | Delete a contact permanently | | contacts subscribe <email> | Re-subscribe — sets emailBlacklisted = false | | contacts unsubscribe <email> | Unsubscribe — sets emailBlacklisted = true |

subscribe/unsubscribe toggle the contact's email subscription status (emailBlacklisted), i.e. whether they receive marketing emails.

Contact options: --attrs "FIRSTNAME=Jane,LASTNAME=Doe", --list <id1,id2>, --no-subscribe, --update (update if the contact already exists) for add; --limit, --offset for list.

brevo-cli contacts list --limit all
brevo-cli contacts add [email protected] --attrs "FIRSTNAME=Jane" --list 3
brevo-cli contacts unsubscribe [email protected]
brevo-cli contacts subscribe [email protected]
brevo-cli contacts remove [email protected]

Templates (transactional / automated emails)

These are the transactional email templates that power automated emails such as welcome and subscription messages.

| Command | Description | | ---------------------------- | ---------------------------------------------------- | | templates list | List templates (--active / --inactive to filter) | | templates show <id> | Show a template's details, or its HTML with --html | | templates add --name "..." | Create a template | | templates edit <id> | Update a template |

Template options:

| Option | Description | | ------------------------- | ---------------------------------------------------- | | --name <name> | Template name | | --subject <subject> | Email subject line | | --html <file\|text> | (add/edit) HTML body from a file path or inline text | | --html [file] | (show) Print the HTML body, or write it to <file> | | --sender-email <email> | Sender email address | | --sender-name <name> | Sender display name | | --sender-id <id> | Use an existing sender by ID (instead of email/name) | | --active / --inactive | Activate or deactivate the template |

brevo-cli templates list --active
brevo-cli templates show 3
brevo-cli templates show 3 --html              # print the HTML body
brevo-cli templates show 3 --html welcome.html # save the HTML body to a file
brevo-cli templates add --name "Welcome" --subject "Hi {{contact.FIRSTNAME}}" \
  --html ./welcome.html --sender-email [email protected] --sender-name "Team"
brevo-cli templates edit 3 --subject "Welcome aboard" --html ./welcome.html --active

Auto-pagination (list)

Both contacts list and templates list accept --limit <n|all> and --offset. Brevo returns up to 1000 records per request; when --limit is larger (or all), the CLI transparently fetches successive pages and trims to the requested count.

Output

Every command accepts --json to print the raw API response instead of a table — handy for piping into jq or feeding other tools.

Programmatic Usage

const BrevoAPI = require("./api");

const api = BrevoAPI({ apiKey: process.env.BREVO_API_KEY });

const { contacts, count } = await api.contacts.list({ limit: 10 });
console.log(count, contacts);

await api.contacts.update("[email protected]", { emailBlacklisted: true });

Exposed resources: account.get(), contacts.{list,get,create,update,remove}, templates.{list,get,create,update}, plus a low-level request(method, path, { query, body }) for any other Brevo endpoint.

How it works

• Auth — every request sends the api-key header, as Brevo requires.
• Transport — the native fetch; JSON in, JSON out.
• Errors — non-2xx responses throw an Error carrying Brevo's message, plus status and code for programmatic handling.