# 02 · The email template

*From Adam Schoenfeld (adamgtm.com). Part of a kit for beehiiv builders at https://adamgtm.com/design-process/. True as of October 23, 2026.*

My weekly issue has one locked format. A beehiiv post template holds the fixed parts. Each week an agent fills the slots from a short spec and my Markdown, then checks the email as readers will see it. This file covers the format, how it's built, the partner block, the traps in beehiiv's email render, and images.

## The format, top to bottom

1. **Masthead.** An ink title bar (my icon, "Adam's GTM Report", the date) and this week's agenda stacked under it, in one frame. It holds only what's true and useful to every reader every week. No welcome sentence.
2. **"Forwarded this email? Subscribe here."** One small line, email only.
3. **[1] Sponsors.** The partner block (below). The agenda line for it stays general ("they make this possible"); it doesn't list names.
4. **[2] Quick takes.** My LinkedIn posts from the week as ledger rows: date, a tag, the logos of the companies the post features, the headline, a one-line take, the comment count and "Join the conversation". A footer row links my live market tracker.
5. **[3] Deep dive.** The issue title as a real H1, the lead card (`04-thumbnails-and-checks.md`), a short TL;DR attached under it, the article as narrative, a reply question, then "Go deeper": a plain list of sources, one row each.

The system that ties it together: numbered square ink tiles for the section headers, a thin line with a gold dot connecting them, and every box in paper with an ink frame.

Rules I locked along the way:

- **One system.** Every box shares one frame and one fill rule.
- **The deep dive stays narrative.** I tried tabs inside it and cut them; I write in long form.
- **One lead graphic.** A second infographic was one too many.
- **A section header replaces any title that repeats it.** The partner block lost its own title row because "[1] Sponsors" already says it.
- **Tags say what a post is:** Deal, Launch, Framework, or My take. Use the most specific one; "My take" on every row was too much.
- **Count lines in the render, not by eye.** The agenda's Quick takes line fits two lines on a phone.

## How it's built

**Before the first issue.** Check that your beehiiv plan has custom HTML blocks (`htmlSnippet`); the partner block depends on them. Have the agent read `learn_post_authoring` and `learn_post_metadata`: they say which markup survives a save, and unsupported markup can disappear without an error. Then build three things once and test them on a throwaway draft: your template, a small script that renders each slot, and the placeholders. Only then make issue one.

- **A beehiiv post template** holds the masthead frame, the section headers, the footer and one placeholder paragraph per slot (masthead agenda, partner block, quick takes, each deep dive piece).
- **One small JSON spec per issue:** title, agenda line, the quick takes (date, tag, logos, headline, take, comment count, URL), TL;DR, reply question, Go deeper links, the lead image. A script turns each slot into HTML. Plain-text fields get escaped; nothing is typed into HTML by hand.
- **The draft:** create it from the template with `save_post` and `post_template_id`. Set the subject, and in the email settings hide beehiiv's own title, subtitle and byline so the masthead comes first. On the web, show the title and subtitle, and hide the thumbnail (the lead card is already in the body).
- **The slots:** read the body with `get_post_content(format="editor_html")`, find each placeholder's block hash, and replace the slots with `edit_post_content`. Either send every change in one call from a fresh read, or send one call at a time using the new hashes each response returns. Never reuse hashes from an earlier read. If a placeholder is missing or matches twice, stop and look. Never guess a target.
- **The article:** I write in Markdown. It's converted to beehiiv's HTML in chunks and inserted, after its images are uploaded (see Images).
- **The checks** (end of this file). A draft with placeholders left is a scaffold, not a finished issue.

The title goes everywhere: subject line, masthead agenda and the deep dive's H1. The email hides beehiiv's title, so the issue needs its own H1. On the web that H1 repeats the page title, so hide it there with page CSS (`03-site-builder.md`).

## The partner block

What readers see: one spotlight partner (a wordmark and a headline, or the partner's own banner) plus one to five partner rows, each a logo, a name and one line of copy, in the order I set. A week with no spotlight uses equal-weight rows instead.

How it's built:

- **A custom HTML block (`htmlSnippet`), tables and inline styles only.** beehiiv's native table node drops inline styles and takes its borders from the post theme, so the design wouldn't survive as normal content. HTML snippets do render in email. beehiiv strips `<style>`, `<script>`, iframes, audio and video.
- **It fills its container.** No `width="600"` cap. beehiiv's email shell already holds the body to 600px, and the web column is wider. With a cap, the card stopped short of the body text on the web.
- **Logos come from beehiiv's CDN,** at the direct media URL (see Images). On the web, give them `max-width:100%;height:auto`. The web theme shrinks a wide logo to its cell, and a fixed height then stretches it.
- **A banner creative** is wrapped in the partner's link, capped (400px wide read best for a 2:1 banner), and carries its own font size, so its alt text still shows when images are off.
- **Link a partner's name once.** Linking every mention put six links to one URL in a single card.
- **beehiiv adds UTM tags to every link.** A partner URL that already carries tags ends up with both sets.
- **Dark mode.** Gmail on iPhone inverts the whole email. I tried two treatments:
  - *Protect the light fills:* every cell carries `bgcolor`, an inline `background-color` and a same-color `linear-gradient`; beehiiv's sanitizer drops the first and keeps the other two. Text needs the same trick (a gradient clipped through transparent text) or Gmail lightens it on the white you protected. It works, but it's heavy.
  - *Logo plates (what I use now):* let the block invert with the rest of the issue, and put only each logo on its own small protected white plate. Logos stay readable, everything else matches the issue, and the block got about 40% smaller.
  - Outlook for Windows ignores the fill trick. If a plate shows as a tight white box there, bake the white margin into the logo file.

## The email CSS traps

Each one looked fine in the editor and broke in the email.

1. **What happened:** beehiiv's email theme pads every `<p>` 12px top and bottom, and forces any link inside a `<p>` to italic navy with `!important`. **What to do:** use `<div>` for text in custom HTML.
2. **What happened:** whitespace-only text between two tags is deleted. `Sponsors:</b> <span>they` rendered as "Sponsors:they". **What to do:** write `&#160;`, plus `&#8203;` where the line must still be able to break.
3. **What happened:** `height=` attributes are stripped in email (the web keeps them), so a 6px color bar collapsed in email only. **What to do:** put the height inline in `style`, and give an empty cell `&#160;`.
4. **What happened:** a minifier that collapsed `>\s+<` ate the `&nbsp;` spacers, because Python's `\s` matches the no-break space. It also welded neighboring words and links together. **What to do:** collapse whitespace only at block boundaries.
5. **What happened:** a template created through the API got an auto-generated theme. **What to do:** compare it with a past post's theme (`get_post_theme`) before trusting it.
6. **What happened:** body type (font, size, link style) comes from each post's theme, on the web too. **What to do:** change type in the template's theme, and send a test email first.
7. **What happened:** native tables drop cell styles and `align`. **What to do:** style tables with the post theme's table tokens (`save_post_theme`): header fill, cell fill, borders, padding. Never set `colwidth`; it writes fixed pixels and breaks the phone layout.
8. **What happened:** a Markdown blockquote became a decorative pull quote, and a single line break inside a paragraph collapsed to a space. **What to do:** use a plain paragraph for notes, and a real `<br>` for a line break.
9. **What happened:** block hashes change on every edit, across the whole document. A stale target aborts the whole batch, so nothing applies. **What to do:** re-read `editor_html` right before writing, and land every change in one call.
10. **What happened:** passing `post_template_id` together with `html_content` put my body after the whole template, below the footer. **What to do:** start a post bare, or create it from the template and fill its placeholders.
11. **What happened:** custom HTML inside an email-only section is hidden on the web. **What to do:** use it on purpose (the "Forwarded this email?" line lives there).

## Size

Gmail clips an email at about 102KB. My check fails anything over 100,000 bytes to keep a margin. On my issue about 39KB is fixed: beehiiv's head CSS (about 12.7KB), the masthead and section headers, the partner block and beehiiv's required footer. Each quick take costs about 3.9KB. In the article, each paragraph adds about 150 bytes of wrapper and each link about 230 bytes, because of the UTM tags. When an issue runs long, cut repeated links first, then secondary source links. Measure the bytes of the rendered email, not the editor. Near the limit, beehiiv's own size estimate in the editor is the final word.

## Images

1. **What happened:** `save_image` takes a public HTTPS URL and refuses `file://`. Sending an image as base64 through the model corrupted it: one flipped character, same length, silently broken. **What to do:** host the file at a public URL first. I put images on a temporary draft deploy (never production), pass each URL, then delete the deploy.
2. **What happened:** a corrupt upload still returned a URL. **What to do:** check the response. Width and height of `null` means beehiiv couldn't read it; upload again.
3. **What happened:** the resizer form of a beehiiv image URL (`/cdn-cgi/image/...`) adds a redirect and can serve WebP, which Outlook can't show. **What to do:** use the direct media URL.
4. **What happened:** an old helper reduced graphics to 128 colors and muted the blues. **What to do:** upload graphics at their original quality. Downscale photos to about 1000px. Logos can be small, flattened PNGs.
5. **What happened:** a link wrapped around an image block was flattened and lost. **What to do:** build image blocks in beehiiv's own figure markup, with the caption as a `figcaption` inside the figure, and put links in the caption.
6. **What happened:** a company logo that couldn't be found came out as a gray letter tile. **What to do:** open every logo file before using it. Get the real mark from the company's site.

## Check the email the way readers see it

- Read the real themed email with `get_post_content(format="html")`. The editor and the web page hide the traps above.
- Render it in a headless browser at 700px and 390px, in light and a simulated Gmail dark mode, and look at all four.
- Headless Chrome's `--window-size` won't go below 500px wide; the page lays out at 500 and the screenshot shows the left 390, which looks like overflow that isn't there. Set a real viewport (Playwright does) or render inside a fixed-width container.
- Full-page screenshots repeat after 16,384 device pixels. Capture a long issue in segments.
- Then the human sends test emails: Gmail on iPhone in dark mode, Apple Mail, Outlook, and Gmail with images off. That's the only real inbox check.