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 '[email protected]'
recipients '[email protected]'
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
- Andrea Campi (http://github.com/andreacampi)
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
- Fork it.
- Create a branch
- Commit your changes
- Push to the branch
- Send a pull request