Logo Site EngageLab Mark Colored TransparentDocument
Email
Doc Home
QuickStartInstructionsREST APISMTPUseMarketingWebHookChangelogResources
Search
Login
Instructions/Agent Email/Agent Email Cli
InstructionsAgent EmailAgent Email Cli...

EngageLab Email CLI

Last updated：about 10 hours ago

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
              
              npm install -g @engagelabemail/cli
This code block in the floating window

Check the installed version:

engagelab-email-cli -V
              
              engagelab-email-cli -V
This code block in the floating window

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
              
              npm install -g @engagelabemail/cli@latest
This code block in the floating window

Configuration

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
              
              engagelab-email-cli config set --base-url http://localhost:8087 --secret-key sk_xxx
This code block in the floating window

View the saved configuration:

engagelab-email-cli config list
              
              engagelab-email-cli config list
This code block in the floating window

Clear the saved configuration:

engagelab-email-cli config clear
              
              engagelab-email-cli config clear
This code block in the floating window

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
              
              engagelab-email-cli --base-url http://localhost:8087 --secret-key sk_xxx threads get thread-1
This code block in the floating window

Quick Start

List recent inbound messages:

engagelab-email-cli emails receiving list --mailbox-id 12 --page-size 20
              
              engagelab-email-cli emails receiving list --mailbox-id 12 --page-size 20
This code block in the floating window

Read one inbound message:

engagelab-email-cli emails receiving get <message-uid>
              
              engagelab-email-cli emails receiving get <message-uid>
This code block in the floating window

View the full thread around a message:

engagelab-email-cli threads messages <thread-id> --include-content --limit 10
              
              engagelab-email-cli threads messages <thread-id> --include-content --limit 10
This code block in the floating window

Reply to an inbound message:

engagelab-email-cli emails receiving reply <message-uid> --subject "Re: Hello" --text "Thanks, we received your message."
              
              engagelab-email-cli emails receiving reply <message-uid> --subject "Re: Hello" --text "Thanks, we received your message."
This code block in the floating window

Send a new email:

engagelab-email-cli emails send \ --mailbox-id 1001 \ --to alice@example.com \ --subject "Hello" \ --text "Hello from EngageLab Email CLI."
              
              engagelab-email-cli emails send \
  --mailbox-id 1001 \
  --to alice@example.com \
  --subject "Hello" \
  --text "Hello from EngageLab Email CLI."
This code block in the floating window

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

engagelab-email-cli emails receiving list --mailbox-id 12 --page-size 20 --json
              
              engagelab-email-cli emails receiving list --mailbox-id 12 --page-size 20 --json
This code block in the floating window

Commands

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
              
              engagelab-email-cli config set --base-url http://localhost:8087 --secret-key sk_xxx
This code block in the floating window

config list

Show saved configuration.

Example:

engagelab-email-cli config list
              
              engagelab-email-cli config list
This code block in the floating window

config clear

Clear saved local configuration, including baseUrl and secretKey.

Example:

engagelab-email-cli config clear
              
              engagelab-email-cli config clear
This code block in the floating window

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
              
              engagelab-email-cli mailbox list --page-size 20
This code block in the floating window

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
              
              engagelab-email-cli threads list --subject refund --page-no 1 --page-size 20
This code block in the floating window

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
              
              engagelab-email-cli threads get b0d9d6a1-1d17-4df8-8245-c807d7e8cb50
This code block in the floating window

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
              
              engagelab-email-cli threads messages b0d9d6a1-1d17-4df8-8245-c807d7e8cb50 --include-content --json
This code block in the floating window

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
              
              engagelab-email-cli emails receiving list --keyword refund --page-size 20
This code block in the floating window

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
              
              engagelab-email-cli emails receiving get 7e2b2de6-14c5-4ef1-a1e2-f4337e4606e2 --json
This code block in the floating window

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
              
              engagelab-email-cli emails receiving listen --limit 10 --interval 5 --json
This code block in the floating window

Continue from a known cursor:

engagelab-email-cli emails receiving listen --after 1500 --limit 10 --interval 5 --json
              
              engagelab-email-cli emails receiving listen --after 1500 --limit 10 --interval 5 --json
This code block in the floating window

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
              
              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
This code block in the floating window

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 alice@example.com \ --to bob@example.com \ --subject "Refund update" \ --text "Your refund has been processed." \ --attachment ./receipt.pdf \ --disposition attachment
              
              engagelab-email-cli emails send \
  --mailbox-id 1001 \
  --to alice@example.com \
  --to bob@example.com \
  --subject "Refund update" \
  --text "Your refund has been processed." \
  --attachment ./receipt.pdf \
  --disposition attachment
This code block in the floating window

Send HTML with an inline image attachment:

engagelab-email-cli emails send --mailbox-id 1001 --to alice@example.com --subject "Inline image" --html "<p>Logo <img src=cid:image_1000></p>" --attachment ./logo.png --disposition inline --content-id image_1000
              
              engagelab-email-cli emails send --mailbox-id 1001 --to alice@example.com --subject "Inline image" --html "<p>Logo <img src=cid:image_1000></p>" --attachment ./logo.png --disposition inline --content-id image_1000
This code block in the floating window

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 alice@example.com --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"
              
              engagelab-email-cli emails send --mailbox-id 1001 --to alice@example.com --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"
This code block in the floating window

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

engagelab-email-cli emails send --mailbox-id 1001 --to alice@example.com --subject "Inline image" --html "<p>Logo <img src=cid:image_1000></p>" --attachment ./logo.png --disposition inline --content-id image_1000
              
              engagelab-email-cli emails send --mailbox-id 1001 --to alice@example.com --subject "Inline image" --html "<p>Logo <img src=cid:image_1000></p>" --attachment ./logo.png --disposition inline --content-id image_1000
This code block in the floating window

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 alice@example.com \ --subject "Monthly report" \ --html-file ./report.html
              
              engagelab-email-cli emails send \
  --mailbox-id 1001 \
  --to alice@example.com \
  --subject "Monthly report" \
  --html-file ./report.html
This code block in the floating window

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
              
              engagelab-email-cli emails receiving get <message-uid> --json
This code block in the floating window

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

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" } }
              
              {
  "error": {
    "code": "auth_error",
    "errorCode": 100101,
    "message": "unauthorized"
  }
}
This code block in the floating window

Exit codes:

Exit Code Meaning
1 Parameter error or missing config
2 Authentication failure
3 Resource not found
4 Conflict or in-progress state
5 Server error or network error
Icon Solid Transparent White Qiyu
Contact Sales