README.md in ahoy_email-0.0.2 vs README.md in ahoy_email-0.1.0

@@ -1,16 +1,16 @@
 # Ahoy Email
 
-:construction: Coming soon - May 1, 2014
+:postbox: Simple, powerful email tracking for Rails
 
-:envelope: Simple, powerful email tracking for Rails
+You get:
 
-Keep track of emails:
+- A history of emails sent to each user
+- Open and click tracking
+- Easy UTM tagging
 
-- sent
-- opened
-- clicked
+Works with any email service.
 
 ## Installation
 
 Add this line to your application’s Gemfile:
 
@@ -25,100 +25,152 @@
 rake db:migrate
 ```
 
 ## How It Works
 
-Ahoy creates an `Ahoy::Message` record when an email is sent.
+Ahoy creates an `Ahoy::Message` every time an email is sent by default.
 
-### Open
+### Users
 
-An invisible pixel is added right before the closing `</body>` tag to HTML emails.
+Ahoy tracks the user a message is sent to - not just the email address.  This gives you a full history of messages for each user, even if he or she changes addresses.
 
-If a recipient has images enabled in his / her email client, the pixel is loaded and an open is recorded.
+By default, Ahoy tries `User.where(email: message.to.first).first` to find the user.
 
-### Click
+You can pass a specific user with:
 
-Links in HTML emails are rewritten to pass through your server.
+```ruby
+class UserMailer < ActionMailer::Base
+  def welcome_email(user)
+    # ...
+    track user: user
+    mail to: user.email
+  end
+end
+```
 
+The user association is [polymorphic](http://railscasts.com/episodes/154-polymorphic-association), so use it with any model.
+
+To get all messages sent to a user, add an association:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :messages, class_name: "Ahoy::Message"
+end
+```
+
+And run:
+
+```ruby
+user.messages
+```
+
+### Opens
+
+An invisible pixel is added right before the `</body>` tag in HTML emails.
+
+If the recipient has images enabled in his or her email client, the pixel is loaded and the open time recorded.
+
+Use `track open: false` to skip this.
+
+### Clicks
+
+A redirect is added to links to track clicks in HTML emails.
+
 ````
 http://chartkick.com
 ```
 
 becomes
 
 ```
-http://yoursite.com/ahoy/messages/rAnDoMtOken/click?url=http%3A%2F%2Fchartkick.com&signature=...
+http://you.io/ahoy/messages/rAnDoMtOkEn/click?url=http%3A%2F%2Fchartkick.com&signature=...
 ```
 
 A signature is added to prevent [open redirects](https://www.owasp.org/index.php/Open_redirect).
 
-Keep specific links from being tracked with `<a data-disable-tracking="true" href="..."></a>`.
+Use `track click: false` to skip tracking, or skip specific links with:
 
+```html
+<a data-skip-click="true" href="...">Can't touch this</a>
+```
+
 ### UTM Parameters
 
-UTM parameters are added to each link if they don’t already exist.
+UTM parameters are added to links if they don’t already exist.
 
-By default, `utm_medium` is set to `email`.
+The defaults are:
 
-### User
+- utm_medium - `email`
+- utm_source - the mailer name like `user_mailer`
+- utm_campaign - the mailer action like `welcome_email`
 
-To specify the user, use:
+Use `track utm_params: false` to skip tagging, or skip specific links with:
 
-```ruby
+
+```html
+<a data-skip-utm-params="true" href="...">Break it down</a>
+```
+
+## Customize
+
+There are 3 places to set options. Here’s the order of precedence.
+
+### Action
+
+``` ruby
 class UserMailer < ActionMailer::Base
   def welcome_email(user)
     # ...
-    ahoy user: user
+    track user: user
     mail to: user.email
   end
 end
 ```
 
-User is [polymorphic](http://railscasts.com/episodes/154-polymorphic-association), so use it with any model.
+### Mailer
 
-## Customize
+```ruby
+class UserMailer < ActionMailer::Base
+  track utm_campaign: "boom"
+end
+```
 
-There are 3 places to set options.
-
 ### Global
 
-The defaults are listed below.
+```ruby
+AhoyEmail.track open: false
+```
 
+## Reference
+
+You can use a `Proc` for any option.
+
 ```ruby
-AhoyEmail.options = {
-  create_message: true,
-  track_open: true,
-  track_click: true,
-  utm_source: nil,
-  utm_medium: "email",
-  utm_term: nil,
-  utm_content: nil,
-  utm_campaign: nil
-}
+track utm_campaign: proc{|message, mailer| mailer.action_name + Time.now.year }
 ```
 
-### Mailers
+Disable tracking for an email
 
 ```ruby
-class UserMailer < ActionMailer::Base
-  ahoy utm_campaign: "boom"
-end
+track message: false
 ```
 
-### Action
+Or by default
 
-``` ruby
-class UserMailer < ActionMailer::Base
-  def welcome_email(user)
-    # ...
-    ahoy user: user
-    mail to: user.email
-  end
-end
+```ruby
+AhoyEmail.track message: false
 ```
 
+Use a different model
+
+```ruby
+AhoyEmail.message_model = UserMessage
+```
+
 ## TODO
 
+- Add tests
+- Open and click hooks for deeper analytics
 - Subscription management (lists, opt-outs) [separate gem]
 
 ## History
 
 View the [changelog](https://github.com/ankane/ahoy_email/blob/master/CHANGELOG.md)