Embedding Guidebeehiiv

How to Embed a Widget in beehiiv

beehiiv is a newsletter platform that supports custom HTML blocks in its post editor. You can add an iframe to the HTML block, but there is an important distinction: iframes render on the web archive version of your newsletter but are stripped from email delivery by most email clients. This guide covers both the HTML block approach for web readers and the CTA button approach for email subscribers.

Email client limitation

Most email clients (Gmail, Outlook, Apple Mail, Yahoo Mail) strip iframes from HTML emails for security reasons. This is not a beehiiv limitation -- it is an industry-wide email standard. Your iframe will work on beehiiv's web archive page but will not render in the email itself. Use a CTA button or image link for email readers.

1. Prerequisites

1An active Embeddy account with at least one published widget.
2A beehiiv account at beehiiv.com.
3Your Embeddy iframe embed code and direct widget URL from your dashboard.

2. How beehiiv Handles HTML

beehiiv's post editor is a block-based editor. Among the available blocks is the HTML block, which lets you insert custom HTML code. This HTML is included in both the web archive version of your post and the email version, but email clients may strip unsupported elements.

beehiiv also supports embed blocks for specific providers (YouTube, Twitter, etc.), but there is no generic iframe embed block. The HTML block is the way to add custom iframe code.

3. Email vs. Web Archive

Web Archive (works)

When readers view your post on beehiiv's web archive (the browser version), iframes in HTML blocks render normally. Your Embeddy widget will be fully interactive.

Email Delivery (limited)

When the newsletter is delivered as an email, most email clients strip iframes entirely. The widget will not appear in the email. Use a CTA button or image link instead.

For the best experience, we recommend using both methods: an HTML block with the iframe for web archive readers, and a CTA button linking to the widget for email readers.

4. Method 1: HTML Block (Web Archive)

This method embeds your widget on the web archive version of your beehiiv newsletter post.

1
Open the beehiiv post editor.
Log in to beehiiv, go to Posts, and create a new post or open a draft.
2
Add an HTML block.
Click the + button on a new line in the editor, then select HTML from the block menu. This opens a code input area.

Paste your Embeddy iframe code.

Paste the following code into the HTML block:

<div style="width:100%;max-width:600px;margin:20px auto;text-align:center;">
  <iframe
    src="https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID"
    width="100%"
    height="500"
    frameborder="0"
    style="border:none;border-radius:8px;"
    allowfullscreen>
  </iframe>
  <!-- Fallback for email clients that strip iframes -->
  <noscript>
    <a href="https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID">
      View the interactive widget
    </a>
  </noscript>
</div>

Replace WIDGET_ID and PROPS_ID with your actual values from the Embeddy dashboard.

4
Preview in web view.
Use beehiiv's preview feature and check the Web view to confirm the iframe renders. The Email preview will likely show a blank space where the iframe should be.

5. Method 2: CTA Button Link (Email-Safe)

For email readers, the most reliable approach is a CTA button or linked image that opens the widget in a new browser tab.

1
Add a Button block in the beehiiv editor.
Click + and select Button. Set the button text to something like "Try the Interactive Widget" or "Open Widget".
2
Set the button link to your Embeddy widget URL.
Paste your widget's direct URL as the button link:
https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID
3
Style the button and publish.
Customize the button colors to match your newsletter's branding. This button will work in both the email and web archive versions.

Best practice: combine both methods

Add the HTML block (Method 1) for an inline widget experience on the web archive, and add a CTA button (Method 2) above or below it for email readers. This way, all readers can access your widget regardless of how they view your newsletter.

6. Troubleshooting

Widget missing in email preview

This is expected. Email clients strip iframes from HTML emails. Use a CTA button link (Method 2) to give email readers access to your widget.

HTML block not rendering in editor

beehiiv's editor may not render the iframe in real-time during editing. Use the Preview button and check the Web view to see the rendered output.

Widget appears too small on mobile

Set width="100%" and use a reasonable fixed height (e.g., 400-500px). The max-width on the container div will prevent it from exceeding the newsletter column width.

7. FAQ

Will iframes work in beehiiv emails?

No. Iframes are stripped by virtually all email clients (Gmail, Outlook, Apple Mail, Yahoo). This is an email industry standard, not specific to beehiiv. Iframes only work on beehiiv's web archive pages.

Can I use beehiiv's embed block for Embeddy widgets?

beehiiv's embed block supports specific providers like YouTube and Twitter. It does not support arbitrary URLs. Use the HTML block instead for custom iframe embeds.

Does beehiiv's HTML block support JavaScript?

beehiiv's HTML block supports basic HTML and inline styles. JavaScript may be limited or stripped in some contexts. Since your Embeddy widget runs inside an iframe, it does not need JavaScript in the parent page -- the iframe source handles all interactivity.

Ready to embed your widget in beehiiv?

Build and publish your widget in minutes with embeddy.ai -- then share it with your newsletter audience.

Open Dashboard Browse All Docs