premailer-rails

The gem works by registering a delivery hook with actionmailer. When an email is delivered, premailer-rails collects URLs from <link rel="stylesheet" href="..."> tags and attempts to retrieve their content using the following strategies in order:

1. :filesystem: Looks for a file in the public/ directory matching the URL path.
2. :asset_pipeline: If Rails is available and the asset pipeline is enabled, it strips the fingerprint and prefix from the URL to request the asset via the pipeline.
3. :network: Performs a standard HTTP request to the URL (useful for assets hosted on a CDN).

In Rails production environments, retrieved CSS is cached. To prevent specific tags (like Google Fonts) from being inlined, add the data-premailer="ignore" attribute to the tag.

To run the provided example Rails application, ensure you have Bundler installed, then execute the following commands in your terminal:

1. Install dependencies: bundle
2. Start the Rails server: bundle exec rails s

Once the server is running, access the application at http://localhost:3000/.

If you are using actionmailer outside of a Rails environment (e.g., in Sinatra), you must manually register the interceptors for the gem to function. This should be done in your application's initialization phase.

Premailer::Rails.register_interceptors

To run the example Rails application provided in this repository, use the following commands to install dependencies and start the server:

1. Install the required gems using bundle.
2. Start the Rails server using bundle exec rails s.

Once the server is running, access the application at http://localhost:3000/.

Add premailer-rails to your Gemfile.

Important: premailer-rails and premailer do not have a hard dependency on an HTML parser. You must manually add an HTML parsing gem to your project. This gem is primarily tested with nokogiri.

gem 'premailer-rails'

You can pass configuration options to the underlying premailer instance by using Premailer::Rails.config.merge!. In a Rails application, this is typically done in an initializer (e.g., config/initializers/premailer_rails.rb).

Default Configuration:

{
  input_encoding: 'UTF-8',
  generate_text_part: true,
  strategies: [:filesystem, :asset_pipeline, :network]
}

Common Tasks:

• Disable automatic text part generation: Set :generate_text_part to false.
• Customizing strategies: Pass a custom array to :strategies to change the order or selection of CSS retrieval methods.

Premailer::Rails.config.merge!(preserve_styles: true, remove_ids: true)

To prevent premailer-rails from processing a specific email, set the :skip_premailer header to true in the mail method call.

Warning: The mere presence of the skip_premailer header causes the gem to skip processing. Because headers are transformed into strings, setting skip_premailer: false will still result in the email being skipped because the string 'false' is truthy.

class UserMailer < ActionMailer::Base
  def welcome_email(user)
    mail to: user.email,
         subject: 'Welcome to My Awesome Site',
         skip_premailer: true
  end
end

Emails are processed automatically upon delivery or when previewing in Rails. If you need to trigger the inlining manually (for example, during testing), you can call Premailer::Rails::Hook.perform(mail). This modifies the email object in place.

mail = SomeMailer.some_message(args)
Premailer::Rails::Hook.perform(mail)

You can access and modify the global configuration via Premailer::Rails.config. The default configuration includes the following keys:

• input_encoding: The encoding of the input HTML (default: 'UTF-8').
• generate_text_part: Whether to generate a plain text part for the email (default: true).
• strategies: An array of CSS loading strategies to use (default: [:filesystem, :asset_pipeline, :propshaft, :network]).

Premailer::Rails.config = {
  input_encoding: 'UTF-8',
  generate_text_part: true,
  strategies: [:filesystem, :asset_pipeline, :propshaft, :network]
}