benchwarmer

= Benchwarmer {}[http://travis-ci.org/terra-firma/benchwarmer] {}[https://gemnasium.com/terra-firma/benchwarmer]

Benchwarmer is a Ruby gem that provides a wrapper for interacting with the {Benchmark Email API}[http://www.benchmarkemail.com/API/Doc].

== Requirements

You will need a {Benchmark Email account}[http://www.benchmarkemail.com/Register]. Once you have your Benchmark account set up, you will need your username and password to access the API.

== Installation

(sudo) gem install benchwarmer

== API Token

The first step is to login to the Benchmark Email API and get your API access token, which you will want to store for later use. Keep in mind that each time you "login" to the API, a new token will be generated. Token management is discussed further down. Don't forget that your "username" can also be your email address, depending on how you have set up your Benchmark Email account.

token = Benchwarmer::API.login('username/email', 'password')

"833a7c7ff759414699efe73ac90cff98" # => Store this value for later use.

== Usage

Once you have your API access token, the next step is to create a Benchwarmer object:

b = Benchwarmer::API.new(token)

You can also override the default configuration by passing in your own when initializing:

b = Benchwarmer::API.new(token, {:secure => true, :timeout => 60, :api_version => '1.0'})

You can then run any of the methods that you find in the {Benchmark Email API Documentation}[http://www.benchmarkemail.com/API/Library] against it. Simply convert the names to the more Ruby-like underscored versions (e.g. listGetContactDetails becomes list_get_contact_details).

Retrieve all contact lists

b.list_get('', 1, 100, '', '')

Add contacts to a list

contacts = [ { :email => '[e-mail]', :firstname => 'Bob', :lastname => 'Smith' } ] b.list_add_contacts('list_id', contacts, 0) # => Change to '1' for double opt-in

Create a new contact list

b.list_create('My List Name') # => Returns the ID of the newly created list

== Dealing With Tokens

Each time you "login" to the API to retrieve an access token, the Benchmark Email API will generate a new access token. The problem with this is that if you don't store your token and instead login each time, tokens will build up. Since having a lot of tokens that grant access to your account via the API is a bad idea, {Benchwarmer}[http://rubygems.org/gems/benchwarmer] provides methods to manage your tokens:

List the valid API tokens for this account

Benchwarmer::API.token_get('username/email', 'password', {:secure => true})

Add a new API token

Benchwarmer::API.token_add('username/email', 'password', {:secure => true})

Delete an API token

Benchwarmer::API.token_add('username/email', 'password', 'api_token_to_delete', {:secure => true})

== Contributing to Benchwarmer

• 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) 2012 Terra Firma Design & Consulting. See LICENSE.txt for further details.