Embedding GuideButtondown

How to Embed a Widget in Buttondown

Buttondown is a minimalist newsletter platform that supports Markdown and HTML in its email editor. You can include an iframe in your newsletter's HTML, but like all email platforms, iframes are stripped by email clients during delivery. The iframe will render on Buttondown's web archive page. For email subscribers, use a styled CTA link that opens the widget in their browser.

Email client limitation

Email clients (Gmail, Outlook, Apple Mail, Yahoo Mail) strip iframes from HTML emails. This is an industry-wide email standard, not a Buttondown limitation. Your iframe will only render on Buttondown's web archive. For the email itself, use a link or button.

1. Prerequisites

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

2. How Buttondown Handles HTML

Buttondown's editor supports both Markdown and raw HTML. You can switch between Markdown and HTML modes in the editor settings. When writing in Markdown mode, you can still include inline HTML (including iframes), and Buttondown will preserve it.

Buttondown also publishes each email to a web archive page that is publicly accessible via a URL. On this web page, iframes and other HTML elements render normally since it is a standard web page, not an email.

Buttondown supports custom CSS for your newsletter, which means you can style your embed containers, CTA buttons, and link text to match your newsletter's design.

3. Email vs. Web Archive

Web Archive (works)

Buttondown's web archive renders your email as a standard web page. Iframes, JavaScript, and all HTML elements work normally. Your Embeddy widget will be fully interactive here.

Email Delivery (limited)

When delivered as an email, iframes are stripped by email clients. Your widget will not appear inline in the email. Use a CTA link to direct subscribers to the widget.

Tip: encourage web archive viewing

Add a note at the top of your email: "This email contains an interactive widget. If it does not display below, view in browser." Buttondown automatically includes a "View in browser" link that opens the web archive version.

4. Method 1: Web Archive Iframe

Include the iframe in your email's HTML so it renders on the web archive page.

1
Open the Buttondown editor.
Log in to Buttondown and click New email or open a draft.

Write your content and add the iframe.

In Markdown mode, you can include inline HTML. Add your Embeddy iframe where you want the widget:

Here's an interactive widget for you to explore:

<div style="width:100%;max-width:600px;margin:20px auto;">
  <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>
</div>

**Can't see the widget above?**
[Click here to open it in your browser](https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID)

Replace WIDGET_ID and PROPS_ID with your actual values. The fallback link below the iframe ensures email readers can still access the widget.

3
Preview and send.
Use Send preview to send a test email to yourself. Check both the email (for the fallback link) and the web archive page (for the interactive iframe).

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

For the email version, create a visually prominent CTA link that subscribers can click to open your widget in their browser.

Add a styled HTML button in your email.

Use inline-styled HTML for maximum email client compatibility:

<div style="text-align:center;margin:24px 0;">
  <a href="https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID"
     style="display:inline-block;
            background-color:#7c3aed;
            color:#ffffff;
            font-weight:bold;
            font-size:16px;
            padding:14px 28px;
            border-radius:8px;
            text-decoration:none;">
    Try the Interactive Widget
  </a>
</div>

2
Or use a simple Markdown link.
If you prefer Markdown simplicity:
[Open the Interactive Widget](https://embeddy.ai/webhost/WIDGET_ID?widget_props_id=PROPS_ID)

Best practice: combine both methods

Include the iframe for web archive readers and a styled CTA link below it for email readers. This dual approach ensures every subscriber can access your widget regardless of how they read your newsletter.

6. Troubleshooting

Iframe not showing in email

This is expected behavior. Email clients strip iframes for security. The iframe will only render on the web archive page. Include a fallback link for email readers.

HTML not rendering in editor preview

Buttondown's in-editor preview may not render iframes. Send a preview email to yourself and also check the web archive URL to verify the iframe works correctly.

CTA button styling broken in some email clients

Use inline styles only (no CSS classes) for maximum compatibility. The HTML button example above uses inline styles which work in Gmail, Outlook, Apple Mail, and most other clients.

7. FAQ

Does Buttondown support HTML in emails?

Yes. Buttondown supports Markdown with inline HTML, and you can also write entirely in HTML mode. However, email client support for specific HTML elements varies -- iframes are stripped by all major email clients.

Will the iframe work on the Buttondown web archive?

Yes. Buttondown's web archive renders your newsletter as a standard web page. Iframes, JavaScript, and all HTML elements work normally on the archive page.

Can I use Buttondown's API to include iframes programmatically?

Yes. Buttondown has a comprehensive API that accepts HTML content for email bodies. You can include iframe code in your API request, and it will be preserved in the web archive. The same email client iframe restriction applies to emails sent via the API.

Can I embed the widget on my Buttondown custom domain landing page?

Buttondown's custom domain feature is for the web archive and subscription pages. If you have a custom domain set up, the web archive pages (with working iframes) will be served from your domain. For a fully custom landing page with the widget, consider using your own website and linking to it from your newsletter.

Ready to share your widget via Buttondown?

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

Open Dashboard Browse All Docs