= 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 ', '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 = "My great promotion!Body stuff[[tracking_beacon]]" 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 Copyright (c) 2010 Nicholas Young. See LICENSE for details.