zog

zog is a Python CLI for Zoho Mail, designed to feel familiar to anyone who already uses gog for Google services. It keeps the dependency set small, uses argparse, stores credentials under ~/.config/zogcli/, and supports both machine-readable and terminal-friendly output.

Install

pipx install zog-cli

uv tool install zog-cli

For local development:

uv venv
source .venv/bin/activate
uv pip install -e .[dev]

Quickstart

pipx install zog-cli
zog auth add me@example.com

This opens your browser to authorize zog. After you click Allow, the CLI captures the authorization callback automatically and stores your tokens locally.

For headless servers or SSH sessions without port forwarding, use the out-of-band flow:

zog auth add me@example.com --no-browser

For power users who want to use their own Zoho app, use --self-client.

Usage

Authorize your mailbox:

zog auth add you@yourdomain.com

Search mail:

zog mail search -a you@yourdomain.com "from:cloudflare" --max 3

List folders:

zog mail folders -a you@yourdomain.com

Dry-run a send:

zog mail send \
  -a you@yourdomain.com \
  --to friend@example.com \
  --subject "zog test" \
  --body "hello from zog" \
  --dry-run

Importing existing Zoho credentials

If you already have a JSON file with client_id, client_secret, and refresh_token from a previous Zoho Self Client setup, you can import it directly:

zog auth import-legacy /path/to/credentials.json

Command Reference

zog auth add <email> [--services mail] [--no-browser] [--port N]
zog auth list
zog auth remove <email>
zog auth import-legacy <path>

zog mail search -a <email> "<query>" [--max N] [-j|-p]
zog mail get -a <email> <messageId> [-j|-p]
zog mail thread get -a <email> <threadId> [-j|-p]
zog mail send -a <email> --to ... --subject ... --body ...
zog mail folders -a <email> [-j|-p]

zog --version

Global flags follow gog-style conventions:

• -a, --account
• -j, --json
• -p, --plain
• -n, --dry-run
• -v, --verbose
• -h, --help

Output Modes

• Default: aligned table output for list-style commands.
• --json: {"status": "...", "data": ...} envelope.
• --plain: stable TSV for scripting.

OAuth Setup

By default zog auth add uses Zoho's OAuth 2.0 Authorization Code flow with a local loopback server, so no manual Self Client setup is required. If you prefer to use your own Zoho app, use the --self-client flag:

zog auth add you@yourdomain.com --self-client

Then create or select a Self Client in the Zoho API Console:

https://api-console.zoho.com/

Use these scopes:

ZohoMail.messages.ALL,ZohoMail.accounts.READ,ZohoMail.folders.READ

Contributing

1. Create a virtual environment with uv venv.
2. Install the package in editable mode with uv pip install -e .[dev].
3. Run pytest -q.
4. Keep changes small, typed, and focused.

See LICENSE for license terms.

Setting up your own Zoho application

zog carries no client secret. Before adding an account, create a Zoho application in the Zoho API console and export its secret:

export ZOG_CLIENT_SECRET=your-client-secret
export ZOG_CLIENT_ID=your-client-id   # optional, only for your own app
zog auth add

An embedded secret used to ship in this repository, which is public, so anyone could stand up a consent page under that application's name. The secret has to come from the environment now and there is no fallback.