@engagelabemail/cli

EngageLab Email CLI

Official EngageLab Email developer tooling.

EngageLab Email CLI helps agents and developers work with inbound and outbound email from the command line.

Use it to:

• List available mailboxes
• List and inspect email threads
• Read inbound messages
• Poll for new inbound messages
• Reply to inbound messages
• Send new emails

Install

npm install -g @engagelabemail/cli

Check the installed version:

engagelab-email-cli -V

When you run a command that connects to EngageLab Email, the CLI checks whether a newer CLI version is available. If an update is required, it stops and shows the update command:

npm install -g @engagelabemail/cli@latest

Configuration

Sign In Through the Browser

Run the login command to sign in on the EngageLab website, choose an organization, and authorize the CLI:

engagelab-email-cli login

The CLI opens your browser and waits for authorization for up to 15 minutes. After you authorize, it selects your data center automatically — the last-used one, the first available one, or a newly created default Singapore one — generates a Secret Key for it, and saves the key in the local CLI config. The API base URL is not returned by the login endpoints: it is derived from the key's region prefix and saved at the same time.

If no authorization arrives within 15 minutes, the CLI exits and the sign-in page in your browser is no longer valid. Close that page and run login again.

If the browser cannot be opened automatically, copy the displayed URL into a browser. You can request this behavior directly with --no-browser:

engagelab-email-cli login --no-browser

Use --json for a machine-readable final result. Progress events are written to standard error so that standard output contains only the final result. The data center is selected automatically; login never prompts interactively.

Manage Saved Configuration

Use the config command group to save, inspect, or clear local credentials.

Save your service address and Secret Key locally:

engagelab-email-cli config set --base-url http://localhost:8087 --secret-key sk_xxx

View the saved configuration:

engagelab-email-cli config list

Clear the saved configuration:

engagelab-email-cli config clear

config list masks the Secret Key.

Use Global Credentials With Any Business Command

You do not have to save credentials first. You can pass --base-url and --secret-key directly before any business command such as threads ... or emails .... These command-line credentials apply only to the current command and do not overwrite saved config.

Example:

engagelab-email-cli --base-url http://localhost:8087 --secret-key sk_xxx threads get thread-1

Quick Start

List recent inbound messages:

engagelab-email-cli emails receiving list --mailbox-id 12 --page-size 20

Read one inbound message:

engagelab-email-cli emails receiving get <message-uid>

View the full thread around a message:

engagelab-email-cli threads messages <thread-id> --include-content --limit 10

Reply to an inbound message:

engagelab-email-cli emails receiving reply <message-uid> --subject "Re: Hello" --text "Thanks, we received your message."

Send a new email:

engagelab-email-cli emails send \
  --mailbox-id 1001 \
  --to [e-mail] \
  --subject "Hello" \
  --text "Hello from EngageLab Email CLI."

For scripts or agents, add --json to get machine-readable output:

engagelab-email-cli emails receiving list --mailbox-id 12 --page-size 20 --json

Commands

login

Sign in through the EngageLab website and save the generated Secret Key.

Option	Description
--no-browser	Print the sign-in URL without opening a browser.
--json	Write the final result as JSON.

config set

Save local configuration.

Option	Description
--base-url <url>	Service address. Defaults to ENGAGELAB_EMAIL_BASE_URL when set.
--secret-key <key>	Secret Key. Defaults to ENGAGELAB_EMAIL_SECRET_KEY when set.

Example:

engagelab-email-cli config set --base-url http://localhost:8087 --secret-key sk_xxx

config list

Show saved configuration.

Example:

engagelab-email-cli config list

config clear

Clear saved local configuration, including baseUrl and secretKey.

Example:

engagelab-email-cli config clear

mailbox list

List available mailboxes.

Option	Description
--mailbox <address>	Filter by mailbox address.
--page-no <number>	Page number.
--page-size <number>	Page size.
--json	Output raw JSON.

Example:

engagelab-email-cli mailbox list --page-size 20

threads list

List email threads.

Option	Description
--mailbox-id <id>	Filter by mailbox ID.
--subject <text>	Search by normalized subject.
--participant <email>	Search by participant.
--start-time <timestamp>	Latest message start timestamp in milliseconds.
--end-time <timestamp>	Latest message end timestamp in milliseconds.
--page-no <number>	Page number.
--page-size <number>	Page size.
--json	Output raw JSON.

Example:

engagelab-email-cli threads list --subject refund --page-no 1 --page-size 20

threads get <thread-id>

Show one thread.

Argument/Option	Description
<thread-id>	Thread ID.
--json	Output raw JSON.

Example:

engagelab-email-cli threads get b0d9d6a1-1d17-4df8-8245-c807d7e8cb50

threads messages <thread-id>

List messages in a thread.

Argument/Option	Description
<thread-id>	Thread ID.
--limit <number>	Message limit.
--include-content	Include text/html/headers/attachments.
--json	Output raw JSON.

Example:

engagelab-email-cli threads messages b0d9d6a1-1d17-4df8-8245-c807d7e8cb50 --include-content --json

emails receiving list

List inbound messages.

Option	Description
--mailbox-id <id>	Filter by mailbox ID.
--keyword <text>	Search keyword.
--page-no <number>	Page number.
--page-size <number>	Page size.
--json	Output raw JSON.

Example:

engagelab-email-cli emails receiving list --keyword refund --page-size 20

emails receiving get <message-uid>

Show one inbound message.

Argument/Option	Description
<message-uid>	Message UID.
--json	Output raw JSON.

Example:

engagelab-email-cli emails receiving get 7e2b2de6-14c5-4ef1-a1e2-f4337e4606e2 --json

emails receiving listen

Poll for new inbound messages. This command keeps running until you stop it with Ctrl+C.

Option	Description
--after <id>	Cursor ID from the previous result.
--limit <number>	Message limit.
--interval <seconds>	Polling interval in seconds (minimum 2).
--json	Output one JSON message per line.

Example:

engagelab-email-cli emails receiving listen --limit 10 --interval 5 --json

Continue from a known cursor:

engagelab-email-cli emails receiving listen --after 1500 --limit 10 --interval 5 --json

emails receiving reply <message-uid>

Reply to an inbound message.

Argument/Option	Description
<message-uid>	Message UID to reply to.
--subject <text>	Reply subject.
--text <text>	Plain text body.
--html <html>	HTML body.
--text-file <path>	Read plain text body from file.
--html-file <path>	Read HTML body from file.
--cc <email>	CC address. Can be repeated.
--bcc <email>	BCC address. Can be repeated.
--reply-to <email>	Reply-To address. Can be repeated.
--preview-text <text>	Email preview text.
--attachment <path>	Attach local file. Can be repeated. Requires --disposition. Up to 10 files, 10MB total after base64 encoding (about 7.5MB raw files).
--disposition <value>	Attachment disposition: attachment or inline. Required when using --attachment. Can be repeated or provided once for all attachments.
--content-id <id>	Content-ID for inline image attachments. Required when --disposition inline is used with an image attachment.
--sandbox	Send in sandbox mode.
--json	Output raw JSON.

Example:

engagelab-email-cli emails receiving reply 7e2b2de6-14c5-4ef1-a1e2-f4337e4606e2 \
  --subject "Re: Refund update" \
  --text "Thanks, we received your message." \
  --attachment ./receipt.pdf \
  --disposition attachment

emails send

Send a new email.

Option	Description
--mailbox-id <id>	Mailbox ID.
--from <email>	Sender email address.
--to <email>	Recipient email address. Can be repeated.
--subject <text>	Email subject.
--text <text>	Plain text body.
--html <html>	HTML body.
--text-file <path>	Read plain text body from file.
--html-file <path>	Read HTML body from file.
--cc <email>	CC address. Can be repeated.
--bcc <email>	BCC address. Can be repeated.
--reply-to <email>	Reply-To address. Can be repeated.
--preview-text <text>	Email preview text.
--attachment <path>	Attach local file. Can be repeated. Requires --disposition. Up to 10 files, 10MB total after base64 encoding (about 7.5MB raw files).
--disposition <value>	Attachment disposition: attachment or inline. Required when using --attachment. Can be repeated or provided once for all attachments.
--content-id <id>	Content-ID for inline image attachments. Required when --disposition inline is used with an image attachment.
--sandbox	Send in sandbox mode.
--json	Output raw JSON.

Example:

engagelab-email-cli emails send \
  --mailbox-id 1001 \
  --to [e-mail] \
  --to [e-mail] \
  --subject "Refund update" \
  --text "Your refund has been processed." \
  --attachment ./receipt.pdf \
  --disposition attachment

Send HTML with an inline image attachment:

engagelab-email-cli emails send --mailbox-id 1001 --to [e-mail] --subject "Inline image" --html "<p>Logo <img src=cid:image_1000></p>" --attachment ./logo.png --disposition inline --content-id image_1000

Attachment metadata can be passed in two compatible ways. The recommended form binds metadata to each file path, which avoids ambiguity with multiple attachments:

engagelab-email-cli emails send --mailbox-id 1001 --to [e-mail] --subject "Mixed attachments" --html "<p>Logo <img src=cid:image_1000></p>" --attachment "./receipt.pdf;disposition=attachment" --attachment "./logo.png;disposition=inline;content_id=image_1000"

The legacy split-option form is also supported for compatibility:

engagelab-email-cli emails send --mailbox-id 1001 --to [e-mail] --subject "Inline image" --html "<p>Logo <img src=cid:image_1000></p>" --attachment ./logo.png --disposition inline --content-id image_1000

Do not mix inline attachment metadata (path;disposition=...) with --disposition or --content-id in the same command. Send HTML content from a file:

engagelab-email-cli emails send \
  --mailbox-id 1001 \
  --to [e-mail] \
  --subject "Monthly report" \
  --html-file ./report.html

Output

By default, the CLI prints readable tables or summaries and shows a short loading message while requests are running.

Use --json when another tool or script needs to parse the result.

engagelab-email-cli emails receiving get <message-uid> --json

emails receiving listen --json prints one message JSON object per line.

Anonymous Usage Metrics

API commands add an anonymous installation ID and CLI version to request headers so EngageLab can measure distinct CLI installations. The ID is stored in the local CLI config under telemetry; no Secret Key, email content, or recipients are collected. The first successful API request also carries X-EngageLab-SDK-Init: 1.

To disable these headers:

ENGAGELAB_EMAIL_TELEMETRY_DISABLED=1 engagelab-email-cli mailbox list

Errors

Human-readable errors include the business error code when the API returns one, for example [100101] unauthorized.

--json errors use this shape:

{
  "error": {
    "code": "auth_error",
    "errorCode": 100101,
    "message": "unauthorized"
  }
}

Exit codes:

Exit Code	Meaning
1	Parameter error, missing config, or login timeout
2	Authentication failure
3	Resource not found
4	Conflict or in-progress state
5	Server error or network error