Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A Ruby gem to send multipart email--the easy way
branch: master

This branch is 2 commits ahead, 10 commits behind zephirworks:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
lib
test
.gitignore
LICENSE
README.md
Rakefile
TODO.md
easy_multipart.gemspec

README.md

easy_multipart

A Ruby gem to send multipart email--the easy way.

Installation

First install the gem:

gem install easy_multipart

Then you can just include easy_multipart in your mailers:

include EasyMultipart::Base

Alternatively, to make it available to all your mailers, put this line in an initializer:

ActiveMailer::Base.extend EasyMultipart::Base

Rationale

If you use Rails you probably know ActiveMailer, the core gem that provides all necessary functionality to send and receive email. ActiveMailer does let you build and send a multipart message, with support for such features as alternative text (plain text, HTML etc) and attachments.

However, using ActiveMailer in a practical way requires a working understanding of the ins and outs of MIME, the relevant RFCs and most troubling of all--the quirks of different email clients. For instance, sending a newsletter that can be reliably rendered by all popular email clients can be a daunting task.

easy_multipart aims to help with that; it provides a small (but hopefully growing) set of tools to deal with the most common tasks. It doesn't try to do too much; it does a few things, but it tries to do them in an easy and pleasant way that should feel familiar.

Features

Note: at this time, easy_mailer has only been tested on Rails 2.3.8 with Ruby 1.8.7, and the documentation reflects that. Expect that to change in the near future.

With easy_multipart you write your ActiveMailer model like you are used to. You must not include a body or part; instead you should invoke easy_multipart.

class TestModel
  def test
    from        'billing@example.com'
    recipients  'dear.customer@some.big.company'
    subject     'Your monthly invoice'

    easy_multipart :body => { :name => 'Dear Customer',
                              :amount => '9.99' }
  end
end

Your views and layouts don't need to change either; easy_multipart respects conventions from ActiveMailer and will find them.

With this basic support in place, you are ready to take advantage of easy_multipart features.

Embedded images

Embedded images are a way of sending HTML email messages that images inside your email are loaded from the same message, instead of off a website.

Technically, this functionality is achieved using a MIME type of multipart/related. The concept is quite easy; however, getting the details right can be tricky.

easy_multipart provides a very convenient helper that hides all this complexity from you:

<%= related_image_tag 'logo.png', :file => 'email/logo.png' %>

The path is assumed to be relative to your public/images folder (in fact, image_tag is used internally).

This helper will attach the image to the email and generate an appropriate HTML tag:

<img src="cid:some-random-string">

The email messages generated by easy_multipart have been tested to display correctly with:

  • Apple Mail
  • Gmail
  • iPhone Mail
  • Thunderbird
  • Postbox

Testing

To run the tests:

TODO

Maintainers

Bugs and Feedback

If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.

http://github.com/zephirworks/easy_multipart/issues

BSD License. Copyright 2010 ZephirWorks. http://www.zephirworks.com

Contributing

  1. Fork it.
  2. Create a branch
  3. Commit your changes
  4. Push to the branch
  5. Send a pull request
Something went wrong with that request. Please try again.