An open-source, programmable mail server for apps and AI agents. Haraka SMTP (MX + submission) and a thin IMAP head, wrapped around one small HTTP backend contract. Run the whole thing on your own box.
git clone https://github.com/mailkite/server && cd server
cp .env.example .env # then set HMAC_SECRET: openssl rand -hex 32
docker compose up -d # backend + web console on http://localhost:8787That is the whole install: a Node + SQLite backend, a React console, and a bearer-token API
on POST /v1/send / GET /api/messages. No account, no key, no cloud dependency.
Add the SMTP edge when you want inbound mail — this is the part that needs a public IP, port 25, a PTR record and TLS material:
docker compose --profile edges up # + Haraka MX on :25Prebuilt images publish to ghcr.io/mailkite/server from the release tags, so you can skip
the build entirely:
docker run -d -p 8787:8787 -e HMAC_SECRET=$(openssl rand -hex 32) \
-v mail-data:/data ghcr.io/mailkite/server:v0.5.0Point an existing Resend-style SDK at your own base URL and it works unchanged.
| Component | What it is |
|---|---|
mta/ |
Inbound MX edge — Haraka + plugins that POST accepted mail to your backend as a webhook, with live anti-open-relay recipient checks |
mta-submit/ |
Submission edge (587/465) — authenticated send with DKIM signing, relayed through your backend |
imap/ |
IMAP4 head (993, implicit TLS) — a stateless protocol daemon on imap-core; all storage lives behind the backend contract |
api-local/ |
Reference REST API: Node + SQLite + file blobs implementing the contract below — zero npm dependencies. Inbound webhooks with signing + retries, routes, smarthost outbound, and the developer API |
ui/ |
Web console for domains, DNS records, message log, routes, webhooks, and credentials — magic-link sign-in, pluggable providers |
Past "store it and expose it over IMAP", an address can carry a rule
(docs/routes.md): POST it to a webhook, forward it somewhere, or
hand it to an AI agent that replies or escalates. Matching fans out, so one message can
do all three.
Agent routes are bring-your-own-key — Anthropic, Gemini, OpenAI, OpenRouter, Groq,
Mistral, Together, xAI, DeepSeek, or any OpenAI-compatible endpoint including a local
Ollama/vLLM. Your key is encrypted at rest and only ever leaves for the provider you named;
no dependency and no MailKite account is involved. The agent runs deliberately
narrow — it can reply to the sender or forward to an address you nominated, and nothing
else — because the mail it reads is attacker-controlled input. See
docs/routes.md §5 for the threat model and the one known gap (no
per-route rate cap yet).
Every component is a dumb protocol head. State lives behind a handful of HMAC-authenticated
HTTP endpoints (/api/imap/{auth,status,list,flags,raw}, an inbound ingest hook, and a
submission inject endpoint). Implement that contract over any store and every edge here
works unchanged — the reference SQLite backend is just the default implementation of it.
One MX edge can even serve several backends at once, routing each recipient domain to
its owner — see docs/multi-backend.md.
Opt in with config/backends.json (example: mta/config/backends.example.json); without
it the edge is single-backend.
See docs/contract.md and docs/app-passwords.md
(mailbox credentials: one domain, an address pattern, IMAP and/or API access); the
conformance suite in api-local/test/ is its executable form, and scripts/e2e-imap.mjs
proves the full stack (signed ingest → backend → the real IMAP daemon → a TLS IMAP client).
Runs on any Node ≥ 22.5 host — VPS (systemd), Docker, Fly.io, Railway. Serverless (Workers/Vercel) is intentionally out of scope: those runtimes can't hold SQLite state or raw-TCP mail ports.
- Docker:
compose.yaml—docker compose up -d;--profile edgesadds the MX edge - Fly.io:
deploy/fly.md· Railway:deploy/railway.md - Bare VPS (full mail stack incl. IMAP/submission):
docs/self-hosting.md— DNS records, TLS provisioning, and systemd units. Short version: one VPS, three daemons, your backend URL in one env var.
| Doc | Read it when |
|---|---|
docs/self-hosting.md |
Running the full stack on a VPS — DNS, TLS, systemd |
docs/contract.md |
Writing your own backend instead of using api-local |
docs/routes.md |
Wiring webhook, forward, or AI-agent rules to an address |
docs/v1.md |
Calling the developer API (POST /v1/send) |
docs/multi-backend.md |
One MX serving several backends, one per domain |
docs/app-passwords.md |
Mailbox credentials for IMAP and API access |
docs/auth-setup.md |
Magic-link sign-in and OAuth for the console |
Pre-1.0, and deliberately honest about it. The SMTP and IMAP edges here carry MailKite's
production mail; the reference SQLite backend and web console are newer (first public
release 2026-08-01, now v0.5.0) and pass the conformance + end-to-end suites in CI. Where a
piece is unproven, docs/ says so rather than implying otherwise. The contract is
the stable part; the reference backend is the part still settling.
If you would rather not run mail infrastructure — DNS, PTR, TLS renewal, deliverability, retention — MailKite Cloud is the hosted backend and dashboard. It consumes this same repository as a pinned submodule, so self-hosted and hosted stay in lockstep. It is an option, not a dependency: nothing here requires an account.
Code is licensed under AGPL-3.0-only — see LICENSE.
The MailKite name and logo are not covered by the code license; see
TRADEMARK.md and brand-assets/. Forks must use their
own name and branding.
Contributions require a signed CLA — see CONTRIBUTING.md.
