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.inbox-api.com
# 2. Environment variables
export INBOX_API_TOKEN=cw_your_token
export INBOX_API_URL=https://api.inbox-api.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 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 --starred --sort subject
inbox-api messages list -q "invoice" --has-attachments
Options:
--account <id> Filter by account
--folder <id> Filter by folder
--read Show only read messages
--unread Show only unread messages
--starred Show only starred messages
--unstarred Show only unstarred messages
--has-attachments Show only messages with attachments
--start-date <date> Filter from date (ISO format)
--end-date <date> Filter to date (ISO format)
--sort <order> Sort: date, date_asc, subject, from
-q, --query <text> Full-text search query
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 10)
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>
messages download
Download an attachment from a message.
inbox-api messages download <message-id> <attachment-id>
inbox-api messages download <message-id> <attachment-id> --output "report.pdf"
Options:
--output <path> Output file path (defaults to attachment 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>
inbox-api search "quarterly report" --has-attachments --sort relevance
Options:
--account <id> Limit search to a specific account
--read Show only read messages
--unread Show only unread messages
--starred Show only starred messages
--has-attachments Show only messages with attachments
--start-date <date> Filter from date (ISO format)
--end-date <date> Filter to date (ISO format)
--sort <order> Sort: relevance, date, date_asc, subject, from
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 10)
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: 10)
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> --unread-only
inbox-api threads list --start-date 2026-01-01 --sort date_asc
Options:
--account <id> Filter by account
--start-date <date> Filter from date (ISO format)
--end-date <date> Filter to date (ISO format)
--unread-only Show only threads with unread messages
--sort <order> Sort order
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 10)
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 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: 10)
webhooks retry
Retry a failed webhook delivery.
inbox-api webhooks retry <webhook-id> <delivery-id>
webhooks delivery
Get a single webhook delivery by ID.
inbox-api webhooks delivery <webhook-id> <delivery-id>
batch mark-read
Mark multiple messages as read or unread in a single operation.
inbox-api batch mark-read --message-ids <id1> <id2> <id3>
inbox-api batch mark-read --message-ids <id1> <id2> --unread
Options:
--message-ids <ids...> Message IDs (space-separated, required)
--unread Mark as unread instead of read
batch archive
Archive multiple messages in a single operation.
inbox-api batch archive --message-ids <id1> <id2> <id3>
Options:
--message-ids <ids...> Message IDs (space-separated, required)
batch move
Move multiple messages to a folder in a single operation.
inbox-api batch move --message-ids <id1> <id2> --folder-id <folder-id>
Options:
--message-ids <ids...> Message IDs (space-separated, required)
--folder-id <id> Target folder ID (required)
contacts list
List contacts extracted from email headers, ranked by frequency.
inbox-api contacts list
inbox-api contacts list --account <id> --search "alice"
Options:
--account <id> Filter by account
--search <query> Search contacts by name or email
--since <date> Only contacts since date (ISO format)
--sort <order> Sort order
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 25)
digest
Get an email digest summary across all accounts or a specific account.
inbox-api digest
inbox-api digest --since 7d --account <id>
Options:
--since <duration> Time window, e.g. 24h, 7d (default: 24h)
--account <id> Filter by account
--max-per-account <n> Maximum messages per account (default: 25)
health
Check IMAP health status for an email account. Returns connection state, sync status, and error details.
inbox-api health <account-id>
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | API error (4xx/5xx) |
| 2 | Authentication error (401/403) |
| 3 | Connection error (server unreachable) |