Zoho Mail CLI access — planning doc

Planning document for setting up terminal / CLI access to the Zoho Mail archive, matching the gws Google Workspace CLI setup already in place for Gmail. Not yet implemented. Revisit on a future session.

Current email topology (as of 2026-04-23)

• Google Workspace hosts the personal mailboxes for Patrick (pat@baseworks.com) and Asia, with aliases (pat@cevaco.co, pat@paraimpacto.com, pat@shaspo.org, po@paraimpacto.com) all routing into those accounts. Handled today via the gws CLI.
• Zoho Mail hosts every other mailbox across the owned domains. One organization-admin account manages the domain configuration; each domain has its own Zoho login handling its aliases. Historical correspondence (trademarks, accounting, legal, vendor threads) mostly lives here. Thousands of messages across multiple domain mailboxes.
• DNS routing is a Google-primary configuration with exceptions that route specific mailboxes to Zoho’s MX records. Exact mechanism undocumented; needs to be reverse-engineered from the DNS zone (see open questions below).

Why this matters

• Today, searching Zoho archives means logging into each domain’s webmail individually. Slow, error-prone, no cross-domain search.
• Today’s trademark workstream exposed the gap: Shobayashi correspondence was on a Zoho-hosted address and had to be manually forwarded to pat@baseworks.com (Gmail) for Claude to search through gws. That workflow does not scale to other historical lookups (vendor contracts, early Baseworks contracts, accounting).
• CLI access would let Claude cross-reference any archival thread in seconds during a session, the same way it does with Gmail now.

Options

Option A — IMAP via himalaya (per-account config)

What it is: himalaya is a modern IMAP/SMTP CLI. Each Zoho login becomes an account block in its config file. Authenticates with app-specific passwords (not main Zoho password).

Pros:

• Simplest to set up — 1-2 hours for first account, 15 min per additional
• Works with any IMAP server, not Zoho-specific
• Search, read, send, reply, attachments all supported
• App passwords are revocable per-device (safer than main password)

Cons:

• N accounts × N configs to maintain
• IMAP search is slower than API search on large archives (Zoho has millions of indexed messages; IMAP grep is less efficient)
• Each Zoho login needs its own app password generated manually via Zoho security settings
• No Zoho-specific features (tags, org-wide admin queries)

Effort estimate: ~2-3 hours to set up for all domains.

Option B — Zoho Mail Admin API (single OAuth app, org-wide access)

What it is: Zoho offers a REST API with admin-level scopes that let a single OAuth app read/send on behalf of any user in the organization. One app registered in Zoho API Console, one OAuth client ID/secret, one refresh token — access to every domain mailbox through admin impersonation.

Pros:

• Single credential handles all mailboxes — matches Patrick’s “unified access” goal directly
• API search is fast across large archives (Zoho’s server-side index)
• Supports Zoho-specific features (tags, threads, org filters)
• Cleanest long-term — adding a new domain = no new auth, just start querying
• Admin API lets Claude search Ksenia’s Zoho mailboxes too (when authorized by her) without separate logins

Cons:

• More initial setup: register OAuth app in Zoho API Console, configure scopes, handle token refresh, pick a credential store
• Requires building a small wrapper CLI (no gws-equivalent ready to install)
• Need to pick the right scope tier — ZohoMail.accounts.READ and ZohoMail.messages.ALL at minimum; admin scopes cost more token-refresh complexity

Effort estimate: ~4-6 hours for a first working version; pays off quickly after that.

Option C — Hybrid: start with himalaya, upgrade to Admin API when needed

Pattern: install himalaya for the 2-3 Zoho accounts used most often. Live with it. If it hits a ceiling (too slow on search, missing features, too many accounts to configure), invest in Option B.

Pros:

• Fastest time to working CLI
• Avoids over-engineering before use patterns are clear
• Easy migration path (Option B can coexist with or replace Option A)

Cons:

• Two setups to maintain short-term
• Incomplete coverage until upgrade happens

Recommendation

Option C as an entry point, with Option B as the documented target. Install himalaya for the 2-3 highest-value mailboxes this week; use it for a month; if the pattern justifies it, build the Admin API wrapper on that evidence.

If it’s clear up front that cross-domain search across all mailboxes is the primary use case (not occasional per-account lookups), skip straight to Option B — it’s the correct shape for that workload and the extra setup time pays back quickly.

Open questions

1. Which Zoho accounts are the highest-value targets? A ranked list would drive the himalaya setup order. Candidates based on what surfaced today: any Baseworks domain addresses that handle vendor/legal/accounting, any address that received Shobayashi correspondence, any address that held early contracts.
2. DNS mechanism — who decides which addresses route to Zoho vs. Google? Needs a zone-file walkthrough. Likely a mix of MX priority, split-domain configuration with SPF/DKIM records, or Zoho Mail routing rules. Worth documenting in 00-inbox/claude-code-shared-context.md once understood.
3. Does Asia’s Zoho access need parity with Patrick’s? If yes, Option B becomes more attractive (one credential can serve both). If her use is lighter, himalaya on her own machine is fine.
4. Credential storage: mac Keychain? ~/.config/baseworks/? pass? Same pattern as gws (encrypted credentials in ~/.config/gws/credentials.enc) is probably the right model.
5. Retention and compliance: Zoho has per-mailbox retention settings. Any outbound email sent from the CLI needs to be archived the same way Zoho webmail archives it. Confirm before writing a “send” path.

What doing this enables

• Cross-reference any historical thread in seconds during a session (trademarks, contracts, vendor history, Para Impacto correspondence, Shaspo/Ceva business records, etc.)
• Draft replies to any Zoho-hosted conversation without bouncing through Gmail forwarding
• Archive-search questions like “what did we agree with X in Y year” become tractable
• Potential future automation: daily digest of unread Zoho mail into the vault, or auto-capture of specific senders

Not doing this now — why revisit?

Patrick flagged this as something to come back to on a separate day. The trademark workstream is the immediate priority and is now closed. This plan is a placeholder to pick up without re-deriving the shape of the problem.

Status

Not yet executed. When executed, move this file to 03-resources/executed-plans/ and add an entry to 00-executed-plans-index.md.

Related

• Plans
• Japan trademark — Shobayashi correspondence is the concrete example that exposed the Zoho-access gap
• Shared operational context