DEV Community

Brown Connie
Brown Connie

Posted on

Writing an SMTP server in Node.js with zero dependencies

A disposable email service needs to receive mail. There is no stdlib SMTP server in Node, and the npm options (smtp-server, mailparser) are fine — but I wanted zero dependencies, so I wrote the SMTP side myself. Here is the whole thing, reduced to what actually matters.

The protocol is a line-based conversation

SMTP is text. The client sends commands, one per line, and the server answers with a three-digit code plus a human-readable message. A minimal receive-only session looks like:

← 220 mx.example.com ESMTP
→ EHLO client.example.com
← 250-mx.example.com
← 250 SIZE 10485760
→ MAIL FROM:<alice@example.com>
← 250 OK
→ RCPT TO:<random@example.com>
← 250 OK
→ DATA
← 354 End data with <CR><LF>.<CR><LF>
→ Subject: hello
→ body text
→ .
← 250 OK queued
→ QUIT
← 221 Bye
Enter fullscreen mode Exit fullscreen mode

That is the entire happy path. The state machine is: IDLE → greeted → mailFrom → rcptTo → data → done. Each command is allowed only in the right state; anything else gets 503 Bad sequence of commands.

Reading lines correctly

The trap: sockets do not deliver lines, they deliver chunks. You buffer bytes and split on \r\n. Bare \n shows up in the wild too, so tolerate both.

let buf = '';
sock.on('data', (chunk) => {
  buf += chunk.toString('utf8');
  let i;
  while ((i = buf.indexOf('\r\n')) >= 0) {
    const line = buf.slice(0, i);
    buf = buf.slice(i + 2);
    handleLine(line.trimEnd());
  }
});
Enter fullscreen mode Exit fullscreen mode

When the client switches to data mode, stop parsing lines as commands: everything until a line containing only . is the message body.

Dot-stuffing

A message body may contain lines starting with .. The client prefixes such lines with an extra dot, and the server removes one dot from any line starting with a dot. Skip this and mail containing a line like ".bye" gets corrupted.

Size limits are not optional

Without a cap, one client can POST you a 20 GB message. Advertise SIZE 10485760, count bytes as they arrive, reply 552 mid-stream when exceeded, and cap line length (998 bytes per RFC 5321).

Parsing the message

A raw email is headers, a blank line, then the body. Headers can be folded (continuation starts with whitespace). Content-Type says whether the body is text/plain, text/html, or multipart with a boundary. Split multipart bodies on --boundary and decode each part's transfer encoding: quoted-printable (=XX), base64, or raw 8-bit. Decode =?UTF-8?B?...?= encoded words in the Subject.

What I skipped (deliberately)

  • TLS. Transactional senders increasingly require STARTTLS; running plaintext SMTP behind Postfix on localhost is fine, a public port 25 without it is not.
  • SPF/DKIM/DMARC verification. Inbound mail should be checked before delivery; that is a project of its own.
  • Queues and retries. This server accepts or refuses; no store-and-forward.

The point was not to rebuild Postfix — it was to accept mail from a local relay, parse it, and put it in SQLite in a few hundred lines with zero dependencies.

The result

The whole service — SMTP receiver, MIME parser, SQLite inboxes, web UI — is one Node.js file. If you want to see what it looks like end to end: https://howtageek.com. The architecture write-up is here: I built a disposable email service that runs on one Node.js file.

Questions about the SMTP corners (dot-stuffing, 8BITMIME, pipelining) are welcome in the comments — I hit most of them the hard way.

Top comments (0)