https://github.com/premailer/premailer

Preflight for HTML email
https://github.com/premailer/premailer

Keywords

css inline mail nokogiri premailer ruby

Keywords from Contributors

activerecord activejob mvc rubygems rubocop css-parser rack code-formatter static-code-analysis crash-reporting

Last synced: about 2 hours ago
JSON representation

Repository metadata

Preflight for HTML email

Host: GitHub
URL: https://github.com/premailer/premailer
Owner: premailer
License: other
Created: 2009-11-26T05:31:46.000Z (over 16 years ago)
Default Branch: master
Last Pushed: 2026-02-24T19:00:41.000Z (7 days ago)
Last Synced: 2026-02-27T10:50:59.840Z (4 days ago)
Topics: css, inline, mail, nokogiri, premailer, ruby
Language: Ruby
Homepage: https://premailer.github.io/premailer
Size: 1010 KB
Stars: 2,401
Watchers: 54
Forks: 362
Open Issues: 97
Releases: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md

Premailer README

What is this?

For the best HTML e-mail delivery results, CSS should be inline. This is a
huge pain and a simple newsletter becomes un-managable very quickly. This
gem is a solution.

CSS styles are converted to inline style attributes
- Checks style and link[rel=stylesheet] tags and preserves existing inline attributes
Relative paths are converted to absolute paths
- Checks links in href, src and CSS url('')
CSS properties are checked against e-mail client capabilities
- Based on the Email Standards Project's guides
A plain text version is created (optional)

Installation

gem install premailer

Example

require 'premailer'

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

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

Adapters

nokogiri (default)
nokogiri_fast (20x speed, more memory)
nokogumbo

(hpricot adapter removed, use ~>1.9.0 version if you need it)

Picking an adapter:

Premailer::Adapter.use = :nokogiri_fast

Ruby Compatibility

See .github/workflows/actions.yml for which ruby versions are tested. JRuby support is close, contributors are welcome.

Premailer-specific CSS

Premailer looks for a few CSS attributes that make working with tables a bit easier.

CSS Attribute	Availability
-premailer-width	Available on `table`, `th` and `td` elements
-premailer-height	Available on `table`, `tr`, `th` and `td` elements
-premailer-cellpadding	Available on `table` elements
-premailer-cellspacing	Available on `table` elements
-premailer-align	Available on `table` elements
data-premailer="ignore"	Available on `link` and `style` elements. Premailer will ignore these elements entirely.

Each of these CSS declarations will be copied to appropriate element's attribute.

For example

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

will result in

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

Plain text version

Premailer can generate a plain text version of your HTML. Links and images will be inlined.

For example

<a href="https://example.com" >
  <img src="https://github.com/premailer.png" alt="Premailer Logo" />
</a>

will become

Premailer Logo ( https://example.com )

To ignore/omit a section of HTML content from the plain text version, wrap it with the following comments.

<!-- start text/html -->
<p>This will be omitted from the plain text version.</p>
<p>
  This is extremely helpful for <strong>removing email headers and footers</strong>
  that aren't needed in the text version.
</p>
<!-- end text/html -->

Configuration options

For example:

Premailer.new(
  html, # html as string
  with_html_string: true,
  drop_unmergeable_css_rules: true
)

available options

Support for CSS variables

The gem does not automatically replace CSS variables with their static values.

For example, if a variable is used to set the font-weight of an h1 element, the result will be

<h1 style="
  font-size:3rem;
  font-weight:var(--bulma-content-heading-weight);">
  Title</h1>

This causes the font-weight value to be the CSS variable call var(--bulma-content-heading-weight); instead of its static value.

Replace CSS variable calls with their static values

The following section instructs how to replace CSS variables with their static value in the context of a Ruby on Rails application.

Install the postcss-css-variables plugin for PostCSS to process the CSS variables.

yarn add postcss postcss-cli postcss-css-variables

To configure the plugin, create the file postcss.config.js in the root directory with the content:

module.exports = {
    plugins: [
        // https://github.com/MadLittleMods/postcss-css-variables to transform the css
      require("postcss-css-variables")({
        preserve: false, // Set to false to replace variables with static values
      }),
    ],
  };

In the package.json file, add the new "build:emails" to the scripts.Replace ./app/assets/stylesheets/emails.css with your file path:

"scripts": {
  "build:emails": "postcss ./app/assets/stylesheets/emails.css -o ./app/assets/builds/emails.css"
}

The previous script processes and overwrites the file at ./app/assets/stylesheets/emails.css with PostCSS using its postcss-css-variables plugin, replacing the CSS variables with their static value.

If the file to be processed is not .css, but .scss, it needs to be converted first to .css, then have its variables replaced. The script would then be

"scripts": {
  "build:emails": "sass ./app/assets/stylesheets/emails.scss:./app/assets/builds/emails.css --no-source-map --load-path=node_modules && postcss ./app/assets/builds/emails.css -o ./app/assets/builds/emails.css"
}

Next, to execute the script when running bin/dev, add the following line in the file Procfile.dev

emails_css: yarn build:emails --watch

The srcipt can also be executed separately with the command

yarn build:emails

Caveat

The variables must be declared before use. Otherwise, their values when called will be set to undefined.

Contributions

Contributions are most welcome.
Premailer was rotting away in a private SVN repository for too long and could use some TLC.
Fork and patch to your heart's content.
Please don't increment the version numbers.

A few areas that are particularly in need of love:

Improved test coverage
Move un-repeated background images defined in CSS for Outlook

Credits and code

Thanks to all the wonderful contributors for their updates.

Thanks to Greenhood + Company for sponsoring some of the 1.5.6 updates,
and to Campaign Monitor for supporting the web interface.

The source code can be found on GitHub.

Owner metadata

Name: premailer
Login: premailer
Email:
Kind: organization
Description:
Website:
Location:
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/5750522?v=4
Repositories: 5
Last ynced at: 2024-04-21T03:04:42.616Z
Profile URL: https://github.com/premailer

GitHub Events

Total

Delete event: 2
Pull request event: 6
Fork event: 5
Issues event: 7
Watch event: 35
Issue comment event: 16
Push event: 1
Pull request review event: 12
Pull request review comment event: 17
Create event: 1

Last Year

Delete event: 2
Pull request event: 5
Fork event: 2
Issues event: 5
Watch event: 30
Issue comment event: 14
Push event: 1
Pull request review comment event: 1
Pull request review event: 1
Create event: 1

Committers metadata

Last synced: 3 days ago

Total Commits: 647
Total Committers: 123
Avg Commits per committer: 5.26
Development Distribution Score (DDS): 0.728

Commits in past year: 11
Committers in past year: 3
Avg Commits per committer in past year: 3.667
Development Distribution Score (DDS) in past year: 0.455

Name	Email	Commits
Alex Dunae	a**x@d**a	176
Akzhan Abdulin	a**n@g**m	109
Michael Grosser	m**l@g**t	97
Anthony McLin	g**t@a**m	21
ju1ius	j**e@l**t	10
Geremia Taglialatela	t**v@g**m	9
Curt Howard	c**t@p**m	9
Mark Edmondson	m**k@g**m	9
Aaron	a**i@g**m	7
Anton Rieder	1****r	6
hradu	h**u@u**m	6
Aaron Breckenridge	a**e@g**m	5
Matthew Landauer	m**r@g**m	5
Stefan Hoffmann	s**n@n**e	5
shields	s**s@t**m	5
Wolfram Nikolas Müller	w**m@f**m	4
Paul Sokolik	s**k@s**m	4
Dave Weir	d**r@i**o	4
Michael Bianco	i**y@g**m	4
Orien Madgwick	4****n	4
Jason Berlinsky	j**y@g**m	3
Johan Brook	j**b@g**m	3
ryanscottaudio	i**l@g**m	3
William Johnston	w**m@j**s	3
Tommy Crumrine	t**y@t**m	3
Mark Edmondson	m**n@g**m	3
Odin Dutton	o**n@g**m	3
James Matsuba	j**a@g**m	3
Bragadeesh	b**y@g**m	3
epinault-ttc	e**t@t**m	3
and 93 more...

Committer domains:

Issue and Pull Request metadata

Last synced: 4 days ago

Total issues: 61
Total pull requests: 96
Average time to close issues: over 1 year
Average time to close pull requests: 3 months
Total issue authors: 57
Total pull request authors: 45
Average comments per issue: 3.43
Average comments per pull request: 1.63
Merged pull request: 68
Bot issues: 0
Bot pull requests: 0

Past year issues: 4
Past year pull requests: 7
Past year average time to close issues: 1 day
Past year average time to close pull requests: 2 days
Past year issue authors: 4
Past year pull request authors: 4
Past year average comments per issue: 1.75
Past year average comments per pull request: 1.86
Past year merged pull request: 4
Past year bot issues: 0
Past year bot pull requests: 0

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/premailer/premailer

Top Issue Authors

tagliala (4)
dorianmariefr (2)
sampatbadhe (1)
ragesoss (1)
jherdman (1)
pravi (1)
dark-panda (1)
romanbsd (1)
jamesryanbell (1)
BenMorel (1)
jahvi (1)
seanhinton (1)
Mickyliu (1)
Spica2 (1)
GregOriol (1)

Top Pull Request Authors

grosser (17)
tagliala (14)
sokolikp (3)
orien (3)
wnm (3)
dorianmariefr (2)
internethostage (2)
searls (2)
aried3r (2)
garyhtou (2)
eflorit (2)
flipsasser (2)
composerinteralia (2)
ryanscottaudio (2)
johnnyshields (2)

Top Issue Labels

Top Pull Request Labels

Package metadata

Total packages: 11
Total downloads:
- rubygems: 234,125,356 total
Total docker downloads: 909,157,046
Total dependent packages: 51 (may contain duplicates)
Total dependent repositories: 5,079 (may contain duplicates)
Total versions: 151
Total maintainers: 2

gem.coop: premailer

Improve the rendering of HTML emails by making CSS inline, converting links and warning about unsupported code.

Homepage: https://github.com/premailer/premailer
Documentation: http://www.rubydoc.info/gems/premailer/
Licenses: BSD-3-Clause
Latest release: 1.28.0 (published 7 days ago)
Last Synced: 2026-03-02T05:32:28.794Z (1 day ago)
Versions: 51
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 117,066,177 Total
Docker Downloads: 454,578,523
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.115%
- Downloads: 0.219%
- Docker downloads count: 0.242%
Maintainers (2)
- grosser
- alexdunae

rubygems.org: premailer