/madmimi-gem

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!

Primary LanguageRubyMIT LicenseMIT

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 = MadMimi.new('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:

MadMimi.new('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:

MadMimi.new('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,dave@example.com\n") # import from a csv string

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

mimi.add_users([
  { :email => 'dave@example.com',   :first_name => 'Dave' },
  { :email => 'custom@example.com', :custom_field_1 => 'Dummy value' },
  { :email => 'smith@example.com',  :last_name => 'Smith' }
]) # add audience members in bulk

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

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

mimi.remove_from_all_lists('dave@example.com') # remove this email address from all lists

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

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?('dave@example.com') # check if audience member is suppressed

mimi.suppress_email('dave@example.com') # move email to suppressed list

mimi.unsuppress_email('dave@example.com') # 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 <nicholas@madmimi.com>',
  'from'           => 'MadMimi Ruby <rubygem@madmimi.com>',
  '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 <nicholas@madmimi.com>',
  'from'           => 'MadMimi Ruby <rubygem@madmimi.com>',
  '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 <nicholas@madmimi.com>',
  'from'           => 'MadMimi Ruby <rubygem@madmimi.com>',
  '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.