For the impatient

Install as plugin:

script/plugin install git://github.com/goganchic/awesome_email.git

Learn how to use it below.

Introduction

Have you ever tried sending HTML emails to your users? If you did, you know for sure that it sucks big time: none of the usual ActionView helpers want to work, URL routing is disabled, layouts don’t work, and last but not least, the CSS you wrote for your email simply won’t work in any e-mail client except maybe Apple Mail. To solve all of the above problems, the awesome_email plugin comes to the rescue. Just install it into your vendor/plugins folder, and the rest comes by itself.
If you are interested in what works in which Email client check this link: A guide to css support in Email

What does it do?

There are a few interesting components in awesome_email:

• The HTML Mail’s CSS is automatcally inlined. That means that your designer and/or CSS guy can design the email in a web browser without worrying about how it might look like in excotic email clients. Yes, it works in Outlook, too, and no, it doesn’t work in Outlook 2007 without tweaking. The reason is a “stupid decision from Microsoft about Outlook 2007”, but we’re working on that one.
• ConvertEntities replaces Umlauts and other crazy symbols like ä, Ö etc. with their HTML Entitiy counterparts e.g. ä and so on.
• HelperMethods allow you to dump the content of the CSS file right into a style tag inside the header of your HTML mail.

How to use it

In your Mailer.delivery_xxx methods you can use

    layout    "template_filename"
    css       "css_filename"

or without letter template

    css "css_filename"
    html_content = "some html here"
    body(inline(html_content))

You can include several css files if required

    css       ["css_filename1", "css_filename2"]

to define which layout should be used and which css file should be used to create inline styles

CSS inlining

The cummulated style of each DOM element will be set as an style attribute when using css inlining.

Example

your css file:

    #some-id { font-size:2em; }
    .some-class { color:red; }

your template:

    <p id="some-id" class="some-class">Hello World!</p>

will result in the following code:

    <p id="some-id" class="some-class" style="color:red; font-size:2em;">Hello World!</p>

Important!

Be sure to follow these simple conventions or otherwise awesome_emails’s magic will fail:

• If you send mutlipart mails, check out the conventions on how to name your files: http://rails.rubyonrails.com/classes/ActionMailer/Base.html So if you have these files inside of /app/views/{mailer_name}: signup_notification.text.plain.erb, signup_notification.text.html.erb ActionMailer will send a multipart mail with two parts: text/plain and text/html
• Your CSS file must be inside of /public/stylesheets
• Your layout files must be inside /app/views/layout

If you use something like Sass to generate your CSS files (and you should!) you can tell awsome_email by overwriting ActionMailer::InlineStyles#maybe_generate_css_file

Here is an overwrite that works for Sass:

ActionMailer::InlineStyles.module_eval do
  def self.maybe_generate_css_file(file_name)
    Sass::Plugin.check_for_updates
  end
end

Dependencies

Gems:

• rails 2.0.1+
• nokogiri 1.3.3+
• css_parser

Getting it, License and Patches

Get the original source code through http://github.com/imedo/awesome_email. License is MIT. That means that you can do whatever you want with the software, as long as the copyright statement stays intact. Please be a kind open source citizen, and give back your patches and extensions. Just fork the code on Github, and after you’re done, send us a pull request. Thanks for your help!

ToDo

• More test coverage (as usual) – especially testing multiple rules (!)
• Make it more flexible with view paths

Copyright © 2008 imedo GmbH, released under the MIT license