inline-email

An open source library that compiles HTML and CSS into email-safe templates and renders them per send. You'll see it if you use my contact form and I reply.

project · active since 2018 · updated 7 Nov 2026
~/dansabin.com — chat Ask about this project

Isn't email a solved problem?

It should be. An email should simply be a template and data. It isn't, because some email clients drop <style> blocks or ignore modern layout CSS, so the CSS has to be inlined and the layout built from tables. Images have their own catch: in some clients an image linked by URL shows only if the reader opts in, so an image that matters can be embedded in the email instead.

Does every option do what it says?

Version 3's command line set image embedding on by default, and its help offered one flag to turn it off: --noInlineImages, "Disable image web resource inlining." You can still read that line with npx inline-email@3.0.1 --help.

When I moved the renderer to Handlebars for version 4, the work ran in small batches built by AI agents, with a reviewer agent reading each one against the design as it went. Early on, the CLI's image flag was being rewired, and the reviewer tried it on one of the repository's own images. The image came back as a link. The library had been calling the part of juice that inlines CSS, and the part that fetches images was never reached. Going back through the history, the agent running the build put it plainly: "no user has ever had inlining from this CLI."

It laid out two ways forward.

Two ways forward for the CLI's image flag Two paths lead from the CLI's image flag. Drop the flag: the email holds the image as a link to its image host, images stay links, it takes removing the flag and saying so in the docs, and with images off nothing changes. Make it work: the image host's image is embedded in the email when the template compiles, images are embedded when asked, it takes about twenty lines and a test with a local image, and with images off nothing changes, byte for byte. the CLI's image flag DROP THE FLAG EMAIL a link image host WHAT A SENDER GETS Images stay links WHAT IT TAKES Remove the flag and say so in the docs WITH IMAGES OFF No change MAKE IT WORK EMAIL embedded image host compile WHAT A SENDER GETS Images embedded when asked WHAT IT TAKES About twenty lines and a test with a local image WITH IMAGES OFF No change, byte for byte Two ways forward for the CLI's image flag Two paths lead from the CLI's image flag. Drop the flag: the email holds the image as a link to its image host, images stay links, it takes removing the flag and saying so in the docs, and with images off nothing changes. Make it work: the image host's image is embedded in the email when the template compiles, images are embedded when asked, it takes about twenty lines and a test with a local image, and with images off nothing changes, byte for byte. the CLI's image flag DROP THE FLAG EMAIL a link image host WHAT A SENDER GETS Images stay links WHAT IT TAKES Remove the flag and say so in the docs WITH IMAGES OFF No change or MAKE IT WORK EMAIL embedded image host compile WHAT A SENDER GETS Images embedded when asked WHAT IT TAKES About twenty lines and a test with a local image WITH IMAGES OFF No change, byte for byte
The two ways forward. Dropping the flag leaves each image a link to its image host. Making it work embeds the image in the email when the template compiles, for about twenty lines and a test with a local image. With images off, neither changes the email.

I wanted inline images, so I asked to work out why it was broken before choosing a fix, and took the second.

The fix went into the same batch with its tests, and the next batch started that evening.

What a sender gets, counted on an email with three images:

Version and setting Images embedded
3.0.1, embedding on by default 0 of 3
4.1.2, without --inlineImages 0 of 3
4.1.2, with --inlineImages 3 of 3

Why it came up while building

Each batch gets a reviewer agent that reads the change against the design and against the code it calls, and runs what it can. So the question about images came up while that code was open, with the fix one step away.

What holds it now

Five tests keep the count where it is: images stay links without the flag, they are embedded with it, an unreachable image is skipped by default, the compile fails on one under webResources.strict, and a guide's script embeds its image.

What it cost, and where it stops

None of it reached a release: 4.0.0 shipped with embedding working. Finding it took one try with a real image. Fixing it took one design change, one extra step in the code, and about twenty minutes from my answer to a reviewed batch. The longest part was the hour it waited on me. Images are embedded when the template compiles, so one whose src is a placeholder such as {{logoUrl}} can't be. And the count says the image is in the email, not that every client shows it. There's no test against real email clients such as Gmail or Outlook.

See it for yourself

contact form →

Send me a message through the contact form on this site. inline-email builds the email, and when I reply, your message comes back quoted under mine in the template it built. Nothing in it names the library, and some mail clients fold quoted text away, so you may need to expand it.

A library and a CLI that compile HTML and CSS into email-safe templates once, then render them with Handlebars and your data for each send. You get back a subject, HTML and plain text for whatever sends your email. It goes back to a transactional email service I built at Apple, which went on to send email for dozens of internal teams and projects. Outside Apple I needed far less. I built what was needed: a lightweight primitive I could embed in any application.

It's not particularly fancy nor does it have any impressive IP, but it's a tool that helps encapsulate a complex problem with a simple interface.

The choices behind it

Handlebars instead of my own renderer, because we don't want to reinvent the wheel. Broken images over failed sends: an unreachable image is skipped unless you set juice.webResources.strict, because if an image host dies, we cannot have all their email workflows crash. And Inky as an option, not a rival: Inky is a flavor of how. My own tags are another option.

Who it's for

package on npm ↗

People who see email as a necessary part of their product, worry about dependency bloat, and don't want to build on juice from scratch. The code is open source on GitHub, MIT licensed, and the package is on npm.

Read next

Testing. Why I cut tests when an AI can write as many as I want.

Projects. Things I have built, with the decisions behind them.

Want the details?

Ask the window anything this page skips.