Product Guide

Product Surfaces

• Landing page: /
• Product login: /login
• Product app:
• /app (overview)
• /app/inbox
• /app/sent
• /app/compose
• /app/agents
• /app/settings
• Admin login: /admin/login
• Admin control plane: /admin/*

Multi-Tenant Model

A **workspace** (tenant) scopes:

• Mailboxes
• Messages and folders
• Outbox queue
• Labels, threads, drafts
• Allow/block list entries
• Webhook endpoints and delivery logs
• Verified sending domains and service-token metadata

Each session has one active workspace. API and UI actions operate only within that workspace.

Authentication Model

• Product users authenticate via /login and receive a session cookie.
• Admin users authenticate via /admin/login.
• CLI users authenticate through /app/api/login and use X-Zmail-Session.
• Workload callers use opaque, hashed service tokens scoped to one workspace,

verified domain, mailbox, and message:send.

Core Flows

Inbox and Threads

• Messages are stored per mailbox and folder (inbox, sent, spam, archive, trash, draft).
• Thread IDs are computed from references/in-reply-to/subject normalization.
• Message and thread labels support agent state tagging (unread, processed, etc.).

Compose and Send

• Sending queues outbound mail and stores message state in sent.
• Attachments are persisted and sent as MIME multipart.
• Outbound policy checks can reject recipients based on list entries.

Transactional Send

• Owners/admins register a domain and publish its verification and DKIM records.
• Per-domain RSA private keys are encrypted in storage.
• Owners/admins issue rotatable mailbox-scoped service tokens; plaintext is

shown once.

• Transactional requests require a caller-stable idempotency key and disable

open tracking.

• SMTP acceptance is distinct from final delivery. Ambiguous outcomes become

terminal unknown rather than being retried.

Drafts

Drafts are first-class records with:

• Create/list/get/update/delete
• Optional labels and attachments
• send action to queue and move to sent

Lists (Allow/Block)

List entries are tenant-scoped and used for policy controls. Current outbound checks look for block matches on:

• Exact recipient email
• Domain and @domain patterns

Webhooks

Webhooks are tenant-scoped endpoints with durable leased delivery, signed raw

payloads, event filtering, and immutable retry logging.

• Manage under /app/api/webhooks
• Inspect attempts under /app/api/webhooks/{id}/deliveries
• Emit synthetic test events with /app/api/webhooks/{id}/test

UI/UX Notes

• Product app and admin are intentionally separate login paths.
• Product pages target operator and agent workflows.
• Admin pages target privileged operations and environment control.