README.rdoc in mandrill-rails-0.0.2 vs README.rdoc in mandrill-rails-0.0.3

@@ -71,20 +71,20 @@
 * select the events you want to trigger on
 * set the "Post to URL" to point to your controller e.g. http://mydomain.com/inbox
 
 === How do I handle a specific Mandrill event payload in my app?
 
-Once you have configured Mandrill and setup your routes and controllers, we can successfully
+Once we have configured Mandrill and setup our routes and controllers, our app will successfully
 receive WebHook event notifications from Mandrill. But we are not doing anything with the payload yet.
 
 To handle specific Mandrill event payloads, we just need to implement a handler for each event type
 we are interested in.
 
 The list of available event types includes: inbound, send, hard_bounce, soft_bounce, open,
 click, spam, unsub, and reject.
 
-In our controller, we simply write a method called handle_<event-type> and it will be called
+In our controller, we simply write a method called `handle_<event-type>` and it will be called
 for each event payload received. The event payload will be passed to this method
 as an Mandrill::WebHook::EventDecorator - basically a Hash with some additional methods to
 help extract payload-specific elements.
 
 For example, to handle inbound email:
@@ -104,9 +104,113 @@
 Note that Mandrill may send multiple event payloads in a single request, but you don't need
 to worry about that. Each event payload will be unpacked from the request and dispatched to
 your handler individually.
 
 And if you don't care to handle a specific payload type - then just don't implement the associated handler.
+
+=== How do I pull apart the event_payload?
+
+The `event_payload` object passed to our handler represents a single event and is packaged
+as an Mandrill::WebHook::EventDecorator - basically a Hash with some additional methods to
+help extract payload-specific elements.
+
+You can use it as a Hash (with String keys) to access all of the native elements of the specific event, for example:
+
+    event_payload['event']
+    => "click"
+    event_payload['ts']
+    => 1350377135
+    event_payload['msg']
+    => {...}
+
+If you would like examples of the actual data structures sent by Mandrill for different event types,
+some are included in the project source under spec/fixtures/webhook_examples.
+
+=== What additional methods does event_payload provide to help extract payload-specific elements?
+
+In addition to prividing full Hash-like access to the raw message, the `event_payload` object
+(a Mandrill::WebHook::EventDecorator) provides a range of helper methods for some of the more obvious
+things you might need to do with the payload. Here are some examples (see
+{Mandrill::WebHook::EventDecorator class documentation}[http://rubydoc.info/gems/mandrill-rails/0.0.2/Mandrill/WebHook/EventDecorator]
+for full details)
+
+    event_payload.message_id
+    # Returns the message_id.
+    # Inbound events: references 'Message-Id' header.
+    # Send/Open/Click events: references '_id' message attribute.
+
+    event_payload.user_email
+    # Returns the subject user email address.
+    # Inbound messages: references 'email' message attribute (represents the sender).
+    # Send/Open/Click messages: references 'email' message attribute (represents the recipient).
+
+    event_payload.references
+    # Returns an array of reference IDs.
+    # Applicable events: inbound
+
+    event_payload.recipients
+    # Returns an array of all unique recipients (to/cc)
+    #   [ [email,name], [email,name], .. ]
+    # Applicable events: inbound
+
+    event_payload.recipient_emails
+    # Returns an array of all unique recipient emails (to/cc)
+    #   [ email, email, .. ]
+    # Applicable events: inbound
+
+
+=== How to extend Mandrill::WebHook::EventDecorator for application-specific payload handling?
+
+It's quite likely you may benefit from adding more application-specific intelligence to the
+`event_payload` object.
+
+There are many ways to do this, but it is quite legitimate to reopen the EventDecorator class and add your own methods
+if you wish.
+
+For example `event_payload.user_email` returns the subject user email address, but perhaps I will commonly want to
+match that with a user record in my system. Or I similarly want to resolve `event_payload.recipient_emails` to user records.
+In this case, I could extend EventDecorator in my app like this:
+
+    # Extends Mandrill::WebHook::EventDecorator with app-specific event payload transformation
+    class Mandrill::WebHook::EventDecorator
+
+      # Returns the user record for the subject user (if available)
+      def user
+        User.where(email: user_email).first
+      end
+
+      # Returns user records for all to/cc recipients
+      def recipient_users
+        User.where(email: recipient_emails)
+      end
+
+    end
+
+=== How do I extract attachments from an inbound email?
+
+The EventDecorator class provides an `attachments` method to access an array of attachments (if any).
+Each attachment is encapsulated in a class that describes the name, mime type, raw and decoded content.
+
+For example:
+
+    def handle_inbound(event_payload)
+      if attachments = event_payload.attachments.presence
+        # yes, we have at least 1 attachment. Lets look at the first:
+        a1 = attachments.first
+
+        a1.name
+        # => e.g. 'sample.pdf'
+        a1.type
+        # => e.g. 'application/pdf'
+        a1.content
+        # => this is the raw content provided by Mandrill, and will be base64-encoded if not plain text
+        # e.g. 'JVBERi0xLjMKJcTl8uXrp/Og0MTGCjQgMCBvY ... (etc)'
+        a1.decoded_content
+        # => this is the content decoded by Mandrill::Rails, ready to be written as a File or whatever
+        # e.g. '%PDF-1.3\n%\xC4\xE5 ... (etc)'
+
+      end
+    end
 
 === How do I use Mandrill gem features with Mandrill::Rails?
 
 {Mandrill}[https://github.com/tatemae-consultancy/mandrill] is included with Mandrill::Rails
 and its behaviour is unchanged. You can use all the features of the Mandrill gem as normal.