Overview

When building a newsletter template, your layout relies on a handful of foundational layout elements known as content blocks. Think of these blocks as the core building blocks of your email.

This article covers the technical specifications, formatting rules, and cross-client compatibility guidelines for each general block type (Text, Image, Button, Video, and Embed/HTML), along with a structural layout blueprint to help you create high-performing newsletters.

1. Core content blocks

Text blocks

The text block is the primary container for all typography, including headings, paragraphs, and lists.

Configuration guidelines

• Font sizing hierarchy: set your body copy between 14px and 16px to ensure mobile legibility. Headings (<h1> through <h3>) should range between 22px to 28px.

• Line spacing: always set your inline line-height to 1.5 or 1.6. This prevents text from overlapping on tighter mobile screens.

• Accessibility & contrast: maintain a colour contrast ratio of at least 4.5:1 (WCAG 2.1 AA standard) between your text and the background colour.

• Font fallbacks: email clients do not always render custom web fonts. Always include a web-safe fallback stack in your styles so your text stays clean if a custom font fails to load.

/* Example of a resilient font stack */
font-family: 'Your Custom Font', Arial, Helvetica, sans-serif;

Image blocks

Image blocks are used to inject photography, product shots, graphics, and animated visuals into your layout.

Configuration guidelines

• File size optimisation: keep asset file sizes under 200KB. Large images trigger spam filters, slow down load times, and can cause clipping issues in apps like Gmail.

• Alt text required: always fill out the Alt Text (Alternative Text) field. Many email clients block images by default; alt text ensures your subscribers still understand the context of the missing image.

• Supported formats: use standard web formats — .jpg for photos, .png for graphics with transparent backgrounds, and compressed .gif for short animations.

• Text inside images warning: avoid baking important text (like sale details or headlines) directly into an image asset. If the client blocks images, that text is completely lost to the reader.

2. Interactive & rich media blocks

Button blocks (call to action)

Button blocks are the interactive entry points that direct readers to external web pages, driving your click-through rate (CTR).

Configuration guidelines

• Bulletproof coding: never use an image file as a button. If images are blocked, your button disappears. Instead, always use a bulletproof button built out of HTML background colours and text styles.

• Sizing for touch elements: ensure your buttons have a minimum click/tap target size of 48px by 48px to remain easily clickable on mobile devices.

• Actionable copy: use specific, action-oriented text rather than generic labels. Use "Download the Guide" or "Shop the Sale" instead of "Click Here."

Video blocks

True, interactive video playback elements (<video>) are blocked by almost all major email clients (Gmail, Outlook, Apple Mail) due to security protocols.

Configuration guidelines

• The thumbnail workaround: to showcase video content, our newsletter builder uses a composite video placeholder block. When you paste your video URL (YouTube, Vimeo, etc.), the block automatically:

  • Grabs a static preview frame of the video.

  • Overlays a distinct, centred "Play Button" icon over the image.

  • Hyperlinks the entire asset directly to your video page.

• Visual check: ensure your video thumbnail is sharp and the overlaid play icon doesn't block critical context.

Embed / HTML blocks

The Embed block acts as a raw code sandbox, allowing you to insert custom HTML code or third-party web snippets directly into the canvas.

Configuration guidelines

• Common use cases: displaying live countdown timers, pulling in automated RSS blog feeds, or rendering custom-designed geometric section dividers.

• Strict security limitations: modern inbox security applications instantly strip out <script> tags, iframe windows, and interactive form fields. Stick entirely to basic layout HTML structure.

• Inline styling enforcement: global <style> blocks can break parent email frameworks. All CSS formatting written inside an embed block must be written directly inline on the elements.

<!-- Example of correct inline styling inside an HTML block -->
<div style="background-color: #f4f4f4; padding: 20px; text-align: center;">
  <p style="color: #333333; margin: 0;">Your custom content here.</p>
</div>

3. Architecture blueprint: designing a campaign layout

To maximise reader engagement and click-through metrics, organise your blocks following the Inverted Pyramid Framework. This structure naturally guides a subscriber's eye from broad context down to a sharp, single focal action point.

1. Establish visual identity: header block. Drop a brand logo using an Image Block at the top of the canvas, followed immediately by a Text Block using an <h1> tag to deliver a clear headline hook.

2. Deploy a visual anchor: hero image block. Place a striking, high-quality Image Block directly below your headline block. This image visually expands on the core topic introduced in Step 1.

3. Write scannable context: body text block. Insert a Text Block to write a brief summary. Keep paragraph elements to a maximum of 2 to 3 sentences to prevent reading fatigue.

4. Position the core action: primary button block. Place your high-contrast Button Block directly beneath the text copy. This forms the focused tip of your inverted pyramid structure, capturing user clicks at peak interest.

5. Append secondary feeds: video or embed block. If your issue features secondary resources (like a podcast link or extra articles), stack a Video Block or custom Embed Block below the primary conversion zone.

Block configuration reference

Use this matrix as a quick checklist before pushing a newsletter campaign to production:

Pre-flight testing checklist: before deploying your final campaign to your subscriber list, send an active test email to both a desktop inbox app (like Outlook or web-based Gmail) and a mobile application viewport (like Apple Mail). Check for layout shifting, pixelation, or broken spacing layouts across different devices.

Frequently asked questions

Q: Why does my custom font not show up for some subscribers?

Ans: Not all email clients render custom web fonts. That's why it's important to include a web-safe fallback stack (such as Arial or Helvetica) in your styles, so your text still displays cleanly if the custom font fails to load.

Q: Can I use an image as a clickable button?

Ans: It isn't recommended. If images are blocked in a recipient's inbox, an image-based button will disappear entirely. Use a bulletproof HTML-based button built from background colours and text styles instead.

Q: Why can't I add a playable video directly into my newsletter?

Ans: Most major email clients, including Gmail, Outlook, and Apple Mail, block interactive video playback for security reasons. The newsletter builder works around this by generating a clickable thumbnail with a play icon that links out to the video.

Q: Can I add JavaScript or custom scripts inside an Embed/HTML block?

Ans: No. Modern inbox security strips out script tags, iframes, and interactive form fields automatically. Embed blocks should stick to basic layout HTML with inline CSS only.

Q: Why do my images sometimes fail to load for recipients?

Ans: Many email clients block images by default. This is why filling out the alt text field is important, so subscribers still understand the context even if the image itself doesn't load.

Q: What's the recommended order for arranging blocks in a newsletter?

Ans: The Inverted Pyramid Framework is recommended: start with a header block for brand identity, follow with a hero image, then scannable body text, a primary call-to-action button, and finally any secondary video or embed content.

Q: Should I test my newsletter before sending it to my full list?

Ans: Yes. It's best practice to send a test email to both a desktop inbox app and a mobile viewport beforehand, checking for layout shifting, pixelation, or broken spacing across devices.