[productdevbook]

Closes #135, closes #136, closes #137, closes #138, closes #139, closes #140, closes #141, closes #142.

Seven drivers — 28 in total now — and the four core gaps that building them would each have worked around. The gaps landed first, so none of the seven had to route around the library.

The core, before the drivers

A templated send no longer needs a subject. A template carries its own, and an always-present subject overrides it — which was wrong for Brevo and Postmark, and Loops discarded it outright. NormalizedMessage.subject is optional now, so every driver had to say what it does without one; TypeScript found all twenty-eight sites.

An attachment can be a URL the provider fetches, so a large file never passes through this process. Exactly one of content and url. A driver must claim features.remoteAttachments or the core refuses the message — sending it with the attachment quietly missing is the failure worth preventing.

httpText and httpBytes sit alongside httpJson. The JSON variant parses and discards anything that is not JSON, which made a raw RFC 5322 message and an attachment's bytes unreachable — Mailcrab had to leave /api/message/{id}/raw unexposed for exactly that reason. Both catchers can read them now.

The fourth gap — a nullable EmailResult.id — is deliberately not done. Every id a driver composes today is stable and resolvable by something; a nullable id would push that uncertainty onto every caller to fix a problem three drivers have.

Two more came out of the agents' own reports: toUuid had been copied verbatim into Brevo and Azure, and cancel/retrieve could not be cancelled — which matters because Azure's retrieve is a poll.

Where reading the documentation changed the answer

Two of my own issues were wrong, and the drivers are right:

• feat(drivers): Mailjet — its Messages array is already the batch shape this library wants #136 on Mailjet. A batch where any message fails answers 400, not 200 — with the accepted messages' ids still in the body. A driver reading the status alone reports every message as failed, including ones Mailjet has already sent. Confirmed against Mailjet's own Java client. Also, SandboxMode is a payload root property, so a dry-run message cannot share a request with a live one.
• feat(drivers): SMTP2GO — regional hosts, attachment-by-URL, and errors hidden inside a 200 #137 on SMTP2GO. Its send endpoint takes one message per request — its own counters class a multi-recipient email as one email — so features.batch is not declared rather than promising a request the provider cannot do. And a message over the per-field cap is refused, not split: splitting changes what each recipient sees in the header and leaves one message with several provider ids.

And what the providers themselves get wrong or bury:

• Azure's access key is base64 and must be decoded before use as the HMAC key. Raw, it signs every request wrong for a bare 401.
• AhaSend's own Authentication examples call a route that does not exist. Every one says /v2/messages; the OpenAPI has only /v2/accounts/{account_id}/messages.
• Scaleway's send_before is a delivery deadline, not a send time. Mapping scheduledAt onto it would send immediately and mean something else, so scheduling is not claimed.
• Mailbreeze takes attachmentIds from a presigned upload, not inline content — so attachments: false is the honest declaration. Its docs also contradict themselves on the base path and auth header.
• SMTP2GO keys inline images by the cid, not the filename — it addresses them as cid:<filename>, so the two must be the same value or the reference resolves to nothing.
• Mailpit stores Message-ID with the brackets stripped and matches with SQL LIKE, and DELETE /api/v1/messages treats an empty id list as delete everything — so delete([]) sends no request at all. Both read out of its Go source, not its docs.

Worth knowing about two of them

Azure is the only driver where retrieve() costs nothing. A send is a long-running operation you poll; everywhere else per-message status is a paid add-on. HMAC-SHA256 over Web Crypto, no @azure/*, so it runs in a Worker. The signature is verified in tests the way DKIM is — re-derived from the spec and checked with crypto.subtle.verify, with discrimination proved against a tampered body, host, verb, date and key.

Mailpit brings htmlCheck(), which scores a message's HTML against real mail clients. A test that asserts a template renders in Outlook is something no other driver here can offer.

Verification

793 tests, 40 files. Coverage rose to 91.46 / 84.16 / 90.66 / 93.43, and the floors go to 91/84/90/93.

They sat under the floor for about an hour, while three drivers' sources were in the tree and their tests were not. I left the floor alone and waited rather than lowering it to fit — lowering a threshold to reach green is not reaching green.

Lint, format, typecheck with isolatedDeclarations, version consistency, export-map parity, JSR dry run, build with every .d.mts present, and bundle budgets all clean.

Noticed, not fixed

• mailpit.retrieve() ignores the abort signal. The inbox methods have no signal parameter and adding one changes every public signature there; bounded by timeoutMs instead.
• AhaSend treats one accepted recipient as success, with every per-recipient verdict on result.provider. Result is binary and failing the whole send would make a retry re-send to recipients already queued — but it is a judgement call worth a second opinion.
• SMTP2GO's schedule format is inferred: the request example is "2025-09-10 13:15:00 +1200" and the search response echoes ISO 8601. The driver sends ISO; if a live send rejects it, it is one line.
• Neither catcher has been run against a live server. Mailpit is the cheap one to fix — a gated integration test against docker run axllent/mailpit would confirm the JSON field casing taken from its swagger.
• rejectUnauthorized: false in mailcrab and mailpit for their self-signed local listeners. Correct there, and a standing wart.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GQAPDWLnDrdYHKhou3Ntvb