smtp: implement the client, the message builder and both transports

[loks0n]

Fills in packages/smtp, which #129 landed as a placeholder. Three commits: the specifications and a survey of prior art, the design written against them, then the implementation.

Scope is submission — hand a message to a configured server with authentication and TLS. Resolving MX records and delivering to strangers is a different job with a different failure model, and is out of scope.

What is here

23 classes: Client, Envelope, Message, Address, Attachment, Reply, Result, Capabilities, Encryption, Tls, Mime\{Encoding,Part}, Transport\{Transport,Native,Swoole}, Auth\{Authenticator,Plain,Login,XOAuth2} and five exceptions. Sixteen RFCs are vendored under docs/rfc, in the path .vale.ini already exempts.

$client = new Client(
    transport: new Native('smtp.example.com', 587),
    domain: 'app.example.com',
    authenticators: [new Plain('username', 'password')],
);

$result = $client->send(new Message(
    from: new Address('jane@example.com', 'Jane Doe'),
    to: [new Address('john@example.com')],
    subject: 'Hello',
    text: 'Plain text body',
));

Where it departs from the four implementations surveyed

docs/prior-art.md records the survey — Go net/smtp, emersion/go-smtp, Symfony Mailer, and PHPMailer, which packages/messaging wraps today.

A send is not a boolean. RFC 5321 lets a server refuse some recipients and accept others while the message still reaches the rest. Result carries accepted, rejected as address to Reply, and the queue identifier. TransactionException is thrown only when every recipient is refused, and its Reply answers the question a queue-backed sender actually has: isTransient() means put it back, isPermanent() means do not. PHPMailer sets one ErrorInfo string, which messaging copies into every per-recipient result, so today that distinction cannot be made at all.

The envelope is its own type and the client never parses what it sends. Bcc addresses reach RCPT TO and no header. Only PHPMailer merges the two, which is why its SMTP class cannot be used on its own.

Encryption is an enum, not Symfony's autoTls and requireTls — two booleans whose four combinations include one that means nothing.

No keep-alive, restart threshold or ping threshold. A Client is one connection; pooling is what utopia-php/pools is for.

Two subtleties, both silent when wrong

The read buffer is cleared with the capability map after STARTTLS. RFC 3207 section 4.2 requires forgetting what was said before the handshake, and that has to include bytes already sitting unread — they arrived in the clear and could have been injected ahead of the upgrade. The test that proves it first looked like a failure: clearing the buffer discarded the rest of the scripted replies, which is exactly right, so the double now models a server that stays quiet until the handshake finishes and the assertion checks the capabilities came from the reply read afterwards.

Dot-stuffing is a generator holding two pieces of state, not a str_replace: whether the next byte opens a line, and a trailing \r whose \n has not arrived yet. Without the second, a chunk boundary falling inside a CRLF reads as a bare CR and the stuffing misses — which truncates the message at that point, and only for messages large enough to split there. Eleven cases in StuffingTest.php, plus an end-to-end check that a message containing a lone . line survives.

Testing

composer test is 85 unit tests driving a scripted in-memory transport: no sockets, no containers. composer test:e2e is 10 more against Mailpit in compose, on host ports 11026 and 18026.

The end-to-end tier earned its place by contradicting two assumptions:

• Mailpit annotates a stored message with its own Bcc, Return-Path and Received, so "no blind recipient reaches a header" can only be asserted about the bytes we wrote. The test asserts both halves — the server did see the blind recipient, and we did not put it in a header.
• It advertises SIZE 0, which exercises the rule that a declared zero means no fixed maximum rather than a zero-byte limit.

The server presents a committed self-signed pair from tests/fixtures/certs, following the nats precedent. Generating one in the container entrypoint was the first attempt and does not work: the image has no openssl and no /data, and depending on apk add at test time would be flaky in CI. MP_SMTP_ALLOWED_RECIPIENTS gives the suite an address the server genuinely refuses, which is what makes partial acceptance testable against real replies.

Deliberately not done

• PIPELINING is parsed but unused. It saves a round trip per recipient and moves error attribution from "the reply to this command" to "the third reply in this group". The reply reader is shaped so it can be added.
• Telemetry stays out, following the dns version 2 redesign — the surface is small enough to decorate.
• Per-command timeouts. RFC 5321 section 4.5.3.2 asks for six, from two minutes to ten. Those minimums were written for relays under load; PHPMailer and Symfony both ship a single thirty second timeout. Documented as a deviation.
• The messaging migration. Dropping PHPMailer from Adapter\Email\SMTP needs a released smtp first, since CI tests changed packages against Packagist and a consumer cannot adopt an unreleased sibling in the same pull request.

Checks

• bin/monorepo check smtp — Pint, PHPStan and Rector pass
• bin/monorepo test smtp — 85 unit, then compose up and 10 end-to-end
• bin/monorepo validate — passes
• vale README.md docs packages — 0 errors

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

The PR replaces the SMTP package placeholder with a complete message-submission client, MIME message builder, authentication mechanisms, and native and Swoole transports.

• Supports TLS policies, SMTP authentication, capability negotiation, partial recipient acceptance, and internationalized addresses.
• Adds streamed MIME construction, attachments, header encoding and folding, and robust DATA dot-stuffing.
• Adds unit and Mailpit-backed end-to-end coverage for protocol, transport, recovery, and message-rendering behavior.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported SMTPUTF8, interrupted-DATA, final-reply recovery, and LOGIN reconnect failures are resolved in the current code, and no blocking failure remains.

Important Files Changed

Filename	Overview
packages/smtp/src/Client.php	Implements SMTP session initialization, capability negotiation, authentication, transaction handling, DATA streaming, and connection recovery; the previously reported lifecycle and SMTPUTF8 defects are fixed.
packages/smtp/src/Message.php	Builds MIME messages and propagates internationalized address requirements, including Reply-To, into the SMTP envelope.
packages/smtp/src/Envelope.php	Separates SMTP paths from message headers and preserves message-level SMTPUTF8 requirements.
packages/smtp/src/Auth/Login.php	Implements LOGIN responses without mutable exchange state, preventing credential-order corruption after reconnects.
packages/smtp/src/Transport/Native.php	Adds the PHP stream-based connection and TLS transport implementation.
packages/smtp/src/Transport/Swoole.php	Adds coroutine-native SMTP transport with TLS and peer-verification handling.
packages/smtp/src/Mime/Header.php	Implements encoded-word generation and standards-aware header folding.
packages/smtp/tests/Unit/ClientTest.php	Covers SMTP session behavior, capability handling, authentication, SMTPUTF8, transaction outcomes, and recovery from failed connections or malformed replies.

_{Reviews (8): Last reviewed commit: "smtp: stop asking the kernel for a port ..." | Re-trigger Greptile}