Skip to content

Rust `lettre` crosswalk

This crosswalk compares Mail API with the Rust lettre crate. Lettre provides a typed message builder with address, multipart body, attachment, and SMTP transport support. It is a strong source model for a Mail API adapter, but its built-in transports send SMTP messages rather than Mail API HTTP requests.

lettre concept Mail API field Mapping observation
Message::builder() addresses from, to, cc, bcc, replyTo Direct correspondence for structured mailbox headers.
subject() subject Direct correspondence.
SinglePart and MultiPart::alternative() text, html Plain-text and HTML alternatives can be mapped before MIME encoding.
Attachment attachments Filename, content type, and bytes can be converted to Mail API’s Base64 content.
Message headers headers Preserve application-defined headers after excluding fields represented by structured Mail API properties.

Use an application adapter to turn the structured message inputs into a POST /v1/messages JSON request. Do this before calling Message::formatted(), because formatted MIME output combines headers and body parts into an opaque byte stream that requires parsing to recover Mail API fields.

Lettre’s SMTP transports remain useful when SMTP is the intended delivery mechanism. For adapting existing SMTP submission code, see the SMTP crosswalk.

  • Mail API 202 indicates asynchronous acceptance, while 200 indicates completion within an applied wait. Neither confirms final recipient delivery.
  • Inline attachments with content IDs need an application policy because Mail API v1 has no equivalent structured field.
  • Preserve retry safety by mapping a caller-generated idempotency key to the Idempotency-Key request header; Lettre does not supply an equivalent transport-level mechanism for HTTP submission.