Designing your email

Buttondown is fairly opinionated about the best emails being plain-text friendly and minimal, but it offers you a variety of ways to customize your email through HTML and CSS.

Most email clients don't support the wide variety of HTML and content that you can see on the web.

Things like <iframe> elements, embedded videos, or custom layouts and fonts are hard if not impossible to replicate in the limited confines of your average inbox. This isn't a Buttondown limitation; it's a Gmail (or whomever) one.

A brief (and inexhaustive) list of things that emails won't be able to handle:

JavaScript is a programming language that makes web content interactive. It's common in websites, but the vast majority of email clients block scripts since they can hide malicious content. Avoid all JavaScript.

An <iframe> (inline frame) is an HTML element that embeds content from one website into another. Inline frames are often used to insert advertisements, video, audio, or forms in other websites. Iframes often contain scripts, so most email clients block them.

Autoplay and click-to-play media won't play in an inbox unless your subscriber's email client supports HTML5 <video> and <audio> tags. Only one major email client, Apple Mail, supports these tags, so it's best to avoid embedded media.

Instead, we recommend using one of our integrations to host your audio and video! We have integrations with Youtube, Vimeo, Soundcloud and Bandcamp that make it easy to share with your readers.

While SVGs are great for sharp, scalable images on the web, most email clients don't fully support them. Some will fail to render the image entirely, while others may strip or alter it for security reasons. For best results, use standard image formats like PNG or JPEG instead.

Forms and interactive content is impossible in email.

Unfortunately, the CSS standard that Gmail and other clients are working off of is fairly old. You'll want to extensively test any custom CSS you are using to make sure it plays nice with many browsers; when in doubt, default to CSS that worked in, say, 2005.

Buttondown comes with two default templates: Classic and Modern.

The Classic template is simple, functional, and minimalist. Did we mention that it's in plain text? This template puts the emphasis on your content.

Here's how the Classic template looks:

You can review the CSS for the Classic template here.

The Modern theme is still clean and accessible, but does more to emphasize your newsletter's branding.

Here's how the Modern template looks:

You can review the CSS for the Modern template here, and below are some common classes and targets you might want to style: