Benchwarmer Dependency Status

Benchwarmer is a Ruby gem that provides a wrapper for interacting with the Benchmark Email API.

Requirements

You will need a Benchmark Email account. 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 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 => 'sample@subscriber.com',
    :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 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

Copyright © 2012 Terra Firma Design & Consulting. See LICENSE.txt for further details.