authoring-html-email

Email is not the web. Clients (Gmail, Outlook, Apple Mail) strip <head>/<style>, ignore most CSS, and some show only plain text. A "looks fine in my browser" HTML email arrives broken or as raw tags. Build for the medium.

Use radical-brevity to edit the message text before building the HTML and plain-text parts.

The non-negotiable: multipart/alternative with BOTH parts

EVERY client-facing email MUST be multipart/alternative carrying both a text/html part AND a text/plain fallback — always, no exceptions. Clients that can't/won't render HTML show the plain part; a missing plain part = some recipients see nothing useful (or your HTML as raw source). Order matters: plain-text first, HTML second (clients pick the LAST part they support).

Content-Type: multipart/alternative; boundary="b"
--b
Content-Type: text/plain; charset="utf-8"
<readable plain version>
--b
Content-Type: text/html; charset="utf-8"
<the HTML>
--b--

HTML that survives email clients

• INLINE every style (style="..." on each element). <style> blocks and external CSS are stripped by major clients. Use a tool/step that inlines CSS before send.
• Tables for layout, not flexbox/grid (Outlook uses Word's rendering engine). Set explicit widths; avoid negative margins, position, float.
• Images: absolute https URLs (no cid:/attachments unless intentional); ALWAYS set alt (many clients block images by default) and width/height; don't rely on background-images.
• Links: full absolute URLs; don't hide critical info behind images-only.
• Keep it narrow (~600px), web-safe fonts with fallbacks, sufficient contrast.

Verify BY RENDERING the received message (not the send log)

"Sent" ≠ "renders". Verification = inspect the ACTUALLY-RECEIVED message: confirm it's multipart/alternative with both parts (read the raw MIME), and that it renders as HTML in a real client (or a rendering preview), images/links work, and the plain-text fallback is readable. A send-API 200 proves nothing about rendering.

DONE means

The received message is multipart/alternative with a text/plain fallback AND a text/html part; styles are inlined; it renders correctly in a real client; verified by inspecting the received MIME + rendering — not by the send log.