No release in over 3 years
Low commit activity in last 3 years
There's a lot of open issues
Send emails, track statistics, and manage your subscriber base with ease.


> 1.4
>= 0
>= 0


> 0.1.7
>= 0.13.1
 Project Readme

madmimi¶ ↑

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

Installation¶ ↑

$ gem install madmimi

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

Dependencies¶ ↑

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

Basic Usage¶ ↑

mimi ='emailaddress', 'api_key')
mimi.lists # get all of your Mad Mimi lists returned as a hash

You can pass raise_exceptions to the initializer, if you wish to receive exceptions for failing requests:'emailaddress', 'api_key', { :raise_exceptions => true })
mimi.lists # will raise an Exception if request fails

You can set verify_ssl to either true or false in initializer, if you wish verify SSL or not in requests:'emailaddress', 'api_key', { :verify_ssl => true })

Audience Members and Lists¶ ↑

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,email\ndave,\n") # import from a csv string

mimi.add_user({ :email => '', :first_name => 'Dave' }) # add new audience member

  { :email => '',   :first_name => 'Dave' },
  { :email => '', :custom_field_1 => 'Dummy value' },
  { :email => '',  :last_name => 'Smith' }
]) # add audience members in bulk

mimi.add_to_list('', 'Test List') # add this email address to a specific list
mimi.add_to_list('', 'Test List', {
  :first_name   => 'Dave',
  :last_name    => 'Example',
  :custom_field => 'Custom value'
}) # add additional data with this email

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

mimi.remove_from_all_lists('') # remove this email address from all lists

# this API call needs advanced permissions (manually requested)
mimi.update_email('', '') # changes email address for user '' to ''

mimi.members # get all audience members

mimi.list_members('Test List') # get audience members in specific list

mimi.list_members('Test List', 2, 50) # get audience members on the 2nd page in specific list (50 members per page)

mimi.suppressed?('') # check if audience member is suppressed

mimi.suppress_email('') # move email to suppressed list

mimi.unsuppress_email('') # move email from suppressed list

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

Promotions¶ ↑

mimi.promotions # returns a hash of your promotions

mimi.save_promotion('promotion_name', 'raw_html', 'plain_text') # saves a promotion (creates the promotion if it does not exist)

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[[tracking_beacon]]</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)

Getting the status of a transactional mailing¶ ↑

mimi.status('transaction_id') # get the status on a specific transactional mailing

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.”

  • 'to_all': Set to true to send a promotion, plain_text or raw_html to all your audience members

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.

Contributors¶ ↑

tuker marcheiligers maximgladkov

Copyright © 2010 Nicholas Young. See LICENSE for details.