gem install madmimi - then send emails, track statistics, and manage your subscriber base with ease... and all with the Ruby syntax you know and love!
Clone or download
Pull request Compare This branch is 5 commits ahead, 62 commits behind madmimi:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



The power of Mad Mimi in your Ruby application. Deliver emails, track statistics, and manage your subscriber base with ease.


gem install madmimi - or if you prefer to live on the edge, just clone this repository and build it from scratch.

Basic Usage

Dependencies: active_support (I intend to remove this in the not too distant future, and build my own implementation.)

mimi ='emailaddress', 'api_key')

mimi.lists -> get all of your Mad Mimi lists returned as a hash

mimi.memberships('email') -> returns a hash of the lists that specific email address is subscribed to

mimi.new_list('New list name') -> make a new list

mimi.delete_list('New list name') -> delete the list I just created

mimi.csv_import(“name,emailndave,dave@example.comn”) -> import from a csv string

mimi.add_to_list('', 'Test List') -> add this email address to a specific list

mimi.remove_from_list('', 'Test List') -> remove this email address from a specific list

mimi.suppressed_since('unix timestamp') -> get a TXT of all addresses that were suppressed since this timestamp

mimi.promotions -> returns a hash of your promotions

mimi.mailing_stats('promotion_id', 'mailing_id') -> get stats on a specific mailing

Sending E-Mail (using the Mailer API)

Replacing keys in your email body text:

options = { 'promotion_name' => 'Test Promotion', 'recipients' => 'Nicholas Young <>', 'from' => 'MadMimi Ruby <>', 'subject' => 'Test Subject' }

yaml_body = { 'greeting' => 'Hello', 'name' => 'Nicholas' }

mimi.send_mail(options, yaml_body)

Sending Raw HTML (presumably generated by your app)

options = { 'promotion_name' => 'Test Promotion', 'recipients' => 'Nicholas Young <>', 'from' => 'MadMimi Ruby <>', 'subject' => 'Test Subject' }

raw_html = “<html><head><title>My great promotion!</title></head><body>Body stuff[]</body></html>”

mimi.send_html(options, raw_html)

Sending Plain Text

options = { 'promotion_name' => 'Test Promotion', 'recipients' => 'Nicholas Young <>', 'from' => 'MadMimi Ruby <>', 'subject' => 'Test Subject' }

plain_text = “Plain text email contents [[unsubscribe]]”

mimi.send_plaintext(options, plain_text)

Return values

In most cases, a return value of a single space indicates success.

On success, #send_mail, #send_html, and #send_plaintext return String with a numeric mailing_id. This mailing_id can be used to look up stats with #mailing_stats.

Errors or issues preventing operation completing return a human-readable String.

Therefore, if the return value is not a space, or is not a numeric String value, then there is probably an error or uncompleted operation.

Specific options keys

'raw_html': Must include at least one of the [[tracking_beacon]] or [[peek_image]] tags.

'promotion_name': If a promotion doesn't exist under the given name, it will be created. If it exists and you specify raw_html, the promotion body will be replaced.

'list_name': For all of the #send methods, if 'list_name' is provided, the recipients will be those for an already-existing “audience.”

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.




Copyright © 2010 Nicholas Young. See LICENSE for details.