README.rdoc in madmimi-1.0.6 vs README.rdoc in madmimi-1.0.8
- old
+ new
@@ -4,11 +4,11 @@
== Installation
gem install madmimi - or if you prefer to live on the edge, just clone this repository and build it from scratch.
-== A brief tutorial
+== 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')
@@ -31,18 +31,68 @@
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 <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)
+
+=== 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.
+
+== Contributors
+tuker
== Copyright
Copyright (c) 2010 Nicholas Young. See LICENSE for details.