= Mandrill 

Note: This gem is no longer under active development. We have moved on to using the {Mailchimp Gem}[https://github.com/mailchimp/mailchimp-gem] for interacting with Mailchimp's public API's. There is also a {lighter-weight Mandrill wrapper}[https://bitbucket.org/mailchimp/mandrill-api-ruby] maintained by Mailchimp.

Mandrill is a Ruby gem that provides a wrapper for interacting with the {Mandrill API}[http://mandrillapp.com/api/docs/index.html]. Remember that {Mandrill}[http://mandrillapp.com] has an excellent {SMTP Headers API}[http://help.mandrill.com/customer/portal/articles/456744-smtp-headers-api], which is often a better integration option, particularly if your app sends emails.

== Installation

  (sudo) gem install mandrill

== Usage

=== Interacting with the API

Once you have a valid API key (either your {account password}[https://mandrillapp.com/settings] or OAuth token) you can easily interact with the {Mandrill API}[http://mandrillapp.com/api/docs/index.html] by passing in arguments as a hash:

  m = Mandrill::API.new('api-key')
  m.users :ping
  m.users :senders
  # Methods with dashes shouldn't be passed in as symbols
  m.users 'disable-sender', {:domain => "exampledomain.com"}
  m.users 'verify-sender', {:email => 'test@exampledomain.com'}
  m.messages :send, {:message => {:html => "HTML message text", :text => "message text"}...}

=== Errors

When an error is received an instance of <code>Mandrill::API::Error</code> will be returned so that you can rescue accordingly:

  rescue Mandrill::API::Error > error
    ...

== OAuth

This is for advanced users only! Most (> 99%) developers will only care about the API, and that is entirely handled by the description above. OAuth support is only for companies building an email-oriented service who would like to do so atop Mandrill. If this is you, read on...

You will need a {Mandrill account}[http://help.mandrill.com/customer/portal/topics/214457-getting-started/articles] as a developer so that you can register your app.

=== Register Your App

{Login to your Mandrill account}[https://mandrillapp.com] and click "{register a new app}[https://mandrillapp.com/app/register]" on the "Settings > Applications" page. Once your app is registered, you will get an "App Authentication ID", and you're now ready to get started.

=== Connect Your App

The first thing you will need to do is prompt your users to authorize the connection between your application and {Mandrill}[https://mandrillapp.com]. Once they are logged in, simply redirect them:

  redirect_to Mandrill.authorization_url("your_app_id", "https://yourapp.com/mandrill/callback")

Once authorized successfully, a POST request will be sent to the +redirect_url+ with a "key" parameter containing the API key for that user's {Mandrill}[https://mandrillapp.com] account. Be sure to store this key somewhere, as you will need it to run API requests later. If authorization fails for some reason, an "error" parameter will be present in the POST request, containing an error message.

  def callback
    # POST /mandrill/callback
    if params[:key]
      current_user.mandrill_key = params[:key]
      current_user.save
      ...
    elsif params[:error]
      flash[:alert] = params[:error]
      ...
    end
  end

As you can see, we are saving the key that Mandrill returns for the currently logged in user, and we have successfully connected this user account to Mandrill.

== Contributing to Mandrill
 
* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
* Fork the project.
* Start a feature/bugfix branch.
* Commit and push until you are happy with your contribution.
* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== Copyright

Copyright (c) 2011 Terra Firma Design & Consulting. See LICENSE.txt for further details.