submail

<p align="center"> <img src="apps/web/public/submail-logo.png" alt="Submail logo" width="112" height="112"> </p> <h1 align="center">Submail</h1> <p align="center"><strong>A self-hosted unified inbox for humans and AI agents.</strong></p> <p align="center">Connect the mailboxes you already use, manage them from one Web UI, and expose carefully scoped email tools through MCP and HTTP.</p> <p align="center"> <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> </p> <p align="center"> <a href="https://github.com/guozhijian611/submail/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/guozhijian611/submail/actions/workflows/ci.yml/badge.svg"></a> <img alt="Node.js 22+" src="https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white"> <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-5.8-3178C6?logo=typescript&logoColor=white"> <img alt="Docker Compose" src="https://img.shields.io/badge/Docker-Compose-2496ED?logo=docker&logoColor=white"> <img alt="Model Context Protocol" src="https://img.shields.io/badge/MCP-Streamable_HTTP-5A45FF"> </p> <p align="center"> <a href="#why-submail">Why Submail</a> · <a href="#screenshots">Screenshots</a> · <a href="#quick-start">Quick start</a> · <a href="#mcp-and-send-api">MCP & API</a> · <a href="#security-model">Security</a> </p>

[!NOTE] Submail is not a mail server and does not replace Gmail, Outlook, QQ Mail, or your existing provider. It connects existing IMAP/POP3 mailboxes, sends through their SMTP servers, and gives people and agents one controlled workspace.

Why Submail

| | | | --- | --- | | One inbox, many accounts | Search, read, reply, forward, star, archive, delete, and manage attachments across multiple mailboxes. | | Built for agents | Use local stdio MCP, remote Streamable HTTP MCP, or a direct HTTP send API without maintaining separate integrations. | | Permissioned by default | Scope every key by capability, mailbox, expiry time, and daily send quota. New keys start with read-only permissions. | | Your data, your deployment | Run locally with SQLite or deploy with Docker, Redis/BullMQ, and SQLite or MySQL. |

Features

• Mail accounts: IMAP or POP3 receive, SMTP send, connection tests, provider presets, app-password guidance, and verified Send As aliases.
• Incremental sync: IMAP UID and POP3 UIDL cursors, remote read/star reconciliation, discoverable special folders including Junk/Spam, scheduled jobs, bounded retries, concurrency limits, and sync history.
• Unified workflow: Inbox, sent, drafts, starred, archived, junk, trash, conversation threading, advanced search, and bulk actions.
• Attachments: Centralized storage after sync, on-demand browser retrieval, .eml parsing, retention settings, and broad in-browser preview support.
• AI assistance: OpenAI-compatible providers for summaries, suggested replies, and email composition. Generated content is placed in the editor and is never sent automatically.
• Translation: Google-compatible, LibreTranslate, or custom HTTP providers with long-message chunking, a configurable default language, and opt-in automatic translation for clearly detected English email.
• MCP and API: Eight MCP tools plus a direct send endpoint, sharing the same authorization and delivery service.
• Operations: Health checks, least-privilege containers, durable Redis queues, audit retention, heartbeat-backed SQLite runtime locks with verified stale-lock recovery, online backup, and atomic restore.

Screenshots

<table> <tr> <td width="50%"> <img src="docs/images/submail-mcp-access.jpg" alt="MCP scopes and API access settings"> <br><strong>MCP and API access</strong><br>Account scopes, capability scopes, expiry, and daily send limits. </td> <td width="50%"> <img src="docs/images/submail-compose.jpg" alt="AI-assisted email composer"> <br><strong>AI-assisted composer</strong><br>Draft with AI, review the result, then decide whether to send. </td> </tr> </table>

All screenshots use a temporary SQLite database and synthetic .local addresses. No production mailbox data is included.

Quick start

Docker deployment

Install Docker Engine with the Compose plugin, then run:

git clone https://github.com/guozhijian611/submail.git
cd submail
./deploy.sh

The setup script lets you choose SQLite, bundled MySQL, or external MySQL. It generates secrets, starts Redis and all services, builds the images, and waits for health checks.

The gateway binds to 127.0.0.1:8080 by default. Put Caddy, Nginx, Traefik, or a load balancer with HTTPS in front of it before exposing Submail to the internet.

See the full deployment and operations guide for first-admin setup, database modes, backup/restore, and upgrades.

Local development

Requirements: Node.js 22+.

npm ci
npm run secure:local
npm run dev

• Web UI: http://localhost:5173
• API: http://localhost:8787
• Local database: apps/api/data/submail.sqlite
• Queue: in-memory by default; set SUBMAIL_QUEUE_DRIVER=redis and SUBMAIL_REDIS_URL to test Redis

npm run secure:local creates an apps/api/.env file with mode 600 and a dedicated master key. If an older local database still uses the development key, the script backs it up and re-encrypts stored mailbox and integration credentials without printing secrets.

Quality checks:

npm run typecheck
npm test
npm run build

MCP and send API

Create a key in Settings → MCP & Admin, select its scopes and allowed mailboxes, then use the remote endpoint:

https://mail.example.com/mcp

Every request carries the key:

Authorization: Bearer sk_submail_xxx

Available tools:

| Group | Tools | | --- | --- | | Read | list_accounts, search_mail, read_mail | | Send | send_mail | | AI | summarize_mail, draft_reply, compose_mail | | Translation | translate_mail |

Local stdio mode:

SUBMAIL_API_URL=http://127.0.0.1:8787 \
SUBMAIL_MCP_API_KEY=sk_submail_xxx \
npm run dev:mcp

Direct send API:

curl --fail-with-body 'https://mail.example.com/api/send' \
  -H 'Authorization: Bearer sk_submail_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-20260710-0001' \
  --data '{
    "accountId": "mailbox-account-id",
    "to": ["receiver@example.com"],
    "subject": "Hello from Submail",
    "text": "Sent through the Submail API"
  }'

The API supports text, HTML, CC/BCC, attachments, thread headers, idempotency keys, and optional verified aliases. MCP send_mail uses the same delivery path.

Security model

[!IMPORTANT] Email and attachments are untrusted input. Deploy behind HTTPS, grant the smallest possible scopes, keep send quotas low, and use app-specific mailbox passwords whenever the provider supports them.

• Mailbox credentials and third-party API keys are encrypted at rest with AES-GCM using SUBMAIL_SECRET.
• Admin passwords and MCP/API keys are stored as one-way hashes; a new key is displayed only once.
• Keys can be restricted by capability, mailbox, expiry, and daily send quota.
• AI output never sends automatically; it enters the composer for human review.
• Audit logs record metadata rather than message bodies, prompts, email addresses, attachment Base64, or idempotency keys.
• SUBMAIL_SECRET is tied to encrypted data. Back it up separately and never rotate it casually after storing credentials.

Please report vulnerabilities privately through GitHub Security Advisories. Read SECURITY.md before reporting.

Architecture

flowchart LR
  Browser["Browser"] --> Web["React + Vite / Nginx"]
  Agent["AI / MCP client"] --> MCP["MCP server"]
  Web --> API["Express API"]
  MCP --> API
  API --> DB["SQLite / MySQL"]
  API --> Queue["Memory / Redis + BullMQ"]
  API --> Mail["IMAP / POP3 / SMTP"]
  API --> Services["AI and translation providers"]

| Path | Responsibility | | --- | --- | | apps/web | React mail client and administration UI | | apps/api | Authentication, mail sync/send, storage, queueing, AI, translation, backup and restore | | apps/mcp | stdio and Streamable HTTP MCP transports | | scripts | Local secret hardening and real-provider integration checks | | tests | API, POP3, HTTP MCP, runtime-lock, and restore integration tests | | docs | Deployment operations and feature-gap documentation |

Current boundaries

• IMAP synchronizes INBOX plus discoverable Sent, Drafts, Junk/Spam, Trash, and Archive folders, including remote read/star flags. Gmail archives are derived from All Mail labels when available. POP3 can read INBOX only.
• Read, star, archive, and delete state is currently local and is not written back to IMAP.
• Gmail and Microsoft OAuth, DKIM signing, DSN bounce processing, and a queue dashboard are not implemented yet.
• SQLite and MySQL data are not automatically migrated between drivers.
• The default free Google translation path is best-effort and is not appropriate for confidential email or strict SLAs. Automatic translation is disabled by default because enabling it sends opened English email content to the configured provider.

The detailed implementation review and roadmap live in docs/gap-review.md.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md, keep changes focused, and include the relevant tests or rendered UI evidence.

Project status and licensing

Submail is an early-stage 0.1.x project. A project-wide license has not yet been selected because optional document-viewer dependencies include components with copyleft licenses. Public repository access does not grant redistribution rights until a LICENSE file is added; dependency licenses continue to apply independently.