README.md in tuktuk-0.5.1 vs README.md in tuktuk-0.5.2

@@ -1,10 +1,10 @@
 Tuktuk - SMTP client for Ruby
 =============================
 
-Unlike Pony (which is friggin' awesome by the way) Tuktuk does not rely on 
-`sendmail` or a separate SMTP server in order to send email. Tuktuk looks up the
+Unlike famous ol' Pony gem (which is friggin' awesome by the way), Tuktuk does not rely on 
+`sendmail` or a separate SMTP server in order to deliver email. Tuktuk looks up the
 MX servers of the destination address and connects directly using Net::SMTP. 
 This way you don't need to install Exim or Postfix and you can actually handle 
 response status codes -- like bounces, 5xx -- within your application. 
 
 Plus, it supports DKIM out of the box.
@@ -30,11 +30,11 @@
 ``` ruby
 [...]
 
 response, email = Tuktuk.deliver(message)
 
-if response.is_a?(Bounce)
+if response.is_a?(Tuktuk::Bounce)
   puts 'Email bounced. Type: ' + response.class.name # => HardBounce or SoftBounce
 else
   puts 'Email delivered!'
 end
 ```
@@ -53,11 +53,11 @@
 
 result = Tuktuk.deliver_many(messages)
 
 result.each do |response, email|
 
-  if response.is_a?(Bounce)
+  if response.is_a?(Tuktuk::Bounce)
     puts 'Email bounced. Type: ' + response.class.name
   else
     puts 'Email delivered!'
   end
 
@@ -85,21 +85,58 @@
 response, email = Tuktuk.deliver(message)
 ```
 
 For DKIM to work, you need to set up a TXT record in your domain's DNS.
 
-Additional Tuktuk options:
+All available options, with their defaults:
 
 ``` ruby
 Tuktuk.options = {
-  :log_to => 'log/mailer.log',
-  :helo_domain => 'mydomain.com',
-  :max_workers => 'auto', # spawns a new thread for each domain 
+  :log_to       => nil,   # e.g. log/mailer.log
+  :helo_domain  => nil,   # your server's domain goes here
+  :max_workers  => 0,     # controls number of threads for delivering_many emails (read below)
+  :open_timeout => 20,    # max seconds to wait for opening a connection
+  :read_timeout => 20,    # 20 seconds to wait for a response, once connected
+  :verify_ssl   => true,  # whether to skip SSL keys verification or not
+  :debug        => false, # connects and delivers email to localhost, instead of real target server. CAUTION!
   :dkim => { ... }
 }
 ```
 
-That's all.
+You can set the `max_threads` option to `auto`, which will spawn the necessary threads to connect in paralell to all target MX servers when delivering multiple messages. When set to `0`, these batches will be delivered sequentially.
+
+In other words, if you have three emails targeted to Gmail users and two for Hotmail users, using `auto` Tuktuk will spawn two threads and connect to both servers at once. Using `0` will have email deliveried to one host and then the other.
+
+Using with Rails
+----------------
+
+Tuktuk comes with ActionMailer support out of the box. In your environment.rb or environments/{env}.rb:
+
+``` ruby
+require 'tuktuk/rails'
+
+[...]
+
+config.action_mailer.delivery_method = :tuktuk
+```
+
+Since Tuktuk delivers email directly to the user's MX servers, it's probably a good idea to set `config.action_mailer.raise_delivery_errors` to true. That way you can actually know if an email couldn't make it to its destination.
+
+When used with ActionMailer, you can pass options using ActionMailer's interface, like this:
+
+``` ruby
+
+config.action_mailer.delivery_method = :tuktuk
+
+config.action_mailer.tuktuk_settings = {
+  :log_to => 'log/mailer.log', # when not set, Tuktuk will use Rails.logger
+  :dkim => {
+    :domain => 'yoursite.com',
+    :selector => 'mailer',
+    :private_key => IO.read('ssl/yoursite.com.key')
+  }
+}
+```
 
 --
 
 (c) 2013 Fork Limited. MIT license.