npm package
Node.js CLI
A full-featured command-line client for managing email accounts, sending messages, and automating workflows. Pipe-friendly output, scriptable commands, and JSON mode for pipelines.
Quick start
# Install
npm install -g @inbox-api/cli
# Configure your API token
inbox-api configure
# List your email accounts
inbox-api accounts list
# Read your latest unread messages
inbox-api messages list --unread
# Send an email
inbox-api send --account <id> --to "bob@example.com" --subject "Hello" --text "Hi Bob!"
# Search across all accounts
inbox-api search "invoice Q3"Installation
Install globally from npm:
npm install -g @inbox-api/cli
Or run directly without installing:
npx @inbox-api/cli --help
Authentication
The CLI authenticates using API tokens (prefixed with cw_).
Three ways to provide credentials, checked in order:
# 1. CLI flags (highest priority)
inbox-api accounts list --token cw_your_token --api-url https://api.example.com
# 2. Environment variables
export INBOX_API_TOKEN=cw_your_token
export INBOX_API_URL=https://api.example.com
# 3. Config file (saved by 'configure' command)
inbox-api configure
Global Options
Available on every command:
--json Output raw JSON instead of formatted tables
--no-color Disable colored output
--debug Enable debug output
--api-url <url> Override API base URL
--token <token> Override API token
configure
Set up API connection interactively. Tests the connection before saving.
inbox-api configure
Saves credentials to ~/.inbox-api/config.json.
accounts list
List all connected email accounts with message counts.
inbox-api accounts list
┌──────────────────────┬─────────────────────┬──────────┬──────────┬────────┐
│ ID │ Email │ Provider │ Messages │ Unread │
├──────────────────────┼─────────────────────┼──────────┼──────────┼────────┤
│ a1b2c3d4-... │ me@gmail.com │ gmail │ 1,247 │ 23 │
│ e5f6g7h8-... │ work@company.com │ imap │ 3,891 │ 7 │
└──────────────────────┴─────────────────────┴──────────┴──────────┴────────┘
# JSON output for scripting
inbox-api accounts list --json
accounts get
Get details for a specific account.
inbox-api accounts get <account-id>
# Example
inbox-api accounts get a1b2c3d4-5678-90ab-cdef-1234567890ab
accounts add
Connect a new email account via IMAP/SMTP credentials.
inbox-api accounts add \
--display-name "Work Email" \
--email "me@company.com" \
--imap-host "imap.company.com" \
--imap-port 993 \
--smtp-host "smtp.company.com" \
--smtp-port 587 \
--password "app-password"
Options:
--display-name <name> Display name (required)
--email <email> Email address (required)
--imap-host <host> IMAP server hostname (required)
--imap-port <port> IMAP port (default: 993)
--smtp-host <host> SMTP server hostname (required)
--smtp-port <port> SMTP port (default: 587)
--password <password> Account password (required)
--imap-ssl Enable IMAP SSL (default: true)
--no-imap-ssl Disable IMAP SSL
--smtp-ssl Enable SMTP SSL (default: true)
--no-smtp-ssl Disable SMTP SSL
accounts update
Update an existing email account. Only pass the fields you want to change.
inbox-api accounts update <account-id> \
--display-name "New Name" \
--password "new-app-password"
accounts remove
Disconnect and remove an email account.
inbox-api accounts remove <account-id>
accounts test
Test IMAP connection credentials before adding an account.
inbox-api accounts test \
--host "imap.gmail.com" \
--port 993 \
--ssl \
--username "me@gmail.com" \
--password "app-password"
accounts providers
List supported email providers with default connection settings.
inbox-api accounts providers
accounts folders
List folders for an email account.
inbox-api accounts folders <account-id>
┌──────────────────────┬──────────┬──────────────────┬──────────┬────────┐
│ ID │ Name │ Path │ Messages │ Unread │
├──────────────────────┼──────────┼──────────────────┼──────────┼────────┤
│ f1a2b3c4-... │ INBOX │ INBOX │ 1,247 │ 23 │
│ f5d6e7f8-... │ Sent │ [Gmail]/Sent │ 892 │ 0 │
│ f9a0b1c2-... │ Drafts │ [Gmail]/Drafts │ 3 │ 0 │
└──────────────────────┴──────────┴──────────────────┴──────────┴────────┘
messages list
List messages with filtering and pagination.
inbox-api messages list
inbox-api messages list --account <id> --unread
inbox-api messages list --has-attachments --page 2 --page-size 50
Options:
--account <id> Filter by account
--read Show only read messages
--unread Show only unread messages
--has-attachments Show only messages with attachments
--start-date <date> Filter from date (ISO format)
--end-date <date> Filter to date (ISO format)
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 20)
messages read
Read a full message including headers and body.
inbox-api messages read <message-id>
From: Alice <alice@example.com>
To: me@company.com
Date: 2026-03-25 14:30
Subject: Q3 Report
──────────────────────────
Hi, please find the Q3 report attached.
Best, Alice
messages update
Update message flags (read/unread, starred/unstarred).
# Mark as read
inbox-api messages update <message-id> --read
# Mark as unread
inbox-api messages update <message-id> --unread
# Star a message
inbox-api messages update <message-id> --star
# Unstar a message
inbox-api messages update <message-id> --unstar
messages delete
Delete a message.
inbox-api messages delete <message-id>
messages move
Move a message to a different folder.
inbox-api messages move <message-id> --folder-id <folder-id>
messages archive
Archive a message.
inbox-api messages archive <message-id>
messages attachments
List attachments for a message.
inbox-api messages attachments <message-id>
send
Send a new email. Recipients support two formats:
"email@example.com" or "Name <email@example.com>"
inbox-api send \
--account <account-id> \
--to "Alice <alice@example.com>" \
--to "bob@example.com" \
--cc "carol@example.com" \
--subject "Weekly Update" \
--text "Hi team, here's the weekly update."
Options:
--account <id> Account to send from (required)
--to <address...> Recipient(s) (required, repeatable)
--cc <address...> CC recipient(s)
--bcc <address...> BCC recipient(s)
--subject <subject> Email subject (required)
--text <body> Plain text body
--html <body> HTML body
reply
Reply to an existing message.
# Reply to sender only
inbox-api reply <message-id> --text "Thanks, looks good!"
# Reply to all recipients
inbox-api reply <message-id> --text "Noted, thanks everyone." --reply-all
Options:
--text <body> Plain text reply body
--html <body> HTML reply body
--reply-all Reply to all recipients
forward
Forward a message to new recipients. All original attachments are preserved.
inbox-api forward <message-id> \
--to "bob@example.com" \
--text "FYI — see the message below."
Options:
--to <address...> Recipient(s) (required, repeatable)
--cc <address...> CC recipient(s)
--bcc <address...> BCC recipient(s)
--text <body> Additional text to prepend
search
Full-text search across all accounts or a specific account.
inbox-api search "invoice"
inbox-api search "from:alice project update" --account <id>
Options:
--account <id> Limit search to a specific account
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 20)
drafts list
List saved drafts.
inbox-api drafts list
inbox-api drafts list --account <id> --page 2
Options:
--account <id> Filter by account
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 20)
drafts get
Get a specific draft.
inbox-api drafts get <draft-id>
drafts create
Create a new draft.
inbox-api drafts create \
--account <account-id> \
--to "alice@example.com" \
--subject "Proposal Draft" \
--text "Hi Alice, here's the draft proposal..."
Options:
--account <id> Account for the draft (required)
--to <address...> Recipients
--cc <address...> CC recipients
--subject <subject> Subject line
--text <body> Plain text body
--html <body> HTML body
drafts update
Update an existing draft.
inbox-api drafts update <draft-id> \
--subject "Updated Subject" \
--text "Updated body content."
drafts send
Send a saved draft.
inbox-api drafts send <draft-id>
drafts delete
Delete a draft.
inbox-api drafts delete <draft-id>
threads list
List conversation threads.
inbox-api threads list
inbox-api threads list --account <id>
Options:
--account <id> Filter by account
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 20)
threads get
Get a full thread with all messages.
inbox-api threads get <thread-id>
webhooks list
List webhook subscriptions.
inbox-api webhooks list
webhooks get
Get webhook details and delivery statistics.
inbox-api webhooks get <webhook-id>
webhooks create
Register a new webhook. The signing secret is shown only once.
inbox-api webhooks create \
--url "https://my-app.com/webhooks/inbox" \
--events message.received message.sent \
--description "Notify on new emails" \
--payload-level Standard
Options:
--url <url> Webhook URL (required)
--events <events...> Events to subscribe to (required):
message.received New email arrived
message.sent Email was sent
message.updated Flags changed
message.deleted Message deleted
message.moved Message moved
--description <text> Description
--payload-level <level> Minimal, Standard (default), or Full
webhooks update
Update a webhook. Only pass the fields you want to change.
inbox-api webhooks update <webhook-id> --events message.received
inbox-api webhooks update <webhook-id> --inactive # disable
inbox-api webhooks update <webhook-id> --active # re-enable
Options:
--url <url> New URL
--events <events...> New event list
--description <text> New description
--payload-level <level> Minimal, Standard, or Full
--active Enable webhook
--inactive Disable webhook
webhooks delete
Delete a webhook and all delivery records.
inbox-api webhooks delete <webhook-id>
webhooks regenerate-secret
Generate a new signing secret. The old secret stops working immediately.
inbox-api webhooks regenerate-secret <webhook-id>
webhooks deliveries
List delivery history for a webhook.
inbox-api webhooks deliveries <webhook-id>
inbox-api webhooks deliveries <webhook-id> --status failed
inbox-api webhooks deliveries <webhook-id> --event-type message.received
Options:
--status <status> Filter: success, failed, pending, dead_letter
--event-type <type> Filter by event type
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 20)
webhooks retry
Retry a failed webhook delivery.
inbox-api webhooks retry <webhook-id> <delivery-id>
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | API error (4xx/5xx) |
| 2 | Authentication error (401/403) |
| 3 | Connection error (server unreachable) |