Setup guides, MCP agent connection, and protocol reference.
Connect any standard IMAP4rev1 and ESMTP mailbox, attach Claude Code, OpenAI Codex, Muse, Antigravity, or local Ollama models via HTTP MCP, and deploy the native Rust binary anywhere.
Native Tauri v2 desktop and single-binary Rust quickstart
Zok Mail compiles from a Cargo workspace into two native binaries: zok-mail (the Tauri v2 desktop application with native window controls and an embedded Tokio engine) and zok-server (the standalone HTTP and MCP daemon for browser or private VPC access).
Build and launch from source
cargo build --release --workspace
./target/release/zok-mail
# Or run the headless server on http://127.0.0.1:3000:
./target/release/zok-server
Want to explore the frosted glass inbox, Glass Calendar, inline SVG charts, and Agent Co-Pilot before adding credentials? Open the instant demo workspace.
Connecting Agents and Local HTTP MCP
Zok Mail exposes a built-in Model Context Protocol JSON-RPC 2.0 endpoint at POST /api/mcp alongside the in-app Agents view (⌘J for the Co-Pilot dock). Connected harnesses can search SQLite FTS5 mail, summarize threads, render safe inline SVG charts from numbers, and query free calendar windows.
Register Zok Mail in Claude Code, Codex, Muse, or Antigravity
Attach coding and workflow harnesses to Zok MCP
# Claude Code (HTTP MCP transport)
claude mcp add --transport http zok http://127.0.0.1:3000/api/mcp
# OpenAI Codex CLI (authenticated via ChatGPT login or API key)
codex --mcp-server http://127.0.0.1:3000/api/mcp
# Local air-gapped inference via Ollama or LM Studio
ollama serve && ZOK_LOCAL_LLM_URL=http://127.0.0.1:11434/v1 ./target/release/zok-mail
All 15 exposed MCP tools: mail_search, mail_read_thread, mail_organize, mail_draft, mail_send, calendar_list_events, calendar_find_free_slots, calendar_schedule_event, viz_render_chart, ui_customize_theme, workspace_create_smart_view, agent_upsert_skill, mail_upsert_rule, keybindings_customize, and viz_render_widget. When any customization tool runs over MCP, Zok Mail broadcasts workspace_customized over /api/events SSE so open windows restyle live.
Themes, [data-slot] Custom CSS, and Portable SKILL.md Workflows
Press ⌥ ⌘ A (Ctrl+Alt+A on Linux and Windows) or ask any connected agent to restyle and rewire your workspace. Zok Mail ships 7 WCAG-verified presets (pearl, glass, aurora-dusk, nordic-frost, kyoto-linen, matcha-glass, and espresso-studio) and exposes 9 stable data-slot selectors: shell, sidebar, list-pane, mail-card, reader-pane, reader-header, composer, agent-dock, and chart-card.
Scoped [data-slot] Custom CSS example
Sanitized at rest by zok_core::sanitize_custom_css
Import or author reusable /slash commands in Customize Studio (seeded with /exec-brief, /chart-reply, and /find-time). Setting pinAsQuickAction: true mounts a 1-click pill inside [data-slot="reader-header"].
SKILL.md with scoped MCP tool allowlist
---
name: Board Brief
slug: board-brief
description: Summarize forecast threads and render a KPI widget
allowedTools: [mail_read_thread, viz_render_widget, mail_draft]
pinAsQuickAction: true
keybinding: Shift+B
---
Read the active forecast thread, render an executive KPI widget, and stage a concise reply.
Want to see all 5 customization acts run live? Open the interactive makeover demo, and click Reset to Pearl (POST /api/customize/reset) anytime to restore clean defaults.
Gmail and Google Workspace
Connect personal Gmail accounts or Google Workspace domains using either OAuth 2.0 (XOAUTH2) or a 16-character Google App Password.
Inbound IMAP hostimap.gmail.com:993
Outbound SMTP hostsmtp.gmail.com:465
Ensure 2-Step Verification is enabled on your Google Account, then create a scoped 16-character App Password (or configure Google OAuth client keys in Enterprise settings).
In Zok Mail, open account setup, select Gmail, and paste your address and credential without spaces.
Click Test Connection to verify TLS 1.3 IMAP and SMTPS sockets before saving to the AES-256-GCM vault.
Microsoft Outlook and Microsoft 365
Zok Mail supports Outlook.com, Hotmail, Live, and Microsoft 365 Exchange Online mailboxes over implicit TLS IMAP and STARTTLS SMTP.
For Microsoft 365 tenants, verify that Authenticated SMTP and IMAP4 are enabled for the mailbox in the Exchange Admin Center, or register an internal Entra ID OAuth 2.0 application.
Apple iCloud and Custom iCloud+ Domains
Apple requires an App-Specific Password generated at account.apple.com for third-party IMAP and SMTP clients. If you send from a custom iCloud+ domain, authenticate with your primary Apple ID email and set the custom domain as your sender address.
Inbound IMAP hostimap.mail.me.com:993
Outbound SMTP host (STARTTLS)smtp.mail.me.com:587
Fastmail and Yahoo Mail
Generate a scoped IMAP/SMTP app password in Fastmail (Settings, Privacy and Security, Integrations) or Yahoo Account Security, then use the endpoints below.
Yahoo Mail IMAP / SMTPSimap.mail.yahoo.com:993 / smtp.mail.yahoo.com:465
Proton Mail Bridge
Run Proton Mail Bridge locally on your workstation so OpenPGP encryption and decryption stay inside the Bridge daemon while Zok Mail connects over loopback sockets.
Bridge local IMAP127.0.0.1:1143
Bridge local SMTP127.0.0.1:1025
Use the Bridge-generated mailbox password (not your Proton web password) and enable the local Bridge TLS certificate option for 127.0.0.1.
Self-Hosting with Rust Binary and Docker Compose
Deploy zok-server anywhere with persistent SQLite WAL storage and a 32-byte hex ZOK_MASTER_KEY for the AES-256-GCM credential vault.
Every navigation, triage, calendar, and agent action in Zok Mail is reachable without leaving the home row, and custom bindings can be scoped by when context (global, mailListFocus, readerFocus, composerFocus, agentDockOpen).
Open command palette⌘K
Toggle Agent Co-Pilot glass dock⌘J
Open Customize Studio (themes, CSS, skills, rules)Alt⌘A