jcollie.dev / zig-smtp
An SMTP client and server library for Zig implementing RFC 5321.
0
Fork 0

Configure Feed

Select the types of activity you want to include in your feed.

zig-smtp / README.md
41 kB 835 lines
1<!-- 2SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us> 3SPDX-License-Identifier: MIT 4--> 5 6# zig-smtp 7 8An SMTP client and server library for Zig (RFC 5321). 9 10Both the client and the server run over plain `std.Io.Reader`/`std.Io.Writer` 11pairs, so they are transport-agnostic: wrap a TCP stream for real use, or 12fixed in-memory buffers in tests. Requires Zig 0.16. 13 14## Where this lives 15 16The canonical repository is on Forgejo, with mirrors on Tangled and Radicle: 17 18- <https://git.jcollie.dev/jeff/zig-smtp> — issues and pull requests 19- <https://tangled.org/jcollie.dev/zig-smtp> 20 21```sh 22git clone https://git.jcollie.dev/jeff/smtp.git 23``` 24 25On [Radicle](https://radicle.xyz/), the peer-to-peer forge, the repository is 26`rad:z3ZKHgoDKEue8FT7sV6fHZdtjxRx1`, which is the only name it has there — a 27Radicle repository is found by its ID and nothing else — so seeding or cloning 28it goes: 29 30```sh 31rad clone rad:z3ZKHgoDKEue8FT7sV6fHZdtjxRx1 32``` 33 34Cloning also seeds the repository, which helps keep it available on the 35network. 36 37The API documentation is generated from the doc comments and published at 38<https://jeff.jcollie.page/zig-smtp/>; `zig build docs` builds it locally and 39`zig build docs-serve` serves it for reading. 40 41## Client 42 43```zig 44const smtp = @import("smtp"); 45 46var reply_buf: [1024]u8 = undefined; 47var client: smtp.Client = .init(&stream_reader.interface, &stream_writer.interface, &reply_buf); 48 49_ = try client.greet(); // read the 220 greeting 50_ = try client.hello("my-host.example.com"); // EHLO (HELO fallback), returns extensions 51try client.sendMail("me@example.com", &.{"you@example.net"}, message); 52try client.quit(); 53``` 54 55`Reply` carries more than three digits. `enhanced()` reads the 56`class.subject.detail` code RFC 3463 defines and 57[RFC 2034](https://datatracker.ietf.org/doc/html/rfc2034) puts at the front 58of the text, and `message()` gives the text without it: 59 60```zig 61const reply = client.last_reply.?; 62if (reply.enhanced()) |status| switch (status.subjectClass()) { 63 .addressing => {}, // 5.1.x — something about the address 64 .security => {}, // 5.7.x — policy, nothing to do with the address 65 else => {}, 66} 67``` 68 69`550` is "no"; `5.1.1` is "no, that mailbox does not exist" and `5.7.1` is 70"no, and not because of anything about the address". Check 71`status.agrees(reply.code)` before acting on it — a 250 carrying a 5.x.x 72code is a server contradicting itself. The greeting, the EHLO response and 73any 3xx carry no code, by RFC 2034's own exclusions, so `enhanced()` 74answers null there and is right to. 75 76Line endings in the message are normalized to CRLF and leading dots are 77stuffed automatically. On `error.UnexpectedReply`, `client.last_reply` holds 78the server's actual code and text. `mailFrom`/`rcptTo`/`sendMessage` are also 79available individually. 80 81Addresses and the EHLO domain are checked before they are written: a value 82containing CR, LF or NUL is rejected with `error.UnsafeArgument` rather than 83sent, since it would otherwise end the command line early and let the rest of 84it be read as further SMTP commands. The check is `protocol.isSafeArgument`, 85and it is framing only — it does not claim the address is a well-formed 86mailbox. 87 88Message bodies can also be streamed instead of passed as a slice — from any 89reader via `sendMessageReader(&reader)`, or push-style via `data()`, which 90returns a writer that dot-stuffs and normalizes line endings as content 91flows through it: 92 93```zig 94var data_writer = try client.data(); 95try data_writer.interface.print("Subject: report {d}\r\n\r\n", .{id}); 96// ... stream as much as needed ... 97try data_writer.end(); // terminates the message, reads the verdict 98``` 99 100`envelope` sends MAIL FROM and every RCPT TO at once and reads all their 101replies, which against a server advertising PIPELINING 102([RFC 2920](https://datatracker.ietf.org/doc/html/rfc2920)) turns an envelope 103of *n* recipients from *n*+1 round trips into one. `hello` sets 104`client.pipelining` from the EHLO response and `envelope` falls back to 105waiting for each reply when it is false, so the result is the same either 106way: 107 108```zig 109var codes: [3]u16 = undefined; 110const accepted = try client.envelope(from, recipients, &codes, .{}); 111// codes[i] is the RCPT reply code for recipients[i]. 112``` 113 114A refused recipient is not an error — with several of them the caller is the 115one who can say whether what remains is worth sending — so compare `accepted` 116against `recipients.len`. `sendMail` makes that decision the strict way: if 117any recipient was refused it sends RSET and returns `error.UnexpectedReply` 118without delivering to the others. 119 120DATA is deliberately left out of the group, though RFC 2920 allows it as the 121last command of one. Once a server has answered DATA with 354 the transaction 122is committed, and the only ways out are to send the message or to send an 123empty one to whichever recipients were accepted; stopping the group before 124DATA keeps that choice with the caller, and costs one round trip out of the 125*n*+1 saved. 126 127A relay carrying somebody else's mail names the original submitter with 128`AUTH=` ([RFC 4954 §5](https://datatracker.ietf.org/doc/html/rfc4954#section-5)): 129 130```zig 131try client.mail(from, .{ .auth = .{ .mailbox = "alice@example.com" } }); 132try client.mail(from, .{ .auth = .unknown }); // sends AUTH=<> 133``` 134 135`<>` is a claim of its own — "I considered the question and cannot vouch for 136anybody" — and RFC 4954 asks a relay to send it rather than leave the 137parameter off. On the receiving side it arrives as `Envelope.submitter`, and 138a server that advertises AUTH must accept the parameter *even from a client 139that has not authenticated*, then behave as though `<>` had been sent. So a 140`.mailbox` in an envelope always means an authenticated peer asserted it, and 141`Envelope.authenticated_as` says which peer, which is what a handler needs to 142decide whether to believe it. 143 144A sender that would rather have a message bounce than travel in the clear 145says so with REQUIRETLS 146([RFC 8689](https://datatracker.ietf.org/doc/html/rfc8689)): 147 148```zig 149try client.mail(from, .{ .require_tls = true }); 150``` 151 152It is refused with `error.InsecureTransport` on a session this client does 153not believe is encrypted, because a guarantee about an unprotected channel 154guarantees nothing. That is the precondition the library can check; the rest 155of §4.1's are the caller's and are not visible from here — the server's 156certificate must have been validated by a trust chain or DANE, so not with 157`Tls.Options.ca = .insecure`, and the MX must have been vouched for by 158DNSSEC or MTA-STS, which nothing here resolves. The demo CLI refuses 159`--requiretls` alongside `--insecure` for exactly that reason. 160 161`mail` and `rcpt` are the parameterized forms of `mailFrom` and `rcptTo`, 162carrying the ESMTP parameters the server advertised — today SMTPUTF8 and the 163DSN set of [RFC 3461](https://datatracker.ietf.org/doc/html/rfc3461): 164 165```zig 166try client.mail("me@example.com", .{ .ret = .hdrs, .envid = "batch 7" }); 167try client.rcpt("bob@example.net", .{ 168 .notify = .{ .on = .{ .failure = true, .delay = true } }, 169 .orcpt = .{ .addr_type = "rfc822", .address = "team@example.net" }, 170}); 171``` 172 173`ENVID` and the `ORCPT` address are xtext-encoded on the way out, so any 174bytes are safe to pass; the length limits RFC 3461 puts on the encoded form 175(100 and 500 characters) are checked and surface as 176`error.ArgumentTooLong`. Check `extensions.dsn` first — a conforming server 177answers an unrecognized parameter with 555. 178 179Setting `client.mode = .lmtp` before `hello` speaks LMTP: `LHLO` goes out in 180place of `EHLO`, and the end of a message brings back one verdict per 181accepted recipient, in the order the RCPT commands were issued. `endResults` 182is how to read them: 183 184```zig 185var data_writer = try client.data(); 186try data_writer.interface.writeAll(message); 187var verdicts = try data_writer.endResults(); 188while (try verdicts.next()) |reply| { 189 // verdicts.index counts the recipients as they are answered. 190 std.log.info("{s}: {d} {s}", .{ recipients[verdicts.index - 1], reply.code, reply.text }); 191} 192``` 193 194Every verdict must be read before the session is used again, or the next 195command is answered by a leftover reply. The simpler `end` reads them all 196and reports `error.RecipientRejected` if any was a refusal — without saying 197which, because the replies share one buffer and reading the next overwrites 198the previous. 199 200When the server advertises CHUNKING (`extensions.chunking`), `bdat` and 201`sendMessageChunked` transmit the message with length-framed BDAT chunks 202instead of DATA — verbatim, with no dot-stuffing, so text content must 203already use CRLF line endings. 204 205That framing is also what makes binary content possible. 206`mail(from, .{ .body = .binary_mime })` declares it 207([RFC 3030](https://datatracker.ietf.org/doc/html/rfc3030), needs 208`extensions.binary_mime`), after which the message may hold any octets at 209all — NULs, bare CR, a line that is nothing but a dot — and `data` refuses 210to open a DATA phase for it with `error.BinaryRequiresChunking`, which is 211the 503 the server would have sent, made one round trip earlier. RFC 3030 212is absolute that binary must not be sent to a server that did not advertise 213it, so check the capability first. 214 215### Authentication 216 217The mechanisms themselves live in 218[zig-sasl](https://git.jcollie.dev/jeff/zig-sasl), re-exported here as 219`smtp.sasl`, because nothing about PLAIN or CRAM-MD5 or XOAUTH2 is specific 220to SMTP — POP3 and IMAP want the same ones, and one implementation of each is 221better than three. What is specific to SMTP is `authenticate`: the `AUTH` 222command, the 334 challenges, the `*` that cancels, and the 235 that ends it. 223 224`hello` reports the server's advertised mechanism names in `extensions.auth`, 225exactly as it sent them, for `sasl.Client.selectFromList`: 226 227```zig 228var sasl_scratch: [smtp.Client.sasl_buffer_suggested]u8 = undefined; 229client.sasl_buffer = &sasl_scratch; 230 231var plain: smtp.sasl.Plain = .init("user", "password"); 232var cram: smtp.sasl.CramMd5 = .init("user", "password"); 233 234const extensions = try client.hello("my-host.example.com"); 235const mechanism = smtp.sasl.Client.selectFromList( 236 &.{ plain.client(), cram.client() }, // in order of preference 237 extensions.auth, 238 client.security == .encrypted, 239) orelse return error.NoSupportedMechanism; 240try client.authenticate(mechanism); 241``` 242 243The scratch buffer is the caller's, like `reply_buffer`: how much room a 244mechanism needs is the caller's to know, and the range is wide — the classic 245mechanisms want a few hundred bytes, an OAuth token several kilobytes. It is 246split four-to-three between base64 and plaintext, which is base64's expansion 247exactly, and the two halves take turns rather than coexisting: a challenge 248decodes into the coded half, the answer is written into the plain half, and 249that answer encodes back over the challenge. `sasl_buffer_min` is the floor 250and `sasl_buffer_suggested` fits everything short of an unusually fat token. 251`Server.Options.sasl_buffer` is the same arrangement on the other side. 252 253A 535 rejection surfaces as `error.AuthenticationFailed` with the reply in 254`last_reply`. 255 256PLAIN, LOGIN and the OAuth mechanisms put a credential on the wire that an 257eavesdropper could reuse — base64 is not encryption, and a bearer token is 258worth more than a password because it authorizes elsewhere too. The client 259refuses those unless `client.security` is `.encrypted`, returning 260`error.InsecureTransport` before anything is sent, and `selectFromList` 261skips them for the same reason: on a plaintext session the preference order 262above falls through PLAIN to CRAM-MD5, which sends a proof rather than the 263secret. 264 265The library is handed a reader and a writer and cannot see what is underneath 266them, so it assumes the worst: `setTransport` records the answer for a 267STARTTLS upgrade, and a session speaking TLS from the first byte sets 268`client.security = .encrypted` itself. For a connection protected by 269something the library cannot see — a unix socket, an SSH tunnel, a loopback 270test — `client.allow_cleartext_auth = true` permits them without claiming the 271transport is encrypted. 272 273One error is worth knowing about even if it never fires for PLAIN: 274`error.ServerNotAuthenticated` means the server reported success while the 275mechanism had not finished proving what it set out to prove. For a one-way 276mechanism that cannot happen. For SCRAM (via 277[zig-scram](https://git.jcollie.dev/jeff/zig-scram)'s `scram-sasl` module) it 278means the server never produced its own signature — which is what something 279in the middle, holding no verifier, would do. 280 281### TLS 282 283`smtp.Tls` wraps [ianic/tls.zig](https://github.com/ianic/tls.zig) and 284verifies against the system trust store by default (a caller-managed CA 285bundle and an insecure mode are also available). The stream reader/writer 286handed to it need buffers of at least `smtp.Tls.min_buffer_len` bytes, and 287`init` must run at the value's final address (the connection holds interior 288pointers). The standard library's TLS client is deliberately not used: it 289requires the optional TLS 1.3 middlebox-compatibility ChangeCipherSpec 290record, which servers like Exim disable. 291 292Implicit TLS (port 465) — handshake first, then speak SMTP: 293 294```zig 295var tls: smtp.Tls = undefined; 296try tls.init(io, gpa, &stream_reader.interface, &stream_writer.interface, .{ 297 .host = "smtp.example.com", 298}); 299defer tls.deinit(gpa); 300var client: smtp.Client = .init(tls.reader(), tls.writer(), &reply_buf); 301client.security = .encrypted; // the transport is TLS; `init` cannot tell 302// ... greet, hello, sendMail ... 303try client.quit(); 304try tls.end(); // close_notify, before closing the socket 305``` 306 307STARTTLS (port 587) — upgrade mid-session, then EHLO again: 308 309```zig 310_ = try client.greet(); 311_ = try client.hello("my-host.example.com"); // check .starttls in the result 312try client.starttls(); 313var tls: smtp.Tls = undefined; 314try tls.init(io, gpa, &stream_reader.interface, &stream_writer.interface, .{ 315 .host = "smtp.example.com", 316}); 317client.setTransport(tls.reader(), tls.writer(), .encrypted); 318_ = try client.hello("my-host.example.com"); // server state was reset 319``` 320 321## Server 322 323```zig 324var session: smtp.Server = .init(&stream_reader.interface, &stream_writer.interface, .{ 325 .context = &my_state, 326 .vtable = &.{ 327 .authenticate = onAuth, // optional; enables AUTH PLAIN and LOGIN 328 .rcptTo = onRcptTo, // optional; accept/reject each Recipient 329 .message = onMessage, // required; receives envelope + message data 330 }, 331}, .{ .hostname = "mx.example.com" }); 332try session.run(gpa); 333``` 334 335`Options.auth_mechanisms` is what the session offers for AUTH (RFC 4954), 336advertised by name in the EHLO response and drawn from 337[zig-sasl](https://git.jcollie.dev/jeff/zig-sasl) — so a server can offer 338CRAM-MD5 or EXTERNAL, which it could not when the mechanisms were built in: 339 340```zig 341const check: smtp.sasl.Server.PasswordCheck = .{ .context = &app, .verify = verify }; 342var plain: smtp.sasl.PlainServer = .init(check); 343var login: smtp.sasl.LoginServer = .init(check); 344// ... .auth_mechanisms = &.{ plain.server(), login.server() } 345``` 346 347**The mechanisms hold per-exchange state, so each session needs its own.** 348Sharing a set between two connections would have them overwrite each other's 349challenges; `Server.init` is per-connection anyway, so building them beside 350it is the natural place. 351 352Where the credential comes from is the mechanism's business, which is why 353there is no longer one callback for it. PLAIN and LOGIN share a 354`PasswordCheck` — asked whether a password is right and told nothing, so an 355application may store a hash — while CRAM-MD5 needs a `PasswordLookup`, 356because it has to compute the same HMAC the client did and therefore needs 357the password itself. That is the argument against offering CRAM-MD5 at all, 358and it is now visible in the types rather than buried. 359 360Whatever the mechanism reports as the authenticated identity reaches every 361`Envelope` as `authenticated_as`, which is what a handler deciding whether to 362relay wants — the envelope sender is whatever the client chose to write. 363 364Setting `Options.require_auth` rejects MAIL with 530 until the client has 365authenticated. 366 367Instead of `message` (which collects the whole body in memory, bounded by 368`max_message_size`), a handler can set `messageReader` to stream it: the 369callback receives an `Io.Reader` yielding the unstuffed message content, 370and anything left unread is drained by the session. 371 372`run` serves one connection until QUIT or disconnect, enforcing command 373sequencing, recipient and message-size limits, and un-stuffing message data. 374The commands it declines it declines precisely: `EXPN` is answered 502, 375"known and not implemented", where a verb it has never heard of gets 500; 376`VRFY` is answered 252, which is the compliant reply for a server that will 377not check an address in advance but will take the mail, and which 378[RFC 5321 §4.5.1](https://datatracker.ietf.org/doc/html/rfc5321#section-4.5.1) 379requires of it. 380Messages may also arrive via BDAT chunks (CHUNKING is advertised); both 381the collecting and streaming handler paths receive the reassembled content. 382MAIL parameters are validated: `SIZE=` (RFC 1870) is rejected early with 552 383when it exceeds `max_message_size`, `BODY=7BIT`/`BODY=8BITMIME` (RFC 6152) 384are accepted, and unrecognized parameters get 555; the declared size and 385body type reach the handler via `Envelope`. Listening, accepting, and 386concurrency are up to the caller. 387 388The server holds back the replies that RFC 2920 §3.2 permits — RSET, MAIL 389FROM and RCPT TO — so that a pipelined group is answered in one write, and 390sends everything pending the moment its input is empty. The condition is what 391makes that safe rather than a deadlock: a reply is only ever held while there 392is another command already waiting to be answered. 393 394Setting `Options.protocol = .lmtp` makes the session speak LMTP 395([RFC 2033](https://datatracker.ietf.org/doc/html/rfc2033)) instead: `LHLO` 396greets and `HELO`/`EHLO` are refused with 500, and the end of a message 397draws one reply per accepted recipient rather than one for the message — 398including a second reply for a recipient named twice. The `recipientResult` 399callback supplies each verdict: 400 401```zig 402fn onRecipientResult(ctx: ?*anyopaque, envelope: smtp.Server.Envelope, index: usize) smtp.Server.Decision { 403 return if (mailboxIsFull(envelope.recipients[index].address)) 404 .{ .reject = .{ .code = 452, .text = "4.2.2 Mailbox full" } } 405 else 406 .accept; 407} 408``` 409 410Without it every recipient is told the same thing, which is correct but 411gains nothing over SMTP. A message the handler rejected outright is reported 412as that rejection for each recipient, since it failed for all of them. LMTP 413is meant for the hop between a queueing MTA and whatever writes to mailboxes; 414RFC 2033 §5 forbids it on TCP port 25 and advises against wide-area use. 415 416BINARYMIME ([RFC 3030](https://datatracker.ietf.org/doc/html/rfc3030)) is 417advertised alongside CHUNKING, which the RFC requires of anything offering 418it. `BODY=BINARYMIME` arrives as `Envelope.body`, DATA for such a message is 419refused with 503, and the content reaches the handler exactly as it was 420sent — the BDAT path copies octets and has no line structure to normalize. 421 422`Options.requiretls` offers REQUIRETLS 423([RFC 8689](https://datatracker.ietf.org/doc/html/rfc8689)), and **setting 424it is a promise**. RFC 8689 requires a server advertising the keyword to 425honour the requirement, and a client that does not see it must quit and try 426another MX — refusing the domain entirely if no host offers it — so the 427keyword is load-bearing in a way most are not. This library cannot keep any 428part of that promise itself: it does not relay, so honouring the request is 429whatever the handler does with `Envelope.require_tls`. It is advertised only 430while the session is TLS-protected, and a client sending the parameter to a 431session that was not offered it gets 555 rather than being quietly 432disregarded — silently accepting it would turn a sender's refusal to be 433downgraded into a downgrade. 434 435DSN ([RFC 3461](https://datatracker.ietf.org/doc/html/rfc3461)) is 436advertised. `RET=` and `ENVID=` on MAIL arrive as `Envelope.ret` and 437`Envelope.envid`, and `NOTIFY=` and `ORCPT=` on RCPT arrive as 438`Recipient.notify` and `Recipient.orcpt` — at the `rcptTo` callback, which 439receives the whole `Recipient`, and again on the `Envelope` afterwards. The 440xtext values are decoded, the length limits enforced, and a malformed value 441answered with 501. Like everything else handed to a callback, those slices 442live only for the duration of the call; keep what you need by copying it. 443 444To advertise and accept STARTTLS (TLS 1.3, via 445[ianic/tls.zig](https://github.com/ianic/tls.zig)), pass a certificate key 446pair; the stream buffers must then be at least `smtp.tls.input_buffer_len` / 447`smtp.tls.output_buffer_len` bytes, since the handshake runs over them: 448 449```zig 450var auth: smtp.tls.config.CertKeyPair = 451 try .fromFilePath(gpa, io, .cwd(), "cert.pem", "key.pem"); 452defer auth.deinit(gpa); 453 454var session: smtp.Server = .init(&stream_reader.interface, &stream_writer.interface, handler, .{ 455 .hostname = "mx.example.com", 456 .tls = .{ .io = io, .auth = &auth }, 457}); 458try session.run(gpa); 459``` 460 461On STARTTLS the session answers 220, performs the server handshake, swaps 462its transport to the encrypted connection, and resets state per RFC 3207 (the 463client must EHLO again). With `.mode = .implicit` the handshake instead runs 464before the greeting (SMTPS, port 465 style): 465 466```zig 467var session: smtp.Server = .init(&stream_reader.interface, &stream_writer.interface, handler, .{ 468 .hostname = "mx.example.com", 469 .tls = .{ .io = io, .auth = &auth, .mode = .implicit }, 470}); 471``` 472 473## Demo CLI 474 475```sh 476zig build 477 478# Debug server that prints received messages to stdout 479# (with a cert/key pair it advertises and accepts STARTTLS): 480./zig-out/bin/zig-smtp serve 2525 481./zig-out/bin/zig-smtp serve --tls-cert cert.pem --tls-key key.pem 2525 482./zig-out/bin/zig-smtp serve --tls-cert cert.pem --tls-key key.pem --implicit-tls 2465 483 484# Send a message read from stdin: 485printf 'Subject: hi\r\n\r\nhello\r\n' | \ 486 ./zig-out/bin/zig-smtp send 127.0.0.1 2525 me@example.com you@example.net 487 488# Same, over implicit TLS or STARTTLS (--insecure skips cert verification): 489zig-smtp send --tls smtp.example.com 465 me@example.com you@example.net 490zig-smtp send --starttls smtp.example.com 587 me@example.com you@example.net 491 492# Send arbitrary binary content (RFC 3030), framed by BDAT rather than DATA: 493./zig-out/bin/zig-smtp send --binarymime 127.0.0.1 2525 me@example.com you@example.net \ 494 < some-binary-file 495 496# Speak LMTP (RFC 2033) instead of SMTP. The server reports one verdict per 497# recipient, and --fail-delivery makes one of them fail to show it: 498./zig-out/bin/zig-smtp serve --lmtp --fail-delivery bad@example.net 2529 499printf 'Subject: hi\r\n\r\nhello\r\n' | \ 500 ./zig-out/bin/zig-smtp send --lmtp 127.0.0.1 2529 me@example.com \ 501 good@example.net bad@example.net 502 503# Request a delivery status notification (RFC 3461): 504zig-smtp send --ret hdrs --envid 'batch 7' --notify success,failure \ 505 --orcpt team@example.net 127.0.0.1 2525 me@example.com you@example.net 506 507# Authenticate. Over a plaintext connection this refuses PLAIN and LOGIN 508# rather than put the password on the wire; --allow-cleartext-auth overrides 509# that for a connection protected by other means: 510zig-smtp send --starttls --user me --password secret smtp.example.com 587 \ 511 me@example.com you@example.net 512``` 513 514## Status 515 516TLS is supported on both sides via 517[ianic/tls.zig](https://github.com/ianic/tls.zig): the client does implicit 518TLS and STARTTLS via `smtp.Tls`, and the server accepts both STARTTLS and 519implicit TLS (TLS 1.3 only). AUTH covers PLAIN, LOGIN, and CRAM-MD5 on the 520client and PLAIN and LOGIN on the server. Message bodies can be streamed on 521both sides, and the server validates MAIL and RCPT parameters (SIZE=, BODY=, 522and the DSN set RET=, ENVID=, NOTIFY=, ORCPT=). Both sides also speak LMTP, 523where a message ends with one verdict per recipient rather than one for the 524message, and both use PIPELINING, which collapses an envelope into a single 525round trip. 526 527## Known gaps 528 529Measured against the implementations people are likely to be coming from — 530Postfix, Exim and Haraka on the server side, Go's `net/smtp`, Python's 531`smtplib`, lettre and Nodemailer on the client side. Kept here so the list 532is one thing rather than a rediscovery each time. 533 534### Out of scope, not missing 535 536- **Message composition.** No MIME builder, headers, attachments, transfer 537 encodings, `Message-ID` or `Date` generation. zig-smtp carries a message that 538 already exists; building one is RFC 5322's job and belongs in a library of 539 its own. 540- **DSN report generation** 541 ([RFC 3464](https://datatracker.ietf.org/doc/html/rfc3464)). The SMTP half 542 of DSN — RFC 3461's `RET`, `ENVID`, `NOTIFY` and `ORCPT` — is implemented 543 on both sides, but nothing here builds the `multipart/report` message that 544 carries a delivery status back to the sender. That is message composition 545 by another name, so it goes with the library above. 546- **Everything an MTA does around a session.** No queue, no retry schedule, 547 no MX resolution, no routing, no mailbox store. "Server" here means a 548 session handler: listening, accepting and concurrency are the caller's. 549 550### Protocol 551 552- **Client certificates** — neither side can present or verify one. 553- **MT-PRIORITY** ([RFC 6710](https://datatracker.ietf.org/doc/html/rfc6710)), 554 **DELIVERBY** ([RFC 2852](https://datatracker.ietf.org/doc/html/rfc2852)), 555 **FUTURERELEASE** ([RFC 4865](https://datatracker.ietf.org/doc/html/rfc4865)) 556 and **ETRN** ([RFC 1985](https://datatracker.ietf.org/doc/html/rfc1985)) 557 are absent on purpose rather than overlooked, and they are all the same 558 thing: queue features. One orders a queue, one bounces from it on a 559 deadline, one holds in it until a time, and one flushes it on demand. This 560 library has no queue — see the first section — so implementing their wire 561 syntax would advertise a capability nothing here could honour. 562 563 They are already answered correctly. The three parameters are not 564 advertised, so a client sending one gets 555, which 565 [RFC 5321 §4.1.1.11](https://datatracker.ietf.org/doc/html/rfc5321#section-4.1.1.11) 566 defines for a parameter the server cannot implement; ETRN is a command 567 from an extension never offered, so it gets 500. Neither is ignored, and 568 ignoring is the one answer that would be wrong. 569 570### Server 571 572- **No `Received:` header.** 573 [RFC 5321 §4.4](https://datatracker.ietf.org/doc/html/rfc5321#section-4.4) 574 requires a receiving server to stamp one. 575- **The handler sees the identity but not the connection.** 576 `Envelope.authenticated_as` and `Server.identity()` say who authenticated; 577 nothing says where from. No connect callback, no peer address, no TLS 578 state — so greylisting, DNSBLs, SPF and per-IP policy cannot be built on 579 top, and a `Received:` header cannot be written without it. 580- **No timeouts**, so a client that connects and says nothing holds the 581 session forever; 582 [RFC 5321 §4.5.3.2](https://datatracker.ietf.org/doc/html/rfc5321#section-4.5.3.2) 583 specifies per-command limits. This matters more since LMTP arrived: an 584 LMTP server is what a queueing MTA hands mail to, so it is likelier to be 585 somewhere a stuck peer costs something. 586- **No abuse limits** beyond `max_recipients`: no error-count disconnect, no 587 command budget, and no cap on failed AUTH attempts — which also matters 588 more now, since a session may offer several mechanisms and a client can 589 try each in turn without limit. 590- **No `require_tls`** to go with `require_auth`. 591- **No PROXY protocol, XCLIENT or XFORWARD**, so the real peer address is 592 lost behind a load balancer. 593- No filter or milter hook, and so no DKIM, SPF, DMARC or ARC. 594- No logging or tracing hooks. 595- `max_message_size` is not enforced in `messageReader` mode. 596 597### Client 598 599- **`sendMail` is all-or-nothing on recipients** — a refused RCPT abandons 600 the transaction, where `smtplib.sendmail` delivers to the rest and reports 601 the refusals. `envelope` gives a caller the per-recipient codes to decide 602 for itself, but no higher-level call does that decision for it. 603- **No `SIZE=` on MAIL**, though the client parses the capability off EHLO: 604 `max_size` is read and never used, so nothing checks that a message fits 605 before transmitting it. 606- No MX resolution or connect helper, no 4xx retry or backoff, no connection 607 reuse helper. 608- **`Extensions.auth` is the one field that borrows.** It points into the 609 client's reply buffer and is valid only until the next reply is read, which 610 is long enough for the `hello`-then-`authenticate` sequence and no longer. 611 Everything else on `Extensions` is self-contained, so a caller storing one 612 across commands gets a dangling slice with no compiler help. zig-pop3 613 answered the same question the other way, with a bounded copy, because its 614 `capabilities()` promises nothing borrows the read buffer — the two 615 libraries disagree about this on purpose, and one of them should probably 616 give way. 617 618## Standards 619 620- [RFC 5321](https://datatracker.ietf.org/doc/html/rfc5321) — Simple Mail 621 Transfer Protocol: the command/reply protocol, multiline replies, 622 dot-stuffing, reply classes, and ESMTP parameter syntax (client and 623 server). 624- [RFC 1870](https://datatracker.ietf.org/doc/html/rfc1870) — SIZE: 625 advertised and enforced by the server (oversize declarations are rejected 626 with 552 before DATA); parsed from EHLO by the client. 627- [RFC 6152](https://datatracker.ietf.org/doc/html/rfc6152) — 8BITMIME: 628 advertised by the server and `BODY=` validated; parsed by the client. 629- [RFC 3030](https://datatracker.ietf.org/doc/html/rfc3030) — CHUNKING 630 (BDAT) and BINARYMIME: client and server, with length-based framing and no 631 dot-stuffing. `BODY=BINARYMIME` is advertised, accepted and delivered bit 632 for bit, and DATA is refused with 503 for a message that declared it, 633 since binary content cannot be framed by a line holding a single dot. 634- [RFC 8689](https://datatracker.ietf.org/doc/html/rfc8689) — REQUIRETLS: 635 offered by the server when `Options.requiretls` is set and the session is 636 TLS-protected, and reaching the handler as `Envelope.require_tls`; sent by 637 the client through `MailOptions.require_tls`, which is refused on a 638 session that is not encrypted. 639- [RFC 3461](https://datatracker.ietf.org/doc/html/rfc3461) — DSN: 640 advertised by the server, which parses and validates `RET=`/`ENVID=` on 641 MAIL and `NOTIFY=`/`ORCPT=` on RCPT and hands them to the handler; the 642 client sends them through `mail`/`rcpt`. Includes the xtext codec of §4. 643 Generating the report message itself (RFC 3464) is out of scope. 644- [RFC 2033](https://datatracker.ietf.org/doc/html/rfc2033) — LMTP: client 645 and server, via `Client.mode` and `Server.Options.protocol`. `LHLO` 646 replaces `EHLO` and the end of a message draws one reply per accepted 647 recipient instead of one for the message, after DATA and after `BDAT 648 LAST` alike. 649- [RFC 2920](https://datatracker.ietf.org/doc/html/rfc2920) — PIPELINING: 650 the client sends a whole envelope as one group through `envelope`, and the 651 server holds back the replies it is allowed to (RSET, MAIL, RCPT) so they 652 leave together, sending everything pending the moment its input runs dry. 653- [RFC 3207](https://datatracker.ietf.org/doc/html/rfc3207) — STARTTLS: 654 client and server, including the mandatory post-handshake state reset. 655- [RFC 8314](https://datatracker.ietf.org/doc/html/rfc8314) — implicit TLS 656 (SMTPS): client (`Tls` before any SMTP traffic) and server 657 (`.mode = .implicit`). 658- [RFC 4954](https://datatracker.ietf.org/doc/html/rfc4954) — AUTH: client 659 and server, including initial responses, empty challenges, `*` 660 cancellation, and §5's `AUTH=` parameter to MAIL FROM — which the server 661 takes from an unauthenticated client and disregards, as §5 requires. The client drives any mechanism from 662 [zig-sasl](https://git.jcollie.dev/jeff/zig-sasl), and the server offers 663 whichever of their server halves it is handed — PLAIN 664 ([RFC 4616](https://datatracker.ietf.org/doc/html/rfc4616)), the de-facto 665 [LOGIN](https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00), 666 CRAM-MD5 and EXTERNAL among them. 667- [RFC 3463](https://datatracker.ietf.org/doc/html/rfc3463) / 668 [RFC 2034](https://datatracker.ietf.org/doc/html/rfc2034) — enhanced 669 status codes: advertised and attached to every reply RFC 2034 asks for, 670 with a test that walks a whole session and checks each one against that 671 rule; read back by the client through `Reply.enhanced`. 672- [RFC 6531](https://datatracker.ietf.org/doc/html/rfc6531) — SMTPUTF8: 673 client (`mailFromUtf8`) and server (advertised; non-ASCII addresses 674 require the parameter and must be valid UTF-8, rejected with 553 5.6.7 675 per [RFC 6533](https://datatracker.ietf.org/doc/html/rfc6533) otherwise; 676 the flag reaches handlers via `Envelope.smtputf8`). 677 678TLS itself (TLS 1.3, [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446)) 679is provided by [ianic/tls.zig](https://github.com/ianic/tls.zig). 680 681## References cited 682 683The specifications this implementation was written against, and the outside 684work it borrows from, in the RFC citation format so that a reference here 685matches one anywhere else. The **Standards** section above says what is 686implemented of each; this one says what each document *is*. Every entry is 687also filed in the project bibliography, so a citation can be taken from there 688rather than composed; the RFCs are keyed by their DOIs (`10.17487/RFC5321` 689and so on). 690 691- **[RFC1870]** Klensin, J., Freed, N., and K. Moore, "SMTP Service 692 Extension for Message Size Declaration", RFC 1870, November 1995, 693 <https://www.rfc-editor.org/info/rfc1870>. 694- **[RFC2033]** Myers, J., "Local Mail Transfer Protocol", RFC 2033, 695 October 1996, <https://www.rfc-editor.org/info/rfc2033>. 696- **[RFC2034]** Freed, N., "SMTP Service Extension for Returning Enhanced 697 Error Codes", RFC 2034, October 1996, 698 <https://www.rfc-editor.org/info/rfc2034>. 699- **[RFC2195]** Klensin, J., Catoe, R., and P. Krumviede, "IMAP/POP 700 AUTHorize Extension for Simple Challenge/Response", RFC 2195, 701 September 1997, <https://www.rfc-editor.org/info/rfc2195>. 702- **[RFC2920]** Freed, N., "SMTP Service Extension for Command Pipelining", 703 RFC 2920, September 2000, <https://www.rfc-editor.org/info/rfc2920>. 704- **[RFC3030]** Vaudreuil, G., "SMTP Service Extensions for Transmission of 705 Large and Binary MIME Messages", RFC 3030, December 2000, 706 <https://www.rfc-editor.org/info/rfc3030>. 707- **[RFC3207]** Hoffman, P., "SMTP Service Extension for Secure SMTP over 708 Transport Layer Security", RFC 3207, February 2002, 709 <https://www.rfc-editor.org/info/rfc3207>. 710- **[RFC3461]** Moore, K., "Simple Mail Transfer Protocol (SMTP) Service 711 Extension for Delivery Status Notifications (DSNs)", RFC 3461, 712 January 2003, <https://www.rfc-editor.org/info/rfc3461>. 713- **[RFC3463]** Vaudreuil, G., "Enhanced Mail System Status Codes", 714 RFC 3463, January 2003, <https://www.rfc-editor.org/info/rfc3463>. 715- **[RFC3464]** Moore, K. and G. Vaudreuil, "An Extensible Message Format 716 for Delivery Status Notifications", RFC 3464, January 2003, 717 <https://www.rfc-editor.org/info/rfc3464>. *(Cited as out of scope: the 718 report message itself.)* 719- **[RFC4616]** Zeilenga, K., "The PLAIN Simple Authentication and Security 720 Layer (SASL) Mechanism", RFC 4616, August 2006, 721 <https://www.rfc-editor.org/info/rfc4616>. 722- **[RFC4954]** Siemborski, R. and A. Melnikov, "SMTP Service Extension for 723 Authentication", RFC 4954, July 2007, 724 <https://www.rfc-editor.org/info/rfc4954>. 725- **[RFC5321]** Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 726 October 2008, <https://www.rfc-editor.org/info/rfc5321>. 727- **[RFC5322]** Resnick, P., Ed., "Internet Message Format", RFC 5322, 728 October 2008, <https://www.rfc-editor.org/info/rfc5322>. *(Cited as out 729 of scope: the format of the message this library carries.)* 730- **[RFC6152]** Klensin, J., Freed, N., Rose, M., and D. Crocker, "SMTP 731 Service Extension for 8-bit MIME Transport", RFC 6152, March 2011, 732 <https://www.rfc-editor.org/info/rfc6152>. 733- **[RFC6531]** Yao, J. and W. Mao, "SMTP Extension for Internationalized 734 Email", RFC 6531, February 2012, 735 <https://www.rfc-editor.org/info/rfc6531>. 736- **[RFC6533]** Hansen, T., Ed., Newman, C., and A. Melnikov, 737 "Internationalized Delivery Status and Disposition Notifications", 738 RFC 6533, February 2012, <https://www.rfc-editor.org/info/rfc6533>. 739- **[RFC7628]** Mills, W., Showalter, T., and H. Tschofenig, "A Set of 740 Simple Authentication and Security Layer (SASL) Mechanisms for OAuth", 741 RFC 7628, August 2015, <https://www.rfc-editor.org/info/rfc7628>. 742 *(Cited as a gap.)* 743- **[RFC7677]** Hansen, T., "SCRAM-SHA-256 and SCRAM-SHA-256-PLUS Simple 744 Authentication and Security Layer (SASL) Mechanisms", RFC 7677, 745 November 2015, <https://www.rfc-editor.org/info/rfc7677>. *(Cited as a 746 gap.)* 747- **[RFC8314]** Moore, K. and C. Newman, "Cleartext Considered Obsolete: 748 Use of Transport Layer Security (TLS) for Email Submission and Access", 749 RFC 8314, January 2018, <https://www.rfc-editor.org/info/rfc8314>. 750- **[RFC8446]** Rescorla, E., "The Transport Layer Security (TLS) Protocol 751 Version 1.3", RFC 8446, August 2018, 752 <https://www.rfc-editor.org/info/rfc8446>. 753- **[SASL-LOGIN]** Murchison, K. and M. Crispin, "The LOGIN SASL 754 Mechanism", Work in Progress, Internet-Draft, 755 draft-murchison-sasl-login-00, August 2003, 756 <https://datatracker.ietf.org/doc/html/draft-murchison-sasl-login-00>. 757 The draft expired and LOGIN was never standardized; it is implemented 758 here because servers still ask for it. 759- **[TLS.ZIG]** Ianic, "tls.zig — TLS 1.2/1.3 implementation in Zig", 760 <https://github.com/ianic/tls.zig>. Provides the TLS on both sides; see 761 the **TLS** section for why the standard library's client is not used. 762- **[ISEMAIL]** Sayers, D., "is_email — an email address validator and its 763 test suite", BSD-3-Clause, <https://github.com/dominicsayers/isemail>. 764 The address corpus the path parser is checked against; see **Tests**. 765- **[EXIM]** The Exim Maintainers, "Exim Internet Mailer", 766 GPL-2.0-or-later, <https://www.exim.org/>. The protocol torture script 767 and the gauntlet unit test's dialogue are adapted from its test suite. 768 769## Tests 770 771```sh 772zig build test 773zig build test --fuzz # run the fuzz tests under the fuzzer (endless) 774``` 775 776The fuzz tests cover parser crash-safety (`Command.parse`, `Reply.read`), 777whole-session robustness against arbitrary bytes on both the client and 778server side, and two differential properties: the streaming `DataWriter` 779must produce byte-identical output to the slice-based `writeStuffed` under 780fuzzer-chosen chunk boundaries, and the collecting and streaming server 781DATA paths must yield identical message content. 782 783### Protocol torture testing with exim's test client 784 785Exim's scriptable SMTP test client (`test/src/client.c` in the exim 786source) sends raw protocol lines and asserts reply prefixes. The exim 787source is declared as a *lazy* Zig dependency, fetched only on demand: 788 789```sh 790zig build -Dexim-client # fetches exim, installs zig-out/bin/exim-client 791./zig-out/bin/zig-smtp serve 2525 & 792./zig-out/bin/exim-client 127.0.0.1 2525 < test/protocol-torture.script 793``` 794 795### Address corpus testing with the is_email suite 796 797Dominic Sayers' [is_email](https://github.com/dominicsayers/isemail) test 798suite (BSD-3-Clause) is declared as a *lazy* Zig dependency; nothing from 799it is copied into this repository. On demand, the corpus test embeds its 800XML test files, extracts the 125 addresses valid at the RFC 5321 layer, 801and checks that each passes through the path parser byte-for-byte: 802 803```sh 804zig build test -Disemail-corpus # fetches the suite and runs the corpus test 805``` 806 807Without the option the corpus test is skipped. 808 809`test/protocol-torture.script` is a 28-reply dialogue distilled from 810exim's own test suite (syntax errors, sequencing violations, parameter 811validation, dot-stuffing); the same dialogue is asserted byte-for-byte 812as a unit test in `Server.zig`. 813 814The library is MIT-licensed; the small amount of test-only material adapted 815from exim's test suite (the torture script and the gauntlet unit test's 816dialogue) is GPL-2.0-or-later, marked with SPDX snippet tags and REUSE.toml 817annotations. 818 819Note: Zig 0.16.0's fuzz *driver* is broken out of the box (its bundled 820test runner fails to compile in fuzz mode, and the coverage server panics 821on a test binary with no fuzz tests); both are fixed on Zig master. Until 822then, fuzzing needs a patched copy of the standard library via 823`zig build --zig-lib-dir <patched-lib> test --fuzz`. The fuzz tests 824themselves also run once per invocation as part of the normal 825`zig build test` suite. 826 827Interoperability against third-party implementations is covered by a NixOS 828VM test (`nix/interop-test.nix`): the zig-smtp client delivers mail to Postfix 829and Exim over plaintext, STARTTLS, and implicit TLS against each, and swaks 830delivers to the zig-smtp server over plaintext and STARTTLS. 831 832```sh 833nix build .#zig-smtp # build the package 834nix build .#checks.x86_64-linux.interop # run the VM interop test 835```