Skip to content
This repository

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!

README.rdoc

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.

Basic Usage

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

mimi = MadMimi.new('emailaddress', 'api_key')

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

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,emailndave,dave@example.comn”) -> import from a csv string

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

mimi.remove_from_list('dave@example.com', '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

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

Copyright

Copyright © 2010 Nicholas Young. See LICENSE for details.

Something went wrong with that request. Please try again.