jmap-cli

A command-line interface for interacting with a JMAP server.

jmap-cli can also be used programmatically from the browser or as a Node o package — see API.md for the full API reference.

Installation

For detailed installation and configuration instructions, please see INSTALL.md.

Quick Start

If your server supports oAuth2:

# Set your JMAP server and credentials
jmap-cli init [url of your mail server]
jmap-cli login
# List your mailboxes
jmap-cli mailboxes

Authentication

jmap-cli supports several authentication strategies

1. Basic Auth (username/password)

Set JMAP_USERNAME and JMAP_PASSWORD — the credentials are encoded as a Basic Auth header immediately. No OAuth2 involved, works with any JMAP server.

export JMAP_BASE_URL="https://mail.example.com"
export JMAP_USERNAME="[email protected]"
export JMAP_PASSWORD="s3cret!"
jmap-cli mailboxes

2. Impersonation (Stalwart admin user)

Access another user's mailbox using the Stalwart impersonation permission feature.

export JMAP_ADMIN="[email protected]"
export JMAP_PASSWORD="admin-secret"
jmap impersonate --for [email protected]

Or interactively:

jmap impersonate --for [email protected]
Impersonator email (admin account): [email protected]
Impersonator password:

After impersonation, all subsequent jmap commands run as the target user.

3. Bearer Token (pre-existing JWT)

Set JMAP_TOKEN to any access token you already have:

export JMAP_TOKEN="eyJhbGciOi..."
jmap-cli mailboxes

This tokens are short lived, you should also set the refresh token to automatically refresh the access token when it expires:

export JMAP_REFRESH_TOKEN="rt_abc123..."
jmap-cli mailboxes

4. Device Authorization Grant (interactive login)

Run jmap login for an interactive OAuth2 Device Authorization Grant (RFC 8628) flow:

jmap-cli login

This will:

1. Contact the server's device authorization endpoint
2. Show a URL and code to enter in your browser
3. Wait until you complete the authorization
4. Save the access and refresh tokens to ~/.config/jmap-cli/config

Configuration file

The config file is stored at ~/.config/jmap-cli/config and uses a simple KEY="value" format. You can edit it directly or regenerate it with jmap init.

JMAP_BASE_URL="https://mail.example.com"
JMAP_TOKEN="eyJhbGciOi..."
JMAP_REFRESH_TOKEN="rt_abc123..."

CLI Usage

jmap-cli <command> [options]

Commands

| Command | Description | |---|---| | init | Set up server URL and optionally log in via OAuth2 device flow | | login | Interactive OAuth2 Device Authorization Grant login | | impersonate | Access another user's mailbox (Stalwart master user) | | mailboxes | List mailboxes | | mailbox | Create a new mailbox | | messages | List messages in a mailbox | | message | Fetch a single message | | send | Send an email | | search | Search messages | | keyword | Set keywords (seen, answered, flagged…) on a message | | move | Move a message to a different mailbox | | listen | Listen for real-time updates (experimental) |

init

jmap-cli init [url]

Prompts for a JMAP server URL and offers to start the OAuth2 device login flow. Saves configuration to ~/.config/jmap-cli/config.

login

jmap-cli login [options]

Interactive OAuth2 Device Authorization Grant (RFC 8628) flow. Displays a URL and code — open the URL in your browser, enter the code, and the CLI saves the resulting tokens to your config file.

impersonate

jmap-cli impersonate --for <target-email> [options]

Access another user's mailbox using Stalwart's master user feature. The login string is <target>%<admin> — the admin password is used for authentication.

Options:

• --for <email>: Target mailbox to access (required)

Environment variables:

• JMAP_ADMIN: Admin email (prompted if not set)
• JMAP_PASSWORD: Admin password (prompted if not set)

Examples:

# Interactive
jmap impersonate --for [email protected]

# Non-interactive
export JMAP_ADMIN="[email protected]"
export JMAP_PASSWORD="admin-secret"
jmap impersonate --for [email protected]

After running, all subsequent jmap commands operate on the target user's mailbox.

mailboxes

jmap-cli mailboxes [options]

Options:

• -j, --json: Output as JSON

messages

jmap-cli messages [mailbox] [options]

Options:

• -l, --limit <n>: Number of messages (default: 10)
• --sort <prop>: Sort property (receivedAt, from, to, subject, size)
• --order <asc|desc>: Sort order (default: desc)
• --read[=true|false], --answered[=true|false], --starred[=true|false], --junk[=true|false], --draft[=true|false]: Filter by keyword
• -j, --json: Output as JSON

message

jmap-cli message <message-id> [options]

Options:

• -j, --json: Output as JSON

send

jmap-cli send <to> [options]

Options:

• --from <email>: Sender address
• --from-name <name>: Sender display name
• --subject <text>: Email subject
• --text <text>: Email body (reads from stdin if not provided)
• --attach <file>: Attach a file

search

jmap-cli search [options] [freeform_query]

Options:

• --from <string>, --to <string>, --subject <string>, --body <string>: Filter by field
• --before <date>, --after <date>: Filter by date (YYYY-MM-DD)
• -l, --limit <n>: Number of messages (default: 10)
• --sort <prop>, --order <asc|desc>: Sort control
• -j, --json: Output as JSON