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

Verify MCP tool discovery with curl

JSON-RPC 2.0 tools/list request
curl -s -X POST http://127.0.0.1:3000/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

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
[data-slot="sidebar"] {
  background: rgba(11, 23, 36, 0.86);
  border-color: rgba(45, 212, 191, 0.24);
}
[data-slot="mail-card"] {
  border-radius: 18px;
  backdrop-filter: blur(22px);
}

Portable SKILL.md /slash workflows

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 host imap.gmail.com:993
Outbound SMTP host smtp.gmail.com:465
  1. 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).
  2. In Zok Mail, open account setup, select Gmail, and paste your address and credential without spaces.
  3. 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.

Inbound IMAP host outlook.office365.com:993
Outbound SMTP host (STARTTLS) smtp.office365.com:587

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 host imap.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.

Fastmail IMAP / SMTPS imap.fastmail.com:993 / smtp.fastmail.com:465
Yahoo Mail IMAP / SMTPS imap.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 IMAP 127.0.0.1:1143
Bridge local SMTP 127.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.

docker-compose.yml
services:
  zok-mail:
    build: .
    container_name: zok-server
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      PORT: "3000"
      ZOK_DB_PATH: "/data/zok.sqlite"
      ZOK_MASTER_KEY: "${ZOK_MASTER_KEY}"
    volumes:
      - zok_data:/data

volumes:
  zok_data:

Keyboard shortcut reference

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
Move to next / previous email card J / K
Open selected conversation Enter
Archive conversation E
Snooze conversation H
Toggle coral star S
Write new email C
Reply to conversation R
Send composed message ⌘ Enter
Focus SQLite FTS5 search bar /