@inbox-api/cli

Command-line client for the Inbox API. Manage email accounts, read and send messages, search, handle drafts, and browse threads from your terminal.

Installation

npm install -g @inbox-api/cli

Quick Start

# Configure your credentials (interactive)
inbox-api configure

# Or use environment variables
export INBOX_API_TOKEN=cw_your_token
export INBOX_API_URL=https://api.inbox-api.com

# List email accounts
inbox-api accounts list

# Read recent messages
inbox-api messages list

# Search across all accounts
inbox-api search "invoice from:[email protected]"

# Send an email
inbox-api send --account <id> --to "[email protected]" --subject "Hello" --text "Hi there"

Configuration

The CLI resolves authentication in this order:

1. CLI flags: --token and --api-url
2. Environment variables: INBOX_API_TOKEN and INBOX_API_URL
3. Config file: ~/.inbox-api/config.json (created by inbox-api configure)

Interactive Setup

inbox-api configure

Prompts for API URL and token, validates the connection with a health check, and saves to ~/.inbox-api/config.json.

Global Options

| Option | Description | |--------|-------------| | --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 |

Commands

accounts — Email Account Management

inbox-api accounts list                              # List all accounts
inbox-api accounts list --provider gmail             # Filter by provider
inbox-api accounts list --status error               # Filter by status
inbox-api accounts list --sort email                 # Sort by email address
inbox-api accounts folders <id>                      # List folders for an account

messages — Email Messages

inbox-api messages list                              # List messages (default: 10 per page)
inbox-api messages list --account <id> --unread      # Unread messages for an account
inbox-api messages list --starred                    # Starred messages only
inbox-api messages list --has-attachments             # Messages with attachments
inbox-api messages list --start-date 2026-01-01      # Date range filter
inbox-api messages list --sort subject               # Sort by subject
inbox-api messages list -q "quarterly report"        # Inline full-text search
inbox-api messages read <id>                         # Read full message with body
inbox-api messages update <id> --read                # Mark as read
inbox-api messages update <id> --star                # Star a message
inbox-api messages move <id> --folder-id <fid>       # Move to folder
inbox-api messages archive <id>                      # Archive a message
inbox-api messages attachments <id>                  # List attachments
inbox-api messages download <id> <attachmentId>      # Download an attachment
inbox-api messages delete <id>                       # Delete a message

send — Send Email

inbox-api send --account <id> \
  --to "Recipient <[email protected]>" \
  --cc "[email protected]" \
  --subject "Meeting tomorrow" \
  --text "Let's meet at 10am."

Recipients support both "Name <email>" and "email" formats.

reply — Reply to a Message

inbox-api reply <messageId> --text "Thanks, got it."
inbox-api reply <messageId> --reply-all --text "Sounds good to everyone."

forward — Forward a Message

inbox-api forward <messageId> --to "[email protected]"
inbox-api forward <messageId> --to "[email protected]" --text "FYI, see below."

search — Full-Text Search

inbox-api search "quarterly report"
inbox-api search "from:[email protected]" --account <id>
inbox-api search "invoice" --starred --sort relevance
inbox-api search "urgent" --unread --start-date 2026-03-01

drafts — Draft Management

inbox-api drafts list                              # List drafts
inbox-api drafts list --account <id>               # Drafts for an account
inbox-api drafts list --start-date 2026-03-01      # Filter by date
inbox-api drafts get <id>                          # View a draft
inbox-api drafts create --account <id> --to "[email protected]" --subject "WIP"
inbox-api drafts update <id> --account <id> --text "Updated content"
inbox-api drafts send <id>                         # Send a draft
inbox-api drafts delete <id>                       # Delete a draft

threads — Email Threads

inbox-api threads list                             # List threads
inbox-api threads list --account <id>              # Threads for an account
inbox-api threads list --unread-only               # Unread threads only
inbox-api threads list --start-date 2026-03-01     # Filter by date range
inbox-api threads get <id>                         # View thread with all messages

webhooks — Webhook Management

inbox-api webhooks list                            # List webhooks
inbox-api webhooks get <id>                        # Get webhook details
inbox-api webhooks create --url https://... --events message.received
inbox-api webhooks update <id> --url https://...   # Update a webhook
inbox-api webhooks delete <id>                     # Delete a webhook
inbox-api webhooks deliveries <id>                 # List delivery attempts
inbox-api webhooks retry <id> <deliveryId>         # Retry a failed delivery
inbox-api webhooks purge <id>                      # Purge old delivery records
inbox-api webhooks templates                       # List webhook event templates

batch — Bulk Operations

inbox-api batch mark-read <id1> <id2> ...          # Mark multiple messages as read
inbox-api batch mark-read --unread <id1> <id2>     # Mark multiple as unread
inbox-api batch archive <id1> <id2> ...            # Archive multiple messages
inbox-api batch move --folder-id <fid> <id1> <id2> # Move multiple messages

contacts — Contact Discovery

inbox-api contacts list                            # List frequency-ranked contacts
inbox-api contacts list --account <id>             # Contacts for an account

digest — Email Digest

inbox-api digest                                   # Digest of recent emails across accounts
inbox-api digest --hours 24                        # Last 24 hours
inbox-api digest --account <id>                    # Digest for a specific account

health — Account Health

inbox-api health <accountId>                       # Check IMAP connection health

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error / API error | | 2 | Authentication error (401/403) | | 3 | Connection error (server unreachable) |

Prerequisites

• Node.js >= 18
• An Inbox API account with an API token (cw_ prefix)

Development

# Build (requires @inbox-api/client built first)
npm run build

# Watch mode
npm run dev

License

MIT