<commit_before>---
title: "Pseudo-HTML and Pidgin CSS: Building an Email Newsletter"
published_at: 2017-07-28T17:35:07Z
hook: Finding a backend and building a toolchain for
  sending an email newsletter. Realizations that
  standardization in email HTML and CSS is a distant dream.
---

After a recent trip to Portland, I decided to start writing
a newsletter. I don't post on Facebook very often and am
not very good at staying in touch with friends and family,
so a curated message that I could send every so often
describing what I'm up to seemed like a good way to help
with that problem. I've been a subscriber to a few high
quality newsletters from other people for years, and
reading them has always been something that I've enjoyed.

I also like the idea of supporting the independent web. I'm
one of the holdouts who refuses to move to a centralized
publishing service, or publish content exclusively a social
network. Bloggers used to have a powerful distribution
channel in the form of RSS, and although the technology
still exists today, but it's been fading for years, with
more and more people moving exclusively towards their
favorite social platform for content discovery. Email is a
flawed technology in many ways, but it's one of the few
communication channels that every connected person in the
can reliably be expected to have, and it fully supports
content more than 140 characters long and rich media over
open standards.

This post contains nothing revelatory, but describes a few
of the building blocks I used to build a modern newsletter,
and some of the surprises along the way.

## The right shape of service (#service)

Initially I assumed that the best way to go would be
through one of the many newsletter services like MailChimp
or TinyLetter. Maybe it is, but in all the cases I looked
at they either wanted to paste a branded footer on the end
of all messages, have you use a WYSIWYG editor, or both;
aspects that I'm pretty allergic to. I also wanted to
archive old copies on the web somewhere, and it was looking
like I'd have to reinvent a custom layer on top of whatever
service I ended up using anyway.

I sure wasn't about to start sending email myself, so I
still wanted to use a service, but kept looking for one
that exposed the right primitives for me. I wanted perfect
control over the visuals, but to fully offload subscription
management to someone else.

After a little more Googling I discovered that Mailgun
offered an API for mailing lists. I've been using them for
sending mail for years at Heroku, then at Stripe, and have
always found their service to be well-designed and
reliable. I poked around their control panel for a while
and experimented by sending a few messages to myself with
their Go SDK, and it was off to the races.

!fig src="/assets/newsletters/passages-001.png" caption="The first issue of Passages & Glass successfully rendering in Google Mail (after considerable pain)."

## Pidgin CSS (#css)

Over the last few decades, we've had pretty good success in
standardizing how HTML and CSS are rendered across
browsers, and during the time some huge victories were won.
Progressively more sophisticated tests like Acid2 and Acid3
helped drag browsers up to spec and establish widespread
consistency, and even hopeless stragglers like IE would
eventually fall in line. I'd naively believed that this was
a war that had been won, only to realize that this whole
time there's been a battle raging on the frontier of email.

Email clients are a million miles away from rendering
anything that's even remotely compliant with anything, and
they're all uncompliant in their own exotic ways. Some
clients are better than others, and somewhat ironically the
companies that we tend to think of as the most advanced in
the world are some of the most regressive, like Google. If
you threw Acid2 at Google Mail for example, you'd be lucky
to see a lone yellow pixel on screen.

The newsletter industry has dealt with this sad state of
affairs by developing a form of pidgin CSS made up of the
lowest common denominator of what the world's diverse set
of clients will handle. [This CSS support<commit_msg>"For example" isn't adding a whole bunch here<commit_after>---
title: "Pseudo-HTML and Pidgin CSS: Building an Email Newsletter"
published_at: 2017-07-28T17:35:07Z
hook: Finding a backend and building a toolchain for
  sending an email newsletter. Realizations that
  standardization in email HTML and CSS is a distant dream.
---

After a recent trip to Portland, I decided to start writing
a newsletter. I don't post on Facebook very often and am
not very good at staying in touch with friends and family,
so a curated message that I could send every so often
describing what I'm up to seemed like a good way to help
with that problem. I've been a subscriber to a few high
quality newsletters from other people for years, and
reading them has always been something that I've enjoyed.

I also like the idea of supporting the independent web. I'm
one of the holdouts who refuses to move to a centralized
publishing service, or publish content exclusively a social
network. Bloggers used to have a powerful distribution
channel in the form of RSS, and although the technology
still exists today, but it's been fading for years, with
more and more people moving exclusively towards their
favorite social platform for content discovery. Email is a
flawed technology in many ways, but it's one of the few
communication channels that every connected person in the
can reliably be expected to have, and it fully supports
content more than 140 characters long and rich media over
open standards.

This post contains nothing revelatory, but describes a few
of the building blocks I used to build a modern newsletter,
and some of the surprises along the way.

## The right shape of service (#service)

Initially I assumed that the best way to go would be
through one of the many newsletter services like MailChimp
or TinyLetter. Maybe it is, but in all the cases I looked
at they either wanted to paste a branded footer on the end
of all messages, have you use a WYSIWYG editor, or both;
aspects that I'm pretty allergic to. I also wanted to
archive old copies on the web somewhere, and it was looking
like I'd have to reinvent a custom layer on top of whatever
service I ended up using anyway.

I sure wasn't about to start sending email myself, so I
still wanted to use a service, but kept looking for one
that exposed the right primitives for me. I wanted perfect
control over the visuals, but to fully offload subscription
management to someone else.

After a little more Googling I discovered that Mailgun
offered an API for mailing lists. I've been using them for
sending mail for years at Heroku, then at Stripe, and have
always found their service to be well-designed and
reliable. I poked around their control panel for a while
and experimented by sending a few messages to myself with
their Go SDK, and it was off to the races.

!fig src="/assets/newsletters/passages-001.png" caption="The first issue of Passages & Glass successfully rendering in Google Mail (after considerable pain)."

## Pidgin CSS (#css)

Over the last few decades, we've had pretty good success in
standardizing how HTML and CSS are rendered across
browsers, and during the time some huge victories were won.
Progressively more sophisticated tests like Acid2 and Acid3
helped drag browsers up to spec and establish widespread
consistency, and even hopeless stragglers like IE would
eventually fall in line. I'd naively believed that this was
a war that had been won, only to realize that this whole
time there's been a battle raging on the frontier of email.

Email clients are a million miles away from rendering
anything that's even remotely compliant with anything, and
they're all uncompliant in their own exotic ways. Some
clients are better than others, and somewhat ironically the
companies that we tend to think of as the most advanced in
the world are some of the most regressive, like Google. If
you threw Acid2 at Google Mail, you'd be lucky to see a
lone yellow pixel on screen.

The newsletter industry has dealt with this sad state of
affairs by developing a form of pidgin CSS made up of the
lowest common denominator of what the world's diverse set
of clients will handle. [This CSS support
{'fraction_non_alphanumeric': 0.029383545214679778, 'fraction_numerical': 0.005516910530103142, 'mean_word_length': 4.464613368283093, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2735422', 'n_tokens_mistral': 2155, 'n_tokens_neox': 1980, 'n_words': 1404}