A Centra fashion storefront sends weekly campaigns through Klaviyo. Sanity holds emailSettings, React Email templates compile to HTML, and a push job uploads CODE blocks to Klaviyo so editors do not hand-edit HTML in Klaviyo on every deploy. Marketing wanted a hero clip in the campaign. <video> looked fine in the preview tab because the preview is a browser. In Gmail it was a blank rectangle. Outlook was worse.

Email clients do not run <video>. Some strip the tag. Some leave an empty box. Autoplay was never on the table. The clip still had to feel tappable: poster frame, play affordance, land on YouTube or Vimeo or TikTok in the browser.

In the demo, use Play overlay on/off and click the poster. The block is a linked raster image, not a video element. That matches what actually survives the inbox.

A poster that lies honestly

The reusable atom is a hosted raster poster (optional play-button overlay) wrapped in an outbound Link. React Email renders Img plus Link for most clients. Outlook needs a VML shell around the background poster: <!--[if mso]><v:rect>...<v:fill src="..." />. Same href, same alt, same raster. Without the VML branch, Outlook shows a broken icon or nothing.

I dropped a <video> into React Email. It looked fine in a browser preview because the preview is a browser. Gmail still stripped the tag or left an empty box. I want one href, one alt, one image, plus the Outlook branch that paints that same image.

The overlay is a hint. Autoplay was never on the table, so the play mark only says this tap leaves the inbox. YouTube, Vimeo, or TikTok opens in the browser, and the email never had to decode a codec. showPlayOverlay defaults to true. Turn it off in the demo if the poster already contains a play mark. Same Link, same raster, same Outlook VML: the overlay is optional chrome on top of a hosted image.

Most clients get Img plus Link. Some layouts use backgroundImage plus the overlay on the same href. Outlook still needs the v:rect / v:fill branch. Two visual recipes, one mapper. If the poster URL is missing, neither recipe should render.

Sanity has to be complete or omit

Sanity holds campaign video fields: poster asset, alt text, external href. At Klaviyo push time a mapper bakes props into the template and returns null unless both poster URL and href exist. mapSanityImageAssetUrl builds the poster. Href and alt are trimmed, and empty href after trim counts as missing. Poster without link, or link without poster: omit the block. Partial config should not ship a half-built thumb that clicks nowhere or shows alt text on a missing image.

Hand-edited CODE in Klaviyo does not survive. The next deploy overwrites it. Fix the React Email component or the Sanity fields, then push again. The source of truth is the template plus the mapper.

export function EmailVideoThumb({ alt, href, src, showPlayOverlay = true }: Props) {
  // Link wraps Img, or backgroundImage + play overlay
  // Outlook: <!--[if mso]><v:rect>...<v:fill src=... />...
}
 
export function mapEmailSettingsToCampaignVideo(result): Props | null {
  const posterSrc = mapSanityImageAssetUrl(result.campaignVideoPoster, ...)
  const href = result.campaignVideoHref?.trim() ?? ''
  if (!posterSrc || href.length === 0) return null
  return { alt: result.campaignVideoAlt?.trim() ?? '', href, src: posterSrc }
}

The omit rule is load-bearing because a URL alone is not video in the inbox, and a pretty poster that goes nowhere is not a thumb. A blank hero in the weekly campaign is worse than no hero. If marketing wants in-inbox motion, they need a different channel. I would rather ship a still that opens YouTube than a <video> tag that every client strips and then blame Klaviyo for not supporting video.

If you want video in email, ship a picture that lies honestly about being a link.

Happy coding! Sander