zoho , Zoho Mail CLI

intent

zoho is a command-line tool for reading, searching, sending, and managing Zoho Mail messages and folders. use it when you need to automate email workflows, build agent integrations, or script email operations without third-party API gateways. all output is json by default, making it ideal for piping into jq, agents, or other tools. you need the zoho binary installed, one-time oauth setup (zoho config init && zoho login), and local credential storage (config file + os keyring). tokens refresh automatically before every command.

inputs

binary requirement:

• zoho CLI tool (Python 3.11+, macOS/Linux/Windows). install via:
  • homebrew: brew install robsannaa/tap/zoho-cli
  • uv: uv tool install git+https://github.com/robsannaa/zoho-cli
  • pipx: pipx install git+https://github.com/robsannaa/zoho-cli

oauth setup (one-time):

• run zoho config init to provide Zoho OAuth client_id and client_secret (obtain from https://accounts.zoho.com/developerconsole)
• run zoho login to authenticate (opens browser, auto-detects region)
• verify with zoho config show (should return json with default_account and non-empty accounts map)

credential storage (sensitive):

• oauth client_id/client_secret: saved in config file (e.g. ~/.config/zoho-cli/config.json)
• access/refresh tokens: stored in os keyring (encrypted) or in encrypted file if ZOHO_TOKEN_PASSWORD env var is set
• do not expose config files or keyring entries to untrusted parties

environment variables (optional):

• ZOHO_ACCOUNT: default Zoho account email (overrides default_account in config)
• ZOHO_CONFIG: path to config.json (overrides default location)
• ZOHO_TOKEN_PASSWORD: passphrase for encrypted file token storage (useful in ci/headless environments where os keyring is unavailable)

network access:

• all commands require network connectivity to Zoho Mail API endpoints

procedure

1. verify cli is installed and authenticated

   • input: shell environment with zoho binary available
   • run: zoho config show
   • output: json object with default_account and accounts map, or error if not logged in
   • decision: if exit code 1 or not_logged_in error, user must run zoho login before proceeding

2. list messages in a folder

   • input: optional folder name, optional limit (default 50), optional account (env or flag)
   • run: zoho mail list [--folder FOLDER_NAME] [--limit N] [--account EMAIL]
   • output: json array of message summaries with messageId, subject, from, to, date (unix ms), unread, hasAttachments, tags
   • edge case: empty folder returns empty json array [], not an error

3. search messages

   • input: query string (e.g. "invoice 2025" or "from:boss@example.com"), optional limit
   • run: zoho mail search "QUERY" [--limit N]
   • output: same json array shape as list
   • edge case: no matches returns empty array; search is server-side, not cached

4. retrieve full message

   • input: message_id (required), optional folder_id (speeds up lookup), optional account
   • run: zoho mail get MESSAGE_ID [--folder-id FOLDER_ID]
   • output: json object with all fields from summary plus textBody, htmlBody, cc, bcc
   • edge case: if folder_id not provided, cli scans all folders; if message_id invalid, returns message_not_found error

5. list attachments in a message

   • input: message_id (required), optional folder_id, optional account
   • run: zoho mail attachments MESSAGE_ID [--folder-id FOLDER_ID]
   • output: json array of attachment objects with attachmentId, fileName, size (bytes)
   • edge case: message with no attachments returns empty array

6. download single attachment

   • input: message_id, attachment_id, output file path
   • run: zoho mail download-attachment MESSAGE_ID ATTACHMENT_ID --out /path/to/file
   • output: json object with status: "ok", path, size
   • edge case: if file already exists at --out path, cli overwrites it; if disk is full, error on stderr

7. send message

   • input: to addresses (required, one or more), subject (required), body (text or html), optional cc, optional bcc, optional attachments, optional account
   • run: zoho mail send --to ADDR [--to ADDR …] --subject "SUBJ" [--text "BODY" | --html-file FILE] [--cc ADDR] [--bcc ADDR] [--attach FILE …]
   • output: json object with status: "ok" and messageId
   • edge case: if both --text and --html-file provided, html takes precedence; if file not found, error before sending

8. mark messages as read/unread

   • input: one or more message_ids, optional account
   • run: zoho mail mark-read ID [ID …] or zoho mail mark-unread ID [ID …]
   • output: json object with status: "ok", updated array of ids, failed array
   • edge case: if some ids fail (e.g. deleted), they appear in failed but command exits 0

9. move messages to folder

   • input: one or more message_ids, target folder name, optional account
   • run: zoho mail move ID [ID …] --to "FOLDER_NAME"
   • output: json object with status: "ok", updated array, failed array
   • decision: if folder name doesn't match any existing folder, returns folder_not_found error

10. spam / not-spam / archive / delete

    • input: one or more message_ids, optional account
    • run: zoho mail spam ID [ID …] or zoho mail not-spam ID [ID …] or zoho mail archive ID [ID …] or zoho mail unarchive ID [ID …] or zoho mail delete ID [ID …] or zoho mail delete ID [ID …] --permanent
    • output: json object with status: "ok", updated array, failed array
    • decision: if --permanent flag absent, delete moves to trash; if --permanent present, hard delete (unrecoverable)
    • edge case: unarchive on already-unarchived message succeeds with empty updated array

11. list folders

    • input: optional account
    • run: zoho folders list
    • output: json array of folder objects with folderId, folderName, folderType (e.g. "Inbox", "Sent", "Custom"), path, isArchived, unreadCount, messageCount

12. create / rename / delete folder

    • input: folder name (for create), folder_id and new name (for rename), folder_id (for delete), optional parent folder_id (for create), optional account
    • run: zoho folders create "NAME" [--parent-id PARENT_ID] or zoho folders rename FOLDER_ID "NEW_NAME" or zoho folders delete FOLDER_ID
    • output: json object with status: "ok" and created/updated folderId
    • edge case: delete on non-empty folder succeeds (messages move to trash implicitly or stay in place depending on api behavior); parent_id mismatch returns error

13. inspect or reset configuration

    • input: optional account
    • run: zoho config show or zoho config path or zoho config init
    • output: config show returns json config (secrets redacted); config path returns {"config_path": "...", "exists": true}; config init is interactive (prompts on stderr, no json output)

14. handle authentication failures

    • input: any command result with exit code 1 and error json
    • check error json for error field value: not_logged_in, token_refresh_failed, no_account_id
    • action: run zoho login [--account EMAIL] to re-authenticate
    • output: browser opens for oauth flow; tokens stored automatically
    • edge case: if keyring is locked or unavailable and ZOHO_TOKEN_PASSWORD not set, login fails; user must set env var or unlock keyring

decision points

if user is not authenticated:

• error message on stderr: "error": "not_logged_in" or "error": "token_refresh_failed"
• action: user must run zoho login [--account EMAIL]
• do not attempt fallback; oauth is mandatory

if message_id not found:

• error message: "error": "message_not_found"
• behavior: if folder_id was not provided, cli scanned all folders; if folder_id was provided, it only checked that folder
• action: verify message_id is correct or check a different folder

if folder name doesn't match:

• error message: "error": "folder_not_found"
• action: run zoho folders list to get exact folder name; names are case-sensitive

if output format requested:

• if --md flag present, output markdown table (human-readable) instead of json
• if no flag, default to json (machine-readable, safe for piping)

if attachment file path does not exist (on send):

• error on stderr before any api call; exit 1
• action: verify file path and try again

if target file already exists (on download-attachment):

• behavior: cli overwrites file silently (no confirmation prompt)
• action: if you need to preserve original, move or rename it first

if api rate limit hit:

• error message: "error": "api_error" with details mentioning rate limit
• action: wait before retrying (backoff 60+ seconds); avoid bulk operations in rapid succession
• edge case: if bulk operation (e.g. 100 mark-read) exceeds limit mid-operation, some ids succeed and others fail; check failed array

if network timeout or connection lost:

• error message: "error": "api_error" or connection error on stderr
• action: verify network connectivity and retry; no built-in retry loop

if os keyring is unavailable or locked (macOS/Linux):

• error during zoho login or token refresh
• fallback: set ZOHO_TOKEN_PASSWORD env var to enable encrypted file storage instead
• action: user must export ZOHO_TOKEN_PASSWORD before running commands

output contract

success responses (exit 0):

• stdout: json (default) or markdown table (if --md flag)
• message list/search: json array of message objects
• message get: json object with full message details
• attachments: json array of attachment metadata
• send/move/mark-read/delete: json object with status: "ok", updated array of ids, optional failed array
• config show: json object with redacted secrets
• no trailing newline issues; json is valid, pipeable, newline-delimited for arrays

error responses (exit 1):

• stderr: json error object with status: "error", error code string, details explanation
• error codes: not_logged_in, token_refresh_failed, no_account_id, folder_not_found, message_not_found, api_error, etc.
• stdout: empty (errors never appear in stdout)
• examples: {"status": "error", "error": "message_not_found", "details": "..."}

file downloads (download-attachment):

• binary file written to disk at --out path
• stdout: json object confirming path and size
• no temporary files left behind on error

timestamps:

• all date fields are unix timestamps in milliseconds (not seconds)
• convert to human-readable: jq '.date | tonumber / 1000 | strftime("%Y-%m-%d %H:%M:%S")'

outcome signal

the skill worked if:

• command exits with 0
• stdout contains valid json (or markdown table if --md used)
• expected fields are present in output (e.g. messageId, subject, from in a message list)
• no error json appears on stdout (only on stderr)

common success checks:

• zoho mail list | jq '.[] | .messageId' prints message ids without errors
• zoho mail send --to user@example.com --subject "test" --text "hi" | jq '.status' returns "ok"
• zoho mail mark-read $ID | jq '.updated | length' returns count of updated messages
• zoho config show | jq '.default_account' returns a non-null email address
• download-attachment creates file at specified path with non-zero size

how to know it failed:

• exit code 1
• stderr contains json error object
• stdout is empty or missing expected fields
• error message mentions not_logged_in, token_refresh_failed, message_not_found, or folder_not_found
• file operations hang or timeout (set --debug flag to see http logs, or interrupt and check network)

debug mode:

• run any command with --debug flag to see http requests, responses, and internal logs on stderr
• logs help diagnose auth issues, api errors, or unexpected behavior

---

credits: original CLI by robsannaa (https://github.com/robsannaa/zoho-cli). skill documentation enriched for Implexa standards.