tkbeili / createsend-ruby

A Ruby library for the Campaign Monitor API

createsend

A ruby library which implements the complete functionality of the Campaign Monitor API.

Installation

gem install createsend

Documentation

Full documentation is hosted by RubyDoc.info.

Examples

Basic usage

This example of listing all your clients demonstrates basic usage of the library:

require 'createsend'

CreateSend.api_key 'your_api_key'

cs = CreateSend::CreateSend.new
clients = cs.clients

clients.each do |c|
  puts "#{c.ClientID}: #{c.Name}"
end

Running this example will result in something like:

4a397ccaaa55eb4e6aa1221e1e2d7122: Client One
a206def0582eec7dae47d937a4109cb2: Client Two

Handling errors

If the Campaign Monitor API returns an error, an exception will be thrown. For example, if you attempt to create a campaign and enter empty values for subject etc:

require 'createsend'

CreateSend.api_key 'your_api_key'

begin
  cl = CreateSend::Client.new "4a397ccaaa55eb4e6aa1221e1e2d7122"
  id = CreateSend::Campaign.create cl.client_id, "", "", "", "", "", "", "", [], []
  puts "New campaign ID: #{id}"
  rescue CreateSend::BadRequest => br
    puts "Bad request error: #{br}"
    puts "Error Code:    #{br.data.Code}"
    puts "Error Message: #{br.data.Message}"
  rescue Exception => e
    puts "Error: #{e}"
end

Results in:

Bad request error: The CreateSend API responded with the following error - 304: Campaign Subject Required
Error Code:    304
Error Message: Campaign Subject Required

Expected input and output

The best way of finding out the expected input and output of a particular method in a particular class is to use the unit tests as a reference.

For example, if you wanted to find out how to call the CreateSend::Subscriber.add method, you would look at the file test/subscriber_test.rb

should "add a subscriber with custom fields" do
  stub_post(@api_key, "subscribers/#{@list_id}.json", "add_subscriber.json")
  custom_fields = [ { :Key => 'website', :Value => 'http://example.com/' } ]
  email_address = CreateSend::Subscriber.add @list_id, "[email protected]", "Subscriber", custom_fields, true
  email_address.should == "[email protected]"
end

Contributing

1. Fork the repository
2. Make your changes, including tests for your changes.
3. Ensure that the build passes, by running bundle exec rake (CI runs on: 1.9.3, 1.9.2, 1.8.7 and ree)
4. It should go without saying, but do not increment the version number in your commits.
5. Submit a pull request.