DEV Community: Gabe

Receiving email is the part nobody warns you about

Gabe — Wed, 16 Sep 2026 12:47:24 +0000

If you're wiring email into an app for the first time, often to give an agent its own inbox, you just want the contents of the message and instead you hit MIME. The moment a feature needs the other direction (a reply that reopens a support ticket, an inbound attachment to process, an "email us your receipt" address, an agent that reads its own mail) you leave the paved road: you inherit arbitrary MIME produced by thirty years of mail clients that agree on nothing, and most providers hand you that swamp as an afterthought bolted onto their send product. Here is the full journey one received email takes before your app can touch it, and every stage in bold is work somebody has to own:

Stage	What happens	Who owns it
sender's MTA	opens an SMTP :25 connection	the sender
your MX edge	mail lands on your domain	you (or your provider)
parse the MIME tree	nested multipart, mixed encodings	the hard part
authenticate the sender	SPF / DKIM / DMARC vs a forged `From:`	the hard part
filter spam	score it, or drown in it	the hard part
deliver the webhook	HMAC-sign, then retry on failure	the hard part
your app	the contents of the email, at last	you

Every bold stage is work the options below make you own, in some combination. MailKite collapses them into one signed JSON webhook.

One inbound email's journey, top to bottom. The four bold stages (parse the MIME tree, authenticate the sender, filter spam, and deliver a signed and retried webhook) are the work every option below makes you own in some combination.

That whole stack collapses into one signed JSON webhook. Here's the entire message your app receives — already parsed, decoded, and authenticated — before any of the plumbing that gets there:

{
  "id": "msg_2Hk9…",
  "type": "email.received",
  "from": { "address": "ada@example.com" },
  "to": [{ "address": "support@myapp.ai" }],
  "subject": "Re: invoice #1042",
  "text": "Looks good — approved!",
  "html": "<p>Looks good — approved!</p>",
  "threadId": "<a1b2c3@mail.example.com>",
  "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "spam": "ham" },
  "attachments": [
    { "filename": "po.pdf", "contentType": "application/pdf", "size": 18213,
      "url": "https://api.mailkite.dev/att/2Hk9…?exp=…&sig=…" }
  ]
}

No MIME tree, no inline base64, no charset to guess, and the sender's SPF/DKIM/DMARC verdict is already attached. The rest of this post is why every other option makes you own those stages yourself.

Why inbound is the hard direction

When you send, you control the message. You build clean data, hand it to a library, and it produces well-formed MIME. When you receive, you inherit whatever twenty years of email clients, marketing tools, and someone's Exchange server from 2009 decided to emit. You don't get to reject it for being ugly. You have to parse it.

And real-world MIME is genuinely nasty:

It's a tree, not a string. A single email is multipart/alternative (text + HTML) wrapped in multipart/mixed (body + attachments), sometimes wrapped again for signatures. You walk the tree to find "the body."
Encodings everywhere. quoted-printable, base64, and charset labels that lie. The classic symptom: a £ or an emoji turns into Â£ because something decoded latin-1 bytes as UTF-8. Getting every part through decoding without corrupting the £ is fiddlier than it looks.
Attachments are inline base64 stuffed into the same payload, so a 10 MB PDF becomes a ~13 MB string you now have to pull apart, decode, and store.
Headers are trivially forged. From: is just text. Anyone can put anything there. Trust it and you've built a spoofing hole. You need SPF/DKIM/DMARC results to know if the sender is real, and computing those is its own project.

That first point is the one people underestimate. Here is what a single "plain" email actually is on the wire: a nested tree you walk to find one leaf.

Level	MIME part	What it is
root	`multipart/mixed`	the envelope around everything
├─	`multipart/alternative`	same body, two formats
│ ├─	`text/plain`	the body you actually want (the leaf you walk the tree to find)
│ └─	`text/html`	the same body, as markup
└─	`application/pdf`	base64 attachment, inline in the payload (a ~13 MB string)

A single "plain" email is a nested MIME tree. The body is one leaf you locate by walking it; the attachment rides inline as base64. Parsing this correctly, for every odd client that ever emitted mail, is the work an inbound API does so you don't.

We know precisely how nasty this gets, because we wrote the same MIME parser three times, in three languages, and the hard part was making them fail identically. None of this is your app's problem. It's plumbing. But it sits directly between you and the one thing you wanted: the contents of the email.

This isn't a niche gripe, either. The founder of Mailgun once described building the product specifically to eliminate MIME for developers, because of how much malformed, broken MIME arrives over SMTP. When the people who ran a mail company for a living call the format the enemy, believe them.

The incumbents each punt in a different way

Every existing option leaves you holding some version of the bag:

SendGrid Inbound Parse posts you multipart/form-data, a form upload, not JSON. You run a form parser, pull headers back out of string fields, and handle attachments as file parts. Developers hit the same walls repeatedly: undocumented payload shapes you reverse-engineer with test emails, attachments arriving corrupt or mislabeled, and the £-becomes-garbage encoding bug as a rite of passage. Worst of all, if your endpoint returns a 4xx or has a DNS hiccup, it drops the email immediately, with no retry.
Mailgun Routes exists because MIME is awful, but now you maintain a rule engine: match_recipient("support@myapp\.ai"), expression syntax you keep in sync with your app. Inbound also moved behind a paywall, and its convenience fields (like stripped body text) have a habit of quietly eating real message content.
Cloudflare Email Routing is a great edge and free, but there's no native parse-to-webhook. You write an Email Worker and parse the raw MIME yourself, inside a CPU budget that a big base64 attachment will blow through, against a 25 MB limit. It's a fine trigger/router; it is not a "parsed message as JSON" API. And it was built to forward, not to let your app reply.
Resend and other send-first tools added inbound, but the webhook is typically metadata-only: you get an event, then make a second API call to fetch the body and attachments. Two round-trips to read one email.
Self-hosting Postfix or Haraka lets you parse everything exactly how you want. You'll also inherit deliverability as a full-time job. Fresh VPS IPs start life on blocklists, and even flawless SPF/DKIM/DMARC lands you in spam often enough that the consensus from people who've done it is simply: don't.

Notice the shape. Every option makes you own the MIME parsing, own the retry/reliability story, make a second call, or own IP reputation, usually more than one. The "just receive an email" task quietly becomes: pick a lesser-evil vendor, learn its wrapper, re-implement decoding for the parts it botched, compute your own auth results, and figure out attachment storage. For a checkbox on a feature list.

What it should look like instead: one webhook, the whole message

We built MailKite's inbound as a first-class product, not a bolt-on. When mail arrives at any address on your domain, we parse the entire MIME tree at the edge (the same work you'd do by hand if you were parsing inbound email to JSON in Node) and POST you one webhook with the whole message already extracted as JSON:

{
  "id": "msg_2Hk9…",
  "type": "email.received",
  "from": { "address": "ada@example.com" },
  "to": [{ "address": "support@myapp.ai" }],
  "subject": "Re: invoice #1042",
  "text": "Looks good — approved!",
  "html": "<p>Looks good — approved!</p>",
  "threadId": "<a1b2c3@mail.example.com>",
  "auth": { "spf": "pass", "dkim": "pass", "dmarc": "pass", "spam": "ham" },
  "attachments": [
    {
      "filename": "po.pdf",
      "contentType": "application/pdf",
      "size": 18213,
      "url": "https://api.mailkite.dev/att/2Hk9…?exp=…&sig=…"
    }
  ]
}

Notice what's not there: no MIME tree, no inline base64 blob, no charset guessing. text and html are already decoded, the £ is a £. Attachments are pulled out and handed to you as a short-lived signed url you fetch on demand, so a 13 MB PDF never rides along in your webhook body. Threading is resolved. And auth tells you up front whether SPF, DKIM, and DMARC passed.

That last field matters more than it looks. The moment your app does something with an inbound email (files a ticket, sends a reply, hands it to an agent), a forged From: becomes an authorization decision. Having auth in the payload means you decide how much to trust the sender without computing it yourself or trusting blindly.

Receiving your first email

Point a domain at MailKite (add the MX record, verify), set a webhook URL, and inbound mail to any address on that domain gets parsed and POSTed to you. The whole handler is: verify the signature, then read the fields.

// Express
import express from "express";
import { MailKite } from "mailkite";

const SECRET = process.env.MAILKITE_WEBHOOK_SECRET;

// Capture the RAW body — verify the exact bytes, not a re-serialized object.
app.use("/hooks/mailkite", express.raw({ type: "application/json" }));

app.post("/hooks/mailkite", (req, res) => {
  // Recomputes the HMAC, compares in constant time, and rejects anything
  // outside the ±5-minute replay window.
  const sig = req.headers["x-mailkite-signature"];
  if (!MailKite.verifyWebhook(sig, req.body, SECRET)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(req.body);
  if (event.type === "email.received") {
    console.log("from", event.from.address, "·", event.subject);
    // event.text / event.html are already decoded.
    // …create a ticket, reply, store it, hand it to an agent.
  }

  res.sendStatus(200); // ack fast; do the heavy work out of band
});

app.listen(3000);

Two traps that cost real debugging hours. Verify the HMAC against the raw request bytes: round-tripping the JSON through parse and re-serialize changes the bytes and the signature never matches again. And ack fast: return 200 first, then do the slow work in a queue, or the sender's retry hands you a duplicate because your handler took nine seconds.

The full HMAC verification walkthrough covers the raw-bytes trap in depth. The same handler exists for Python, Ruby, Go, PHP, and Java; see the receiving docs and webhook security.

All of this runs on the free tier across unlimited domains: 5,000 messages a month with inbound and outbound sharing one quota, 200 emails/day, automatic retries, HMAC-signed payloads, and metered overage instead of a hard cutoff. That's enough to give every side project its own inbox before anything is riding on it.

FAQ

What's the hardest part of receiving email programmatically?
Parsing real-world MIME: emails are nested multipart trees with mixed encodings (quoted-printable, base64) and inline attachments, plus forgeable headers. Decoding all of that correctly, and computing SPF/DKIM/DMARC to know if the sender is genuine, is the work that surprises people. A good inbound API does it for you and hands you decoded text/html and an auth result.

Is SendGrid Inbound Parse the same as this?
It's the closest incumbent, but it POSTs multipart form data, is known to mangle certain encodings and attachments, and drops the message with no retry if your endpoint returns an error. Here the message arrives already fully parsed as JSON, and failed deliveries retry.

How do I stop someone from spoofing an inbound email?
Don't trust the From: header, it's plain text. Use the SPF/DKIM/DMARC results in the auth object to decide how much to trust the sender, and always verify the webhook signature so you know the request genuinely came from your provider and not an attacker POSTing to your endpoint.

Do attachments come inline in the webhook?
Not by default: a large base64 attachment inline bloats every webhook and can blow request-size limits. Each attachment arrives as a short-lived signed url you fetch on demand. (Zero-retention and encrypted domains are the exception: those receive attachment content inline as base64, since there's nothing stored to link to.)

Can Cloudflare Email Routing do this?
It gives you the raw message and leaves parsing to you inside a CPU-limited Worker, exactly where a big attachment will exhaust your budget. It's a fine trigger/router; it is not a "parsed message as JSON" API, and it can't reply from your domain.

Sending was never the hard part. Receiving is, and it's the direction behind support inboxes, reply-by-email, and agents that read their own mail. Point a domain at MailKite and receive your first parsed email in a few minutes.

Four deep dives sit under the hard parts above, one per stage of the pipeline:

Parse inbound email to JSON in Node — Walk the MIME tree by hand: decode every part, find the body, and hand your app clean JSON.
Verify inbound webhooks with HMAC — Recompute the signature over the raw bytes, compare in constant time, and reject replays.
Attachments without corrupting the £ — Why a £ turns into Â£, and how to move every byte through decoding intact.
One MIME parser, three languages — We wrote the same parser three times; the hard part was making them fail identically.

Related: You can't prompt your way out of prompt injection: how we designed an agent inbox that's ACL-gated by design, so a fooled agent still can't do damage.

Originally published at mailkite.dev on April 1, 2026.

I wrote the same email parser three times, and the hard part was making them fail identically

Gabe — Fri, 04 Sep 2026 19:17:01 +0000

@mailkite/mail-parse is MIT-licensed, and its test suite is really two conformance proofs stacked together. One implementation generates the truth; the other two are checked against it, once for the emails that parse and once for the emails that break. Here's both halves at a glance, before any of the code that makes them true:

Diagram. Two conformance proofs, one parser. Top: the TypeScript package generates parse_golden.json from 15 pathological fixtures; Python and Go assert field-for-field against it. Bottom: the same malformed email produces the byte-identical failure signature f55154fda8f2cadd in all three runtimes (a real captured hash from the parity tests), so it dedups to one bucket and one issue.

The reason any of this matters is that inbound email is a swamp. Not the protocol, the content. The moment you accept mail from the open internet you stop getting the tidy RFC 5322 messages from the spec and start getting whatever thirty years of mail clients, marketing tools, and misconfigured servers actually emit: base64 that isn't padded, a Content-Type charset that doesn't exist, boundaries that never close, winmail.dat, 8-bit bytes in a header that swears it's ASCII. A parser that runs on that input has to degrade well, not throw.

import { parse } from "@mailkite/mail-parse";

// bytes in: a Buffer/Uint8Array, a string, or any (async) iterable of chunks (a stream)
const msg = await parse(rawMimeBytes);

msg.from;        // { address, name? }
msg.subject;     // RFC 2047 decoded
msg.text;        // decoded text/plain
msg.attachments; // [{ filename, mimeType, content, size }]
msg.diagnostics; // typed, non-fatal degradations: it never throws on bad input

The same call, and the same Message shape, exists in the Python and Go ports.

Why three languages at all

The honest answer: the email doesn't get to pick where it lands.

Our inbound path parses raw MIME at the SMTP edge, a Node process on a plain VPS: no CPU cap, the natural home for streaming a 20 MB message straight to object storage without buffering it. But the same parsed-message shape also has to be producible inside a Cloudflare Worker (buffered, a different runtime), and the SDKs developers actually call live in a spread of languages.

If those parsers drift, you get the worst class of bug: an email that produces one JSON shape in the Node path and a subtly different one somewhere else. No stack trace. No crash. Just a support ticket that says "the attachment is missing" for one customer and no one else, with no way to reproduce it, because the email that triggered it is gone.

So "three languages" wasn't a flex. It was a constraint that forced a discipline: there is one parser, expressed three times, and I need a mechanical way to prove they're the same.

Making success identical: one golden, generated from the reference

The first half is conformance testing, and the trick is to have a single source of truth rather than three hand-written expectation sets that rot independently.

The TypeScript package is the reference implementation. A script runs it over the 15 gold .eml fixtures (the pathological ones, collected from real breakage) and serializes the full parsed result to a parse_golden.json: subject, from, recipient count, the text body, the HTML body, every attachment's metadata, and the sorted diagnostic codes.

Then Python and Go each assert field-for-field against that same file:

# tests/test_streaming.py — Python asserts against the TS-generated golden
def test_every_fixture_matches_ts(self):
    for path in sorted(glob.glob(os.path.join(FIXTURES, "*.eml"))):
        name = os.path.basename(path)
        g = self.golden[name]                       # the TS reference's output
        msg = parse(open(path, "rb").read())
        self.assertEqual(msg.subject, g["subject"], "subject")
        self.assertEqual(msg.from_.address if msg.from_ else None, g["from"], "from")
        self.assertEqual(len(msg.to), g["toCount"], "toCount")
        self.assertEqual(msg.text, g["text"], "text")
        self.assertEqual([a.filename for a in msg.attachments],
                         [a["filename"] for a in g["attachments"]], "attachments")
        self.assertEqual(sorted(d["code"] for d in msg.diagnostics),
                         g["diagnostics"], "diagnostics")   # the whole shape

// parse_test.go — the SAME golden JSON, asserted from Go
func TestTsParity(t *testing.T) {
    golden := loadGolden(t, "testdata/golden/parse_golden.json")
    for name, g := range golden {
        msg := Parse(readFixture(t, name))
        if strOrNil(msg.Subject) != strOrNil(g.Subject) {
            t.Errorf("%s subject: got %q want %q", name, strOrNil(msg.Subject), strOrNil(g.Subject))
        }
        // ...from, toCount, text, html, attachments, diagnostics — field-for-field over 15 fixtures
    }
}

The nice property: the golden is generated, not authored. When the reference parser's behavior changes, the golden regenerates, and the Python and Go tests fail until they match. There's no world where the three implementations silently diverge on a fixture and everyone's test suite stays green. The fixtures include TypeScript's exact 8-bit-header quirks, so "close enough" doesn't pass.

That covers the emails that parse. It's the emails that don't that taught me the real lesson.

Making failure identical: a fingerprint, not a stack trace

When a MIME parser hits something it can't cleanly handle, the naive move is to throw. That's wrong for inbound email for two reasons: one broken part shouldn't sink the whole message, and, more subtly, an exception is a terrible unit of aggregation. Ten thousand deployments hitting the same malformed-boundary bug should be one signal, not ten thousand log lines with slightly different byte offsets.

So the parser never throws on bad input. Every degradation emits a typed diagnostic, and the part worth showing you: a failure signature, a deterministic, PII-free hash of the structural features of what broke.

interface FailureFeatures {
  libVersion: string;
  scope: 'envelope' | 'structure' | 'part'; // header block? assembly? one leaf part?
  diagnosticCodes: string[];                 // e.g. ["BOUNDARY_NOT_CLOSED"], order-independent
  contentType?: string;                      // the offending leaf's declared type
  disposition?: string;
  transferEncoding?: string;
  byteSignature?: string;                    // hex of the leading bytes: STRUCTURE, never content
  headerNames?: string[];                    // header NAMES present, never their values
  mailerFamily?: string;                     // X-Mailer normalized, e.g. "outlook"
  structurePath?: string;                    // "multipart/mixed>multipart/alternative>application/ms-tnef"
}

interface FailureSignature {
  hash: string;                 // fnv1a64(canonicalize(features)): 16 hex chars, the dedup key
  features: FailureFeatures;
  rollup: SignatureRollup[];    // coarser hashes: "a whole scope is failing" vs a precise group
}

Notice what's not in there: no subject, no addresses, no body bytes. The signature describes the shape of a failure (a base64 attachment that won't decode, an HTML part with a bogus charset, a winmail.dat at a particular position in the tree) using only structural facts. That's what makes it safe to emit from a library running on other people's mail: the fingerprint can leave the box, the email never does.

Order is a cross-language hash trap. The same failure can surface its diagnostic codes in different orders across three runtimes, and casing or a stray ;charset= param can differ too. Canonicalize before you hash (sort the codes, lowercase the types, strip noisy params) or three identical failures fingerprint as three different bugs.

And because it's a pure hash of canonicalized structural features, the same broken email produces the same hash everywhere. That's the second conformance proof, the one that actually matters. The expected hashes are captured from the TypeScript computeSignature() and asserted verbatim in Python and Go:

# tests/test_signature.py — hashes captured from the TS reference, asserted in Python
def test_part_tnef_signature_matches_ts(self):
    sig = compute_signature({
        "scope": "part",
        "diagnosticCodes": ["BOUNDARY_NOT_CLOSED"],
        "contentType": "application/ms-tnef",   # a winmail.dat leaf
        "transferEncoding": "base64",
    })
    self.assertEqual(sig["hash"], "f55154fda8f2cadd")           # byte-identical FNV-1a-64
    scope = next(r for r in sig["rollup"] if r["level"] == "scope")
    self.assertEqual(scope["hash"], "c3c0a940c0ea88e6")         # and the coarser roll-up

I picked FNV-1a (the 64-bit variant, a 16-hex-char digest) deliberately: a handful of lines, no dependencies, trivially portable, so "compute this hash" means the same thing in three languages without pulling in a crypto library or hoping two implementations of something fancier agree on edge cases. The canonicalization is the real work (lowercase the types, strip noisy params, bucket byte-signatures to known magic numbers, reduce the mailer to a family, sort the codes so order doesn't matter); the hash is just the cheap, deterministic seal on top.

Diagram. The signature pipeline. Only structural facts enter the hash, never message content, so the fingerprint is safe to emit from a library running on other people's mail. The same features canonicalize and FNV-1a-64 hash to f55154fda8f2cadd in all three runtimes, with a coarser scope roll-up c3c0a940c0ea88e6. Both hashes are captured verbatim from the parity tests.

The payoff: a malformed email that breaks in the Node edge and the same email replayed through the Python SDK don't just both fail, they report the same signature, land in the same dedup bucket, and (once a threshold is crossed) file one GitHub issue with a structural description precise enough to write a regression test from. Cross-language observability falls out of cross-language determinism for free.

Where the off-the-shelf parsers fit (honest alternatives)

If you only live in one language and don't need the cross-runtime fingerprint, reach for the mature single-language option first:

Node: mailparser or postal-mime (we lean on postal-mime for our own Workers-side build).
Python: the capable email package in the standard library.
Go: net/mail plus mime/multipart for the structure.

Any of them will turn a well-formed message into fields with little or nothing to vendor.

What none of them give you is the thing this post is about: the same parsed shape and the same failure fingerprint across all three runtimes. That guarantee only earns its keep if, like us, you parse the same mail in more than one place and need a bug in one to be provably the same bug in the others. If you don't, a stdlib parser is the right call, and I'd tell you to use it.

The thing I'd tell past-me

Two lessons, both slightly counterintuitive:

Generate your conformance oracle; don't hand-write it per language. One reference implementation plus a generated golden beats three lovingly-maintained expectation files that drift the day you're not looking. The languages get to have different idioms internally (streams in Node, synchronous middleware in Python and Go) as long as they're forced through the same external truth.
Design your failures to be aggregatable, and you get portability and privacy as side effects. The instinct is to make errors rich: full context, the offending bytes, a stack trace. For a library that runs on data you're not allowed to see, the opposite is right: make errors structural and hashable. A PII-free fingerprint is the thing you can compare across languages, dedup across deployments, and safely emit from someone else's process. Determinism is what makes it identical across three parsers; structure-only is what makes it safe to emit at all.

The parser is MIT-licensed and lives here: Node/TS, Python, Go. It grew out of building MailKite, which we build (inbound email turned into a webhook), and that's where the appetite for "the same broken email must behave the same everywhere" came from. But the parser stands on its own: if you just need to turn MIME into clean, typed JSON without a service in the loop, take it and ignore the rest of us.

If you've fought the email-content swamp, I'd genuinely like to hear which message finally made you write your own parser. Mine was a winmail.dat inside a multipart/mixed that three off-the-shelf libraries each mangled a different way. In our signature scheme that failure has a name now: f55154fda8f2cadd. It's the same on all three parsers, and I'll never forget it.

Related: Receiving email is the part nobody warns you about on why the inbound content swamp is the hard direction, and Handling email attachments without losing the £ on the charset-and-encoding half of the same problem.

Originally published at mailkite.dev on June 24, 2026.

MailKite SMTP for WordPress is on WordPress.org

Gabe — Thu, 03 Sep 2026 02:04:34 +0000

Originally published on mailkite.dev. I build MailKite.

MailKite SMTP, the WordPress plugin we build, is now listed in the WordPress.org plugin directory. It replaces PHP mail() with delivery through MailKite, SendGrid, Brevo, Mailgun or any SMTP server, keeps a free email log, fails over automatically when a send fails, and receives email into WordPress. Version 0.4.2, GPL-2.0, free with no Pro tier.

Install it from Plugins → Add New (search "MailKite SMTP"), or from the command line:

wp plugin install mailkite-smtp --activate
wp mailkite test you@example.com

Listing: wordpress.org/plugins/mailkite-smtp. Source: github.com/mailkite/mailkite-smtp. Requires WordPress 6.2 and PHP 8.1.

What you can do now

Send through the provider you already have. MailKite, SendGrid, Brevo, Mailgun with your own API key, or any SMTP host. Routing rules send WooCommerce receipts through one mailer and newsletters through another, by subject or recipient.
Stop losing email silently. If an API send fails, the same message retries through your SMTP server or PHP mail, and the log entry says it fell back instead of reporting a success you did not get. Failure alerts go to email, Slack, Discord, or any webhook, rate-limited so an outage does not become an alert storm.
Read the log without paying for it. Every message, its status, the mailer that sent it, and the error verbatim when there was one. One-click resend of failures, CSV export, configurable retention. Most SMTP plugins put this behind a paid tier.
Receive email in WordPress. Turn inbound on in one click and replies, bounces, and out-of-office notices land in the log next to the message they answer. Reply from wp-admin, in-thread, from your own domain. Or forward everything to an address you already read.
Move over in one click from WP Mail SMTP, Easy WP SMTP, FluentSMTP, or Post SMTP. The importer reads their settings; you confirm and send a test.

Getting started

After activation, the settings screen shows one section per mailer and only the one you pick. Choosing MailKite creates an account from your email address if you do not have one, and the plugin picks up the API key from there. Choosing any other provider asks for its key or SMTP credentials, which are stored encrypted with a key derived from your wp-config salts.

The Send Test tab reports which mailer handled the message and the provider's error text when one comes back. The same check runs from WP-CLI:

wp mailkite status
wp mailkite test you@example.com
wp mailkite log

For automated provisioning, set MAILKITE_API_KEY and MAILKITE_DEFAULT_MAILER in wp-config.php and skip the settings screen entirely. Settings export and import (secrets excluded) cover the rest of a multi-site rollout. The WordPress setup guide walks through each mailer.

Inbound email fires a WordPress action

Every received message fires one hook. The plugin has already verified the webhook signature and stored the message before your code runs, so a handler is a few lines in functions.php:

// functions.php — runs for every inbound message the plugin receives.
// The plugin has already verified the signature and logged the mail.
add_action('mailkite_smtp_inbound', function (array $message) {
    // $message is the event payload: id, threadId, subject, text, html, attachments,
    // and from/to as objects — $message['from']['address'], not a plain string.
    $subject = $message['subject'] ?? '';
    $sender  = $message['from']['address'] ?? '';

    if (str_contains($subject, '[support]')) {
        wp_insert_post([
            'post_type'    => 'ticket',
            'post_title'   => $subject,
            'post_content' => $message['text'] ?? '',
            'post_status'  => 'publish',
            'meta_input'   => [
                'from'      => $sender,
                'thread_id' => $message['threadId'] ?? $message['id'] ?? '',
            ],
        ]);
    }
});

Turning inbound on registers the webhook and its signing secret on your MailKite domain from inside WordPress. There is no URL to copy and no secret to paste. The REST route rejects an unsigned request in its permission callback, before any handler code runs. Inbound needs a MailKite account with a verified domain; sending does not.

Logs that cannot leak a reset link

A stored email log is also a stored copy of every password-reset link your site ever sent. The plugin redacts the body of password-reset, login, and verification emails by default, so a leaked database or an over-shared log page contains the subject and the outcome but never the link. You can turn this off per site if you accept the risk.

Received mail that belongs to a user's personal mailbox (the companion MailKite Mailboxes plugin) never appears in the site-wide log. Ownership is part of the query in the log store, not a filter in the template, and every reader of the log tables goes through the store. That last part is what the 0.4.2 release fixed: the WordPress.org review found the REST log endpoint selecting the table directly and skipping the restriction, and auditing the other readers turned up the same omission in the WP-CLI listing, Site Health, and the weekly summary. All four now read through the store.

Three review rounds, one real bug

The listing took three rounds with the WordPress.org plugin review team. Rounds one and two were what a static scanner flags on any plugin that talks to an API: a hostname it could not resolve from a settings value, a permission callback it could not see through a shared variable, a prepared query assigned through a ternary. Each was restructured so the answer is visible on a read. Round three was the log-scoping bug above, which was real. The full history is in the repo's changelog.

What it costs

The plugin is free, GPL-2.0, and every feature in it is free: logs, failover, alerts, inbound, migration, WP-CLI. There is no Pro tier. It works fully with your own SMTP server or a SendGrid, Brevo, or Mailgun key and never requires a MailKite account. MailKite itself has a free plan and paid plans, and inbound email is the one feature that needs it, because someone has to run the MX.

Get started

The WordPress.org listing has the install and the FAQ, and the setup guide covers each mailer. Bugs and pull requests go to github.com/mailkite/mailkite-smtp.

23 open source email servers for Linux, sorted by the job each one does

Gabe — Wed, 05 Aug 2026 00:00:00 +0000

Most "best open source mail server" lists put a full-stack Docker bundle and a single SMTP daemon in the same ranked table, as if you'd choose between them. You wouldn't. This is 23 Linux mail projects grouped by the slot they fill in the mail path, with licenses, languages, and activity verified on 2026-08-05, plus the part every roundup skips: what self-hosting still costs you after the install script says done.

Start with the slots, not the projects. A mail server is five distinct jobs wearing one
name, and every project below fills one, some, or all of them. Once you know which slot
you're shopping for, the list stops being a popularity contest and turns into about three
real candidates.

Whichever you install, the acceptance test is the same three commands, and it is worth
running them before you read another word of documentation. Two of them check the server.
The third checks the thing that actually decides whether your mail arrives.

# 1. does it accept mail on :25 for a domain it claims to own?
swaks --to you@example.com --server mail.example.com:25 --tls

# 2. does it serve that mailbox back over IMAP with a real cert?
openssl s_client -connect mail.example.com:993 -quiet -crlf <<'EOF'
a login you@example.com hunter2
a list "" "*"
a logout
EOF

# 3. does your sending IP have reverse DNS that matches your HELO name?
dig +short -x "$(curl -s https://ifconfig.me)"

Command 3 is not part of any project's install script, and it is the one that fails. An
IP with no PTR record, or a PTR that doesn't match the name your server announces in
EHLO, gets your mail filed as spam by Gmail and Outlook no matter which of these 23
projects is behind it.

Everything below was checked against each project's repository on 2026-08-05: license
from the actual LICENSE file, language, star count, and the date of the last commit.
Star counts are a proxy for attention, not quality, and I've said so where the two
diverge.

The MTAs: they move mail and nothing else

An MTA speaks SMTP. It accepts a message on port 25, decides whether to take it, and
either drops it into a local store or queues it for delivery elsewhere. It does not serve
you a mailbox, filter spam, or render a web UI. Three of the four below have been doing
this since before most of us had email addresses, which is the point: they are the least
surprising software in your stack.

Postfix

The default answer, and usually the right one. C, dual-licensed under
EPL-2.0 or IPL-1.0 since 3.2.5, written by Wietse Venema as
a security-first replacement for Sendmail. Its architecture is a set of small processes
with narrow privileges talking over pipes, which is why its CVE history is as quiet as it
is. Nearly every bundle further down this page is Postfix plus a wrapper. Configuration
is a flat main.cf of key-value pairs, and it's readable, but the map/transport/restriction
vocabulary takes a weekend to learn properly.

Exim

C, GPL-2.0-or-later, stable at 4.99.5 as of 2026-07-22. The Debian default for years and
the engine behind most cPanel hosts. Exim's distinguishing feature is a genuinely
programmable configuration language with string expansions, routers, and transports, so
you can express routing logic in the config that would need a plugin elsewhere. That
power has a cost: Exim has shipped several remote-code-execution CVEs where Postfix
shipped none, largely because more of the message path runs in one privileged process.
Pick it when you need its routing expressiveness, and subscribe to the security list.

OpenSMTPD

C, ISC license, from the OpenBSD project. The configuration file is the pitch: a working
mail server in about six lines, with a grammar closer to pf than to main.cf. It is
audited to OpenBSD standards and deliberately implements a subset of SMTP rather than all
of it. If you run OpenBSD, or you want the smallest correct thing that can accept mail,
this is the one. Portable builds for Linux exist and are maintained, though they lag the
OpenBSD release.

chasquid

Go, Apache-2.0, 978 stars, last commit
2026-06-07. Written for small personal servers by one maintainer who kept it small on
purpose: SMTP in, SMTP out, hooks for aliases and spam filtering, no store of its own.
It is the modern-language equivalent of OpenSMTPD's philosophy, and it pairs with Dovecot
the same way. A single-maintainer project is a real risk to weigh, but the codebase is
small enough that you could read all of it in an afternoon.

The all-in-one servers: the whole path in one binary

These replace the classic Postfix-plus-Dovecot-plus-Rspamd assembly with a single
process. It's a genuine architectural argument, not just packaging: one config file, one
set of credentials, one thing to upgrade, and no gluing an MTA's idea of a user to an
IMAP server's idea of a user. The trade is that you are betting on a younger codebase in
the position where the old ones have thirty years of hostile-internet exposure.

Stalwart

Rust, dual-licensed AGPL-3.0 and a commercial Enterprise license,
14,017 stars, last commit 2026-08-03. The most
protocol-complete project on this page: SMTP, IMAP4, JMAP, POP3, CalDAV, CardDAV, and
WebDAV in one server, with built-in spam filtering, DKIM/ARC signing, and full-text
search. JMAP support in particular is close to unique here. It's also the most actively
developed, which cuts both ways: features land fast, and the config surface has changed
between minor versions. Read the upgrade notes before you apt upgrade.

mox

Go, MIT, 5,768 stars, last commit 2026-08-02. mox's design
goal is that a competent person can run a personal mail server without becoming a mail
administrator. One binary, a quickstart command that generates your DNS records and
systemd unit, and sane defaults for SPF, DKIM, DMARC, MTA-STS, DANE, and TLSRPT out of
the box. It ships DANE and MTA-STS support that several older projects still don't. If
you want one domain, a handful of mailboxes, and to stop thinking about it, mox is the
shortest honest path.

maddy

Go, GPL-3.0, 6,055 stars, last commit 2026-07-24. The
selling point is composability: maddy models the mail path as pipelines of modules you
wire in its config, so you can swap the storage backend or the auth source without
swapping servers. It hits a nice middle ground between "one opinionated binary" and "six
daemons and a socket map." Development is steadier than fast, which for mail software is
not the worst property.

The bundles: the classics, assembled

These aren't servers. They're curated stacks (usually Postfix, Dovecot, Rspamd, and a
webmail) plus provisioning, TLS automation, and an admin UI. You get a working mail host
in an afternoon and inherit whatever opinions the maintainers baked in. That is a fair
trade for most people, as long as you know you're now debugging the wrapper as well as
the components.

docker-mailserver

Shell, MIT, 18,661 stars, last
commit 2026-08-03. A single container with Postfix, Dovecot, Rspamd, ClamAV, and Fail2ban,
configured by env vars and a setup CLI. No database and no admin web UI on purpose:
accounts live in a flat file, and the project treats "no persistent state we manage" as a
feature. The most popular project on this page by stars, and the easiest to reason about
when it breaks, because it's just the classics in a box.

mailcow: dockerized

GPL-3.0, 13,229 stars, last commit
2026-08-04. The opposite bet: a full docker-compose stack (Postfix, Dovecot, Rspamd,
SOGo, Nginx, MariaDB, Redis) with a polished admin panel, per-domain quotas, ActiveSync,
and calendars and contacts through SOGo. If you're replacing a small-business Exchange or
Google Workspace and non-engineers will use the admin UI, this is the strongest option
here. Budget the RAM: a dozen containers is not a $5 VPS workload.

Mail-in-a-Box

Python, CC0-1.0 (public domain), 15,377 stars,
last commit 2026-05-24. One setup script turns a clean Ubuntu box into mail, webmail,
contacts, calendar, DNS, and a status console that tells you exactly which DNS records
are wrong. Explicitly designed for one box, one owner, no customization, and it says so:
deviate from the supported layout and upgrades will fight you. The slowest commit cadence
in this group, which reflects a project that considers itself finished more than one that
is stalled.

Mailu

Python, MIT, 7,421 stars, last commit 2026-07-27.
Docker-compose stack in the mailcow tradition, with a lighter footprint and a Kubernetes
path that actually works. Web admin, optional webmail, per-user filters. A good middle
choice if mailcow feels heavy and docker-mailserver feels too bare.

iRedMail

Shell, GPL-3.0, 1,834 stars, last commit
2026-07-22. Installs the classic stack straight onto the host (no containers) across
several Linux and BSD distributions, backed by OpenLDAP, MySQL, or PostgreSQL. The
open-source edition is complete; the good admin panel is the paid iRedAdmin-Pro, which is
worth knowing before you plan around it. Choose it when you want packages on metal and an
LDAP directory rather than a compose file.

Modoboa

Python (Django), ISC, 3,528 stars, last commit
2026-08-04. Not a mail server: a management layer over Postfix and Dovecot, with domain
and mailbox admin, per-user DNS record checks, a calendar, and a REST API. Reach for it
when you already run the classics and the thing you're actually missing is a control
panel with an API you can automate against.

The programmable ones: mail as an event in your application

This is the category that behaves differently from everything above. The projects here
assume the recipient is not a human with a mail client but a program: a support tool that
turns replies into tickets, a CI system that accepts commands by email, an AI agent with
its own address. What you want from a mail server in that case is not a mailbox. It's a
well-formed event delivered to your code, with the MIME already parsed and the
authentication already checked.

Haraka

JavaScript, MIT, 5,613 stars, last commit 2026-08-04.
A high-performance SMTP server built as a plugin bus: every phase of the SMTP conversation
(connect, mail, rcpt, data_post) is an event you can hook in JavaScript, so you
can reject a recipient with a live database lookup or hand the parsed message to your own
code. It is the most flexible way to put application logic inside the SMTP conversation
itself, and it's what we run as our own MX edge. It gives you a programmable SMTP server,
not a finished product: storage, auth, retries, and the web UI are yours.

WildDuck

JavaScript, EUPL-1.2, 2,106 stars, last commit
2026-08-04. An IMAP and POP3 server that stores mail in MongoDB instead of on a
filesystem, so mailboxes replicate and shard the way the rest of your infrastructure
does, with no local state on the mail nodes. It also exposes a full REST API over
mailboxes, which is unusual and useful. The right pick when you're building a mail
product for many users rather than hosting mail for a company.

ZoneMTA

JavaScript, EUPL-1.2, 668 stars, last commit
2026-07-20. Outbound only, and specialized: named delivery zones let you bind different
traffic to different IPs, so transactional mail and bulk mail stop sharing a reputation.
Per-zone throttling, connection pooling, and hooks for rewriting messages in flight. Low
star count for how good it is at its one job.

Postal

Ruby, MIT, 16,719 stars, last commit
2026-08-03. The self-hosted answer to SendGrid or Mailgun: a full sending platform with
an HTTP send API, per-organization credentials, click and open tracking, bounce
processing, suppression lists, inbound routes that POST to a URL, and a real dashboard.
If your requirement reads "we need a transactional email API but the data has to stay on
our infrastructure," Postal is the closest open-source match. It expects MariaDB, RabbitMQ,
and someone to keep them alive.

MailKite Server

JavaScript (Node ≥ 22.5), AGPL-3.0, github.com/mailkite/server,
v0.5.0, first public release 2026-08-01. This is ours, and it exists because of a specific
gap in the list above: the programmable projects each solve one slot well (Haraka the SMTP
conversation, WildDuck the store, Postal the sending platform), and an application that
wants to receive mail has to assemble three of them plus the parsing, the signing, and
the retry logic.

MailKite Server is that assembly, built so that every protocol daemon is stateless and all
state sits behind one small HTTP contract: five IMAP read endpoints, an inbound ingest
hook, an SMTP auth check, and a relay endpoint
(docs/contract.md). The
bundled zero-dependency SQLite backend and MailKite Cloud are two implementations of the
same contract, so the Haraka MX edge, the submission edge, the IMAP head, and the web
console run unchanged against either. One MX edge can serve several backends at once,
routing each recipient domain to its owner.

git clone https://github.com/mailkite/server && cd server
docker compose up -d           # backend + web console on :8787
docker compose --profile edges up -d   # adds the MX edge on :25

Mail that arrives is POSTed to your app as parsed JSON, signed with an
x-mailkite-signature: t=<unix>,v1=<hex> header. Verifying it is one call from the SDK,
and because the self-hosted server and the hosted service sign identically, the same
handler works against both:

import { MailKite } from "mailkite";

export async function POST(req) {
  const raw = await req.text();
  const ok = MailKite.verifyWebhook(
    req.headers.get("x-mailkite-signature"),
    raw,
    process.env.MAILKITE_WEBHOOK_SECRET,
  );
  if (!ok) return new Response("bad signature", { status: 401 });

  const { from, subject, text, attachments } = JSON.parse(raw);
  await handleIncomingEmail({ from, subject, text, attachments });
  return Response.json({ status: "ok" });
}

Honest scope: it's pre-1.0, the SMTP and IMAP edges run our production mail but the SQLite
backend and console are new, and it is not a groupware server. If you want mailboxes for
humans with calendars and contacts, mailcow or Stalwart is a better fit and it isn't
close. If you want an application (or an AI agent) to own an address and react to mail as
an event, this is the shape we think that should take, and you can run the whole thing
yourself. MailKite Cloud, which we build and which pays for this
work, is the same contract with the deliverability and retention handled; the DIY path
above is deliberately complete so you never need it.

The supporting cast

Three projects that aren't mail servers but appear in almost every deployment on this
page.

Dovecot

C, LGPL-2.1 with MIT-licensed parts, 1,233 stars on the
core repo, last commit 2026-08-04. The IMAP and POP3 server that nearly every bundle here
ships. Its Sieve implementation handles server-side filtering, and its LMTP and auth
services are what Postfix hands mail to. The low star count is an artifact of a project
that predates GitHub as a center of gravity, not a measure of use.

Rspamd

C, Apache-2.0, 2,501 stars, last commit 2026-08-04.
The spam filter that replaced SpamAssassin nearly everywhere: fast, with Bayesian
classification, fuzzy hashing, greylisting, reputation tracking, and DKIM/ARC signing
built in. It also handles the signing side of DMARC alignment, so it often does more than
filtering in a modern stack. If you already run Postfix and your only problem is spam,
adding Rspamd is a smaller change than replacing your server.

Roundcube

PHP, GPL-3.0, 7,114 stars, last commit
2026-07-25. The webmail your users will actually see, sitting on top of whatever IMAP
server you chose. Roundcube Elastic is the modern responsive skin, and the plugin API
covers most of what people ask for. SOGo (bundled in mailcow) is the alternative when you
need calendars and ActiveSync alongside mail.

If what you want is a newsletter, not a mail server

Two projects worth naming because people land on mail-server roundups when this is what
they actually need. Neither speaks SMTP to the internet on its own; both hand mail to
something that does (Postfix, SES, or any relay).

listmonk (22,624 stars, Go, AGPL-3.0, last commit
2026-08-03) is a single self-contained binary plus Postgres: subscriber lists, campaign
templating, per-campaign analytics, and a fast admin UI. The highest star count on this
page.

Keila (2,180 stars, Elixir, AGPL-3.0, last
commit 2026-08-01) covers the same ground with a friendlier editor and a GDPR-first
posture, which is why it shows up in European deployments.

Every project, one table

Verified 2026-08-05. Stars are rounded; "last commit" is the most recent push to the
default branch.

Project	Slot	Language	License	Stars	Last commit
Postfix	MTA	C	EPL-2.0 / IPL-1.0	n/a	active
Exim	MTA	C	GPL-2.0-or-later	n/a	4.99.5, 2026-07-22
OpenSMTPD	MTA	C	ISC	n/a	active
chasquid	MTA	Go	Apache-2.0	1.0k	2026-06-07
Stalwart	all-in-one	Rust	AGPL-3.0 / commercial	14.0k	2026-08-03
mox	all-in-one	Go	MIT	5.8k	2026-08-02
maddy	all-in-one	Go	GPL-3.0	6.1k	2026-07-24
docker-mailserver	bundle	Shell	MIT	18.7k	2026-08-03
mailcow	bundle	Shell / JS	GPL-3.0	13.2k	2026-08-04
Mail-in-a-Box	bundle	Python	CC0-1.0	15.4k	2026-05-24
Mailu	bundle	Python	MIT	7.4k	2026-07-27
iRedMail	bundle	Shell	GPL-3.0	1.8k	2026-07-22
Modoboa	admin layer	Python	ISC	3.5k	2026-08-04
Haraka	programmable SMTP	JavaScript	MIT	5.6k	2026-08-04
WildDuck	IMAP + store	JavaScript	EUPL-1.2	2.1k	2026-08-04
ZoneMTA	outbound MTA	JavaScript	EUPL-1.2	0.7k	2026-07-20
Postal	sending platform	Ruby	MIT	16.7k	2026-08-03
MailKite Server	app / agent mail	JavaScript	AGPL-3.0	new	2026-08-04
Dovecot	IMAP + store	C	LGPL-2.1 / MIT	1.2k	2026-08-04
Rspamd	filter	C	Apache-2.0	2.5k	2026-08-04
Roundcube	webmail	PHP	GPL-3.0	7.1k	2026-07-25
listmonk	newsletter	Go	AGPL-3.0	22.6k	2026-08-03
Keila	newsletter	Elixir	AGPL-3.0	2.2k	2026-08-01

What none of them fix

Every project on this list will accept mail on port 25 within an hour. None of them can
make anyone else accept mail from you, and that is where self-hosted email actually goes
wrong. Four things decide it, and all four are outside the software:

Port 25 is blocked on most residential ISPs and on several cloud providers by default. Check before you build. Some providers unblock on request, others never will.
Your IP has a history you didn't write. Cloud IPs get recycled. A fresh instance can arrive already on a blocklist because of whoever had it in March, and no amount of correct configuration overrides that.
PTR records live at your hosting provider, not in your DNS zone, and they must match the hostname your server announces. This is command 3 at the top of this page, and it's the single most common miss.
Warming is real for volume. Sending a thousand messages on day one from a new IP is the behavior of a spammer, and receivers model it that way.

None of this argues against self-hosting. It argues for being honest about the job: the
install is an afternoon, the reputation is a practice. A common and entirely reasonable
split is to receive on your own server, where reputation doesn't matter much, and relay
outbound through a service whose IPs are already warm.

How to pick

The decision is almost never "which is best." It's "which sentence sounds like me."

If you're still undecided after that, the default that disappoints the fewest people is
mailcow for human mailboxes and Postfix plus Dovecot plus Rspamd for anything you intend
to operate for a decade. Both are boring in the way infrastructure should be.

And if you got here because an application of yours needs to receive email rather than
host it, that's a different problem with a different shape, which is
why we open-sourced our answer to it.

Originally published at mailkite.dev. I'm Gabe; I build MailKite, and MailKite Server (AGPL-3.0) is #18 on the list above.