Crate mailrs_mail_builder 

Outbound mail builder — the inverse of the mailrs parse stones.

Constructs canonically-compliant RFC 5322 / 2046 / 2047 / 2231 raw bytes for outbound delivery. Lives across from the parse stones (mailrs-rfc5322, mailrs-rfc2047, mailrs-mime) so the same MIME compliance invariants we enforce on inbound can be enforced on outbound — the same canonical envelope, the same encoded-word boundaries, the same CTE-selection heuristics.

Why a builder stone

Outbound message construction in mail servers tends to grow ad-hoc string formatting that drifts toward MIME non-compliance over time (lone LF, mis-folded headers, bad boundaries, missing Content-Transfer-Encoding). When a message looks merely “weird” rather than “broken”, receiving MTAs silently lower reputation rather than reject — the failure mode is “we got banned without ever seeing a 5xx”. A canonical builder closes that whole class of bug at the source.

Scope

• Plain-text single-part messages.
• multipart/alternative (text + html).
• multipart/mixed (body + attachments).
• Encoded-word (RFC 2047) for non-ASCII header values.
• Soft-fold (RFC 5322 §2.2.3) at 78 chars.
• CTE auto-selection: 7bit / quoted-printable / base64.
• Boundary collision-scan (regenerate if body contains it).

Out of scope (deliberate): S/MIME, OpenPGP/MIME, calendar invites (use mailrs-ical), DKIM signing (use mailrs-dkim), DSN formatting (use [mailrs-outbound-queue::dsn] — to be migrated onto this builder in ckpt 1).

Status

0.1 — initial MVP. The API is intentionally narrow to match the three internal mailrs use cases (DSN, DMARC report, future TLS-RPT). Wider API surface lands in 1.0 after the deliverability hardening pass (ckpt 2 in the v8 RFC).

Structs

Attachment

One attachment: filename + content-type + raw bytes. The builder picks the CTE automatically (almost always base64) and emits a Content-Disposition: attachment; filename="..." header.

MessageBuilder

Builder for outbound RFC 5322 messages.

Enums

ContentTransferEncoding

MIME Content-Transfer-Encoding choices the builder picks from.

LintError

One lint failure category.

Functions

choose_cte

Pick the canonical CTE for body.

generate_boundary

Generate a MIME boundary string of the form mailrs_<pid>_<counter>_<rng> that is highly unlikely to collide with any reasonable user input. Callers should still scan the body and call generate_boundary again if a collision is found — multipart_envelope does this automatically.

lint

Check a raw built message against the invariants. Returns the first failure or Ok(()) if everything passes.

multipart_envelope

Build a multipart envelope: returns the bytes that go BETWEEN the outer headers and the closing boundary, with a guaranteed-unique boundary that does not appear in any of the parts. Returns (boundary, envelope_bytes).