Open-source project
premailer/premailer avatar
premailer/premailer

Premailer inlines CSS through a private attribute namespace and warns per client

Preflight for HTML email

2,417 stars366 forksRubyNOASSERTION

At a glance

What is it?
A Ruby gem that converts stylesheet rules into inline style attributes for HTML email, resolves relative asset paths, and flags each unsupported property against the clients that will break. The interesting parts are the table attribute tricks, the adapter choice, and a CSS variable workaround whose prose contradicts its own command.
Who is it for?
Premailer fits a Ruby or Rails team sending HTML email that has outgrown a hand written inline stylesheet, and who want to know which client will object to which declaration. Four things to check before you adopt it.
Can I use it commercially?
Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
Is it still maintained?
Yes. The repository last received commits 12 days ago.
What is it written in?
Mainly Ruby, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • premailer/premailer2,417 ★ · +1
Star history
Repository2026-09-302026-11-15
premailer/premailer2.4k2.4k

1 Stars in the last 46 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A private CSS namespace becomes legacy table attributes

The most distinctive thing about the gem is a small private namespace in CSS that maps onto the HTML attributes email clients actually honour.

There are six of them. A width attribute applies to table, header and data cells. A height attribute applies to tables, rows, header and data cells. Cell padding and cell spacing apply to tables. An align attribute applies to tables. And a data attribute set to ignore, usable on link and style elements, tells the gem to leave that element entirely alone.

Each declaration is copied to the corresponding element's attribute, so this:

css
table { -premailer-cellspacing: 5; -premailer-width: 500; }

becomes this:

html
<table cellspacing='5' width='500'>

That is the whole reason the gem exists in this shape. Inline style is what clients support for most properties, but the table properties are the long standing exception, and a stylesheet rule that sets them is silently dropped by several clients. Writing them as attributes is the only route that works, and the private prefix is what lets an author write them in a stylesheet at all.

The ignore attribute is the escape hatch, and it is the more useful of the two mechanisms for a real project: it says this particular link or style element should be passed through untouched rather than processed.

Note which elements each one covers. The height attribute is the only one that includes rows, and cell padding is not available on header or data cells at all, which is a limitation of the mapping rather than of the clients.

Warnings name the clients that will break the rule

The second capability is the one that makes the gem useful in a build rather than in a script you run once.

Stylesheet properties are checked against email client capabilities, and the basis for that list is the guides published by the Email Standards Project rather than a measurement the gem performs. The example passes a warning level when constructing the transform, and then walks the collected warnings and prints three fields from each: the message, the level, and the clients.

So the output is not a generic warning. It tells you which declaration is unsupported and which clients will not honour it, which is the difference between a warning you can act on and one you have to research.

ruby
premailer.warnings.each do |w|
  puts "#{w[:message]} (#{w[:level]}) may not render properly in #{w[:clients]}"
end

The warning level in the example is a named safe setting. That implies a scale rather than a flag, so a stricter setting probably turns noisier properties into errors, and the available levels are not enumerated on the page.

There is a matching option on the transform itself, named for dropping CSS rules that cannot be merged. That is the same problem solved by omission instead of by warning: instead of telling you a rule will be lost, the gem drops it. Both behaviours exist, and which you want depends on whether a missing declaration should fail a build or produce a note.

The configuration example shows the two options that matter most for a Rails integration, one for passing the HTML as a string rather than a URL, and the unmergeable rules one.

The plain text version has to be extracted before the inline CSS

There is an ordering constraint in the example, and it is there because of how the transform works.

The comment in the code says the plain text output must come before the inline CSS step. That makes sense once you know that the inline step mutates the document: once every rule has been moved into style attributes, the structure that the text extractor walks has changed, and you extract from a transformed tree rather than the one you wrote.

ruby
premailer = Premailer.new('http://example.com/myfile.html', warn_level: Premailer::Warnings::SAFE)

# Write the plain-text output (must come before to_inline_css)
File.write "output.txt", premailer.to_plain_text

# Write the HTML output
File.write "output.html", premailer.to_inline_css

The text conversion inlines links and images, so an image link with no text becomes the image's alternative text followed by the URL in brackets. The example on the page shows an empty anchor turning into a label and a parenthesised URL, which is the behaviour you want in a text alternative and would not get from a naive strip.

The other half of the feature is the opt out, which is more useful than the conversion itself. Wrapping any section in a pair of comments marked as text and html start and end removes that section from the text version entirely, and the page names the use case: stripping the email header and footer that only make sense in the rendered version.

That marker pair is a convention this gem invented rather than a standard, so it is a dependency between your templates and this library. If you switch to a different plain text generator you lose those exclusions, and if you move content inside the markers without realising it, the text version silently loses it too.

Three parsers, one removed with a version pin

The parser is pluggable and the choice is made by assigning a symbol.

ruby
Premailer::Adapter.use = :nokogiri_fast

Three adapters are offered. The default is one of the standard HTML parsers, which is the conservative choice. A second is described as twenty times faster at the cost of more memory, which is the trade you would expect for a parser with a different implementation strategy. The third is a parser built on a browser grade engine, which handles malformed markup the way a browser would.

One adapter has already gone. The hpricot adapter was removed, and the note tells you what to do if you need it: pin the gem to that older version line. That is a clean deprecation, and it is also a warning about the other two. A gem whose parsing layer is swappable will eventually move you off whichever adapter you chose, and the escape hatch is a version pin rather than a migration.

The speed claim is the one number on the page with nothing behind it. There is no benchmark, no input document and no memory figure, only the ratio and the parenthetical about memory. For a gem that runs in a request path that is tolerable, since the work is proportional to document size and newsletter HTML is small. For one running over a large template on every send, it is worth measuring on your own markup rather than trusting the ratio.

There is one more parser-related question the page declines to answer on itself. Which Ruby versions are tested is answered by pointing at a continuous integration workflow file rather than by a compatibility table, and support for JRuby is described as close, with contributors welcome.

CSS variables pass through untouched, and the documented fix is an asset pipeline step

This is the longest section on the page and it is a workaround, which tells you the gem does not resolve variables for you.

The gem does not replace CSS variables with their static values. The example shows a heading whose inline style keeps the font weight as a variable reference, and the consequence is stated plainly: the value in the output is the variable call rather than its value. In an email client there is no custom property resolution to rely on, so that declaration is lost.

The fix is to resolve the variables before the gem runs, with a PostCSS plugin, and the page then walks through the whole Rails setup. Install the plugin alongside a CSS preprocessor and a command line runner. Create a configuration file at the project root with the plugin in its list and the preserve option set to false, which is what tells it to substitute rather than keep the original. Add a script to the package manifest that runs the preprocessor on your email stylesheet and writes the result to the built assets. Then add a line to the development process file so the same script runs in watch mode when the dev server starts.

The stylesheet variant and the preprocessor variant are given as two versions of that script, and the second one is worth reading carefully: it compiles the preprocessor source into the built path and then runs the variable substitution over the built path, writing its output back to the same path it just read. A tool that reads and writes the same file in one command line is a script that works until it does not, and it is the kind of thing to keep an eye on if the build is shared with other processes.

The caveat at the end is the one that will bite. Variables must be declared before use, or their values when called are set to undefined.

The prose says one output path and the command writes another

There is a small documentation error in that workaround, and it is the kind that costs an afternoon.

The command for the plain stylesheet case passes an input path and an output path that are different directories, sending the processed file to the built assets folder. The sentence immediately below it says the script processes and overwrites the file in the stylesheets folder itself.

Both cannot be true. The output flag wins, because that is what the tool does with the path you give it, and the sentence describing an in-place overwrite is the incorrect one. The consequence is that a reader who trusts the prose will look for a modified file in the wrong place, conclude the build did nothing, and go looking for a configuration error that does not exist.

It is a one sentence fix and it is worth reporting rather than working around, because the same paragraph is the reference documentation for the most commonly needed repair to this pipeline.

The page has a few smaller editorial marks of the same kind. The sentence introducing the script that can be run on its own misspells script, and a line break tag is left unclosed after the package manifest instruction. Neither matters, but together with the output path error they are a fair signal about how carefully this section is maintained relative to the rest of the readme, which is precise.

The earlier sections, by contrast, are exact: the attribute table names an element for every declaration, the warning loop shows the three fields it prints, and the plain text markers are shown as a complete pair.

No release tags, and contributors are told not to bump the version

The release story is unusual enough to mention before anything else about the project.

The repository publishes no GitHub releases. Versions are gem versions, released to the package registry, and the newest one is not stated on the page. The only version number that appears anywhere in the readme is inside the credits, where one company is thanked for sponsoring some of the 1.5.6 updates, which dates the last named release to a version well below where the project is likely to be now.

Given that, the readme's own instruction to contributors is the important line: please do not increment the version numbers. The maintainer owns the version, which is a reasonable arrangement for a gem with a long history, and it means a pull request that bumps a version will be rejected on process grounds before its code is read.

The same section lists the two areas that most need work, and both are concrete. Improved test coverage. And moving repeated background images defined in CSS for Outlook, which is the one thing the attribute mapping cannot express: a background image repeated across cells has to be turned into per element attributes, and the gem does not do it yet.

The provenance note is unusually candid for a project of this age. It says the code was rotting away in a private version control repository for too long and could use some attention, which dates the project's history back past its public repository, and the copyright line covers 2007 to 2017.

That same closing line is where the licence question lives. The repository's licence field reports no recognised licence, and the readme attributes copyright to an individual for that year range while pointing at a licence file for the details without naming the licence in the text. If you need to know what you are licensing from, the file is the source, not this page.

Editorial conclusion

Premailer fits a Ruby or Rails team sending HTML email that has outgrown a hand written inline stylesheet, and who want to know which client will object to which declaration. Four things to check before you adopt it. That you accept no type checking and no validation, because this transforms markup and nothing more. Which parser you want, since the fast adapter is described as twenty times quicker on the cost of more memory, and one adapter has already been removed with a version pin for people who still need it. Whether your CSS variables will survive, because they are not resolved, and the documented fix is a separate build step in your asset pipeline with an ordering requirement. And which clients you actually care about, since the warnings are only as useful as the list behind them, which the gem takes from a third party's guides rather than measuring itself.

Frequently asked questions

What does the premailer gem do?

It converts CSS into inline style attributes for HTML email, keeping existing inline attributes and processing both style elements and linked stylesheets. It also converts relative paths to absolute in link targets, image sources and CSS url values, checks properties against email client capabilities based on the Email Standards Project's guides, and can generate a plain text alternative.

How do I handle CSS variables with premailer?

You resolve them before the gem runs, because it does not replace variables with their static values. The documented route is a PostCSS plugin configured with the preserve option set to false, wired into your asset pipeline so the email stylesheet is processed into the built assets, and optionally run in watch mode from your development process file. Variables must be declared before use, or they resolve to undefined.

Which HTML parsers can premailer use?

Three adapters are offered: one standard parser as the default, one described as twenty times faster using more memory, and one built on a browser grade engine. The hpricot adapter was removed, and the page directs anyone who needs it to an older version line. The adapter is chosen by assigning a symbol to the adapter setting.

What are the premailer specific CSS attributes?

Six: prefixed width and height declarations that map onto table, row and cell attributes, prefixed cell padding and cell spacing for tables, a prefixed align declaration for tables, and a data attribute set to ignore that makes the gem skip a link or style element entirely. Each prefixed declaration is copied to the corresponding element attribute, so a table declaration becomes a table tag carrying the legacy cellspacing and width attributes.

Does premailer support Ruby on Rails?

The readme documents the asset pipeline steps for a Rails application rather than a Rails integration, including a script added to the package manifest and a line for the development process file so the stylesheet is rebuilt in watch mode. Which Ruby versions are tested is answered by pointing at the continuous integration workflow file, and JRuby support is described as close rather than complete.

Official sources

  1. Issues
  2. premailer/premailer on GitHub
  3. Project website
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/premailer-premailer.svg)](https://hysenlabs.com/projects/premailer-premailer)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/premailer-premailer.svg)](https://hysenlabs.com/projects/premailer-premailer)

Was this useful?