NuGet package
.NET CLI
A native .NET global tool for managing email accounts, sending messages, creating scoped API tokens, and automating workflows. Rich terminal output with Spectre.Console.
Quick start
# Install
dotnet tool install --global inbox-api-cli
# Configure your API token
mail-cli configure --api-token cw_your_token
# List your email accounts
mail-cli accounts list
# Read your latest unread messages
mail-cli messages list --unread
# Send an email
mail-cli send --account <id> --to "bob@example.com" --subject "Hello" --body "Hi Bob!"
# Search across all accounts
mail-cli search "invoice Q3"Node.js CLI vs .NET CLI
Both CLIs provide the same core functionality. Choose based on your environment:
@inbox-api/cli (Node.js)
- Requires Node.js 18+
- Install via npm
- Address parsing: "Name <email>"
inbox-api-cli (.NET)
- Requires .NET 9 runtime
- Install via dotnet tool
- Short ID prefix matching
- Rich Spectre.Console output
Installation
Install as a .NET global tool:
dotnet tool install --global inbox-api-cli
Verify the installation:
mail-cli --help
Requirements: .NET 9 runtime or SDK
Authentication
The .NET CLI authenticates using API tokens (prefixed with cw_).
Three ways to provide credentials, checked in order:
# 1. CLI flags (highest priority)
mail-cli accounts list --api-token cw_your_token --api-url https://api.inbox-api.com
# 2. Environment variables
export CLOUDWORKS_API_TOKEN=cw_your_token
export CLOUDWORKS_API_URL=https://api.inbox-api.com
# 3. Config file (saved by 'configure' command)
mail-cli configure
Saves credentials to ~/.cloudworks/config.json.
Global Options
Available on every command:
--json Output as JSON
--no-color Disable colored output
--debug Show debug information
configure
Set up API connection. Tests the connection before saving.
mail-cli configure
mail-cli configure --api-url https://api.inbox-api.com --api-token cw_your_token
Options:
--api-url <url> API base URL (default: http://localhost:5015)
--api-token <token> API token
accounts list
List all connected email accounts.
mail-cli accounts list
┌──────────────────────┬─────────────────────┬──────────────┬────────────┬──────────┐
│ ID │ Email │ Display Name │ Sync │ Messages │
├──────────────────────┼─────────────────────┼──────────────┼────────────┼──────────┤
│ a1b2c3d4-... │ me@gmail.com │ Personal │ Synced │ 1,247 │
│ e5f6g7h8-... │ work@company.com │ Work │ Syncing... │ 3,891 │
└──────────────────────┴─────────────────────┴──────────────┴────────────┴──────────┘
messages list
List messages with filtering and pagination.
mail-cli messages list
mail-cli messages list --account <id> --unread
mail-cli messages list --starred --sort subject
mail-cli messages list --query "invoice" --has-attachments
Options:
--account <id> Filter by account
--folder <id> Filter by folder
--unread Show only unread messages
--starred Show only starred messages
--has-attachments Show only messages with attachments
--start-date <date> Filter from date
--end-date <date> Filter to date
--sort <order> Sort: date, date_asc, subject, from
--query <text> Full-text search query
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 10, max: 100)
messages get
Get message details, optionally including the body.
mail-cli messages get <message-id>
mail-cli messages get <message-id> --body # include text body
mail-cli messages get <message-id> --body --html # include HTML body
Options:
--body Display the message body
--html Show HTML body instead of plain text (requires --body)
send
Send a new email. At least --body or --html-body is required.
mail-cli send \
--account <account-id> \
--to "alice@example.com,bob@example.com" \
--subject "Weekly Update" \
--body "Hi team, here's the weekly update."
Options:
--account <id> Account to send from (required)
--to <emails> Comma-separated recipients (required)
--subject <subject> Email subject (required)
--body <text> Plain text body
--html-body <html> HTML body
--cc <emails> Comma-separated CC recipients
--bcc <emails> Comma-separated BCC recipients
reply
Reply to an existing message.
mail-cli reply <message-id> --body "Thanks, looks good!"
mail-cli reply <message-id> --body "Noted, thanks everyone." --reply-all
Options:
--body <text> Reply body (required)
--html-body <html> HTML reply body
--reply-all Reply to all recipients
search
Full-text search across all accounts.
mail-cli search "invoice"
mail-cli search "project deadline" --account <id>
Options:
--account <id> Limit to a specific account
--sort <order> Sort: relevance, date, date_asc, subject, from
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 10, max: 100)
drafts list
List saved drafts.
mail-cli drafts list
mail-cli drafts list --account <id>
mail-cli drafts list --start-date 2026-03-01
Options:
--account <id> Filter by account
--start-date <date> Filter from date
--end-date <date> Filter to date
--sort <order> Sort order
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 10)
drafts get
Get a specific draft.
mail-cli drafts get <draft-id>
drafts create
Create a new draft.
mail-cli drafts create \
--account <account-id> \
--to "alice@example.com" \
--subject "Proposal" \
--body "Here's the draft proposal..."
Options:
--account <id> Account for the draft (required)
--to <emails> Comma-separated recipients
--subject <subject> Subject line
--body <text> Plain text body
--html-body <html> HTML body
drafts update
Update an existing draft.
mail-cli drafts update <draft-id> --subject "Updated Subject"
drafts send
Send a saved draft.
mail-cli drafts send <draft-id>
drafts delete
Delete a draft.
mail-cli drafts delete <draft-id>
mail-cli drafts delete <draft-id> --force # skip confirmation
folders list
List folders for an email account.
mail-cli folders list <account-id>
┌──────────────────────┬──────────┬──────────────────┬──────────┐
│ Name │ Path │ Type │ Messages │
├──────────────────────┼──────────┼──────────────────┼──────────┤
│ INBOX │ INBOX │ Inbox │ 1,247 │
│ Sent │ Sent │ Sent │ 892 │
│ Drafts │ Drafts │ Drafts │ 3 │
└──────────────────────┴──────────┴──────────────────┴──────────┘
forward
Forward a message to new recipients.
mail-cli forward <message-id> --to "alice@example.com"
mail-cli forward <message-id> --to "alice@example.com,bob@example.com" --body "FYI, see below."
Options:
--to <emails> Comma-separated recipients (required)
--body <text> Optional message to prepend
--html-body <html> Optional HTML message to prepend
messages flag
Update message flags (read/starred status).
mail-cli messages flag <message-id> --read
mail-cli messages flag <message-id> --starred
mail-cli messages flag <message-id> --read --starred
Options:
--read Mark as read (or unread with --no-read)
--starred Mark as starred (or unstarred with --no-starred)
messages move
Move a message to a different folder.
mail-cli messages move <message-id> --folder <folder-id>
messages archive
Archive a message.
mail-cli messages archive <message-id>
messages delete
Delete a message.
mail-cli messages delete <message-id>
mail-cli messages delete <message-id> --force # skip confirmation
attachments list
List attachments for a message.
mail-cli attachments list <message-id>
attachments download
Download an attachment from a message.
mail-cli attachments download <message-id> <attachment-id>
mail-cli attachments download <message-id> <attachment-id> --output "./downloads/"
Options:
--output <path> Output directory or file path
threads list
List email threads with filtering and pagination.
mail-cli threads list
mail-cli threads list --account <id> --unread
mail-cli threads list --start-date 2026-03-01 --sort date_asc
Options:
--account <id> Filter by account
--unread Show only threads with unread messages
--start-date <date> Filter from date
--end-date <date> Filter to date
--sort <order> Sort order
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 10, max: 100)
threads get
Get a thread with all its messages.
mail-cli threads get <thread-id>
webhooks list
List webhook subscriptions.
mail-cli webhooks list
webhooks get
Get webhook details.
mail-cli webhooks get <webhook-id>
webhooks deliveries
List delivery attempts for a webhook.
mail-cli webhooks deliveries <webhook-id>
webhooks retry
Retry a failed webhook delivery.
mail-cli webhooks retry <webhook-id> <delivery-id>
webhooks delivery
Get a single webhook delivery by ID.
mail-cli webhooks delivery <webhook-id> <delivery-id>
batch mark-read
Batch mark messages as read or unread.
mail-cli batch mark-read --ids "id1,id2,id3"
mail-cli batch mark-read --ids "id1,id2" --unread
Options:
--ids <ids> Comma-separated message IDs (required)
--unread Mark as unread instead of read
batch archive
Batch archive messages.
mail-cli batch archive --ids "id1,id2,id3"
Options:
--ids <ids> Comma-separated message IDs (required)
batch move
Batch move messages to a folder.
mail-cli batch move --ids "id1,id2,id3" --folder <folder-id>
Options:
--ids <ids> Comma-separated message IDs (required)
--folder <id> Target folder ID (required)
contacts list
List frequency-ranked contacts across your accounts.
mail-cli contacts list
mail-cli contacts list --account <id>
Options:
--account <id> Filter by account
--page <n> Page number (default: 1)
--page-size <n> Results per page (default: 10, max: 100)
digest
Get an email digest summary across all accounts.
mail-cli digest
mail-cli digest --account <id>
Options:
--account <id> Limit to a specific account
health
Check IMAP health status for an email account.
mail-cli health <account-id>