createsend 0.0.1 → 0.0.2

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2010 James Dennes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,3 +1,65 @@
 # createsend
 
-A wrapper for the createsend API v3.
+A ruby library which implements the complete functionality of v3 of the CreateSend API.
+
+## Installation
+
+    sudo gem install createsend
+
+## Examples
+
+### Basic usage
+Retrieve a list of all your clients.
+
+    require 'createsend'
+
+    CreateSend.api_key 'your_api_key'
+
+    cs = CreateSend.new
+    clients = cs.clients
+    
+    clients.each do |c|
+      puts "#{c.ClientID}: #{c.Name}"
+    end
+
+Results in:
+    
+    4a397ccaaa55eb4e6aa1221e1e2d7122: Client One
+    a206def0582eec7dae47d937a4109cb2: Client Two
+
+### Handling errors
+If the createsend 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 = Client.new "4a397ccaaa55eb4e6aa1221e1e2d7122"
+      id = Campaign.create cl.client_id, "", "", "", "", "", "", "", [], []
+      puts "New campaign ID: #{id}"
+      rescue 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 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 = Subscriber.add @list_id, "subscriber@example.com", "Subscriber", custom_fields, true
+      email_address.should == "subscriber@example.com"
+    end

data/createsend.gemspec

@@ -12,13 +12,13 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency('httparty', '~> 0.6.1')
   s.name = "createsend"
   s.author = "James Dennes"
-  s.description = %q{A wrapper for the CreateSend API v3}
+  s.description = %q{A library which implements the complete functionality of v3 of the createsend API.}
   s.email = ["jdennes@gmail.com"]
   s.executables = `git ls-files -- bin/*`.split("\n").map{|f| File.basename(f)}
   s.files = `git ls-files`.split("\n")
   s.homepage = "http://github.com/campaignmonitor/createsend-ruby/"
   s.require_paths = ["lib"]
-  s.summary = %q{Wrapper for the CreateSend API v3}
+  s.summary = %q{A library which implements the complete functionality of v3 of the createsend API.}
   s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.version = CreateSend::VER
   s.platform = Gem::Platform::RUBY

data/lib/campaign.rb

@@ -1,6 +1,7 @@
 require 'createsend'
 require 'json'
 
+# Represents a campaign and provides associated funtionality.
 class Campaign
   attr_reader :campaign_id
 
@@ -8,8 +9,9 @@ class Campaign
     @campaign_id = campaign_id
   end
 
+  # Creates a new campaign for a client.
   def self.create(client_id, subject, name, from_name, from_email, reply_to, html_url,
-    text_url, list_ids, segments)
+    text_url, list_ids, segment_ids)
     options = { :body => { 
       :Subject => subject,
       :Name => name,
@@ -18,12 +20,21 @@ class Campaign
       :ReplyTo => reply_to,
       :HtmlUrl => html_url,
       :TextUrl => text_url,
-      :ListIDs => list_ids ,
-      :Segments => segments }.to_json }
+      :ListIDs => list_ids,
+      :SegmentIDs => segment_ids }.to_json }
     response = CreateSend.post "/campaigns/#{client_id}.json", options
     response.parsed_response
   end
-  
+
+  # Sends a preview of this campaign.
+  def send_preview(recipients, personalize="fallback")
+    options = { :body => {
+      :PreviewRecipients => recipients.kind_of?(String) ? [ recipients ] : recipients,
+      :Personalize => personalize }.to_json }
+    response = post "sendpreview", options
+  end
+
+  # Sends this campaign.
   def send(confirmation_email, send_date="immediately")
     options = { :body => {
       :ConfirmationEmail => confirmation_email,
@@ -31,46 +42,79 @@ class Campaign
     response = post "send", options
   end
 
+  # Deletes this campaign.
   def delete
     response = CreateSend.delete "/campaigns/#{campaign_id}.json", {}
   end
-  
+
+  # Gets a summary of this campaign
   def summary
     response = get "summary", {}
     Hashie::Mash.new(response)
   end
-  
-  def lists
-    response = get "lists", {}
-    response.map{|item| Hashie::Mash.new(item)}
+
+  # Retrieves the lists and segments to which this campaaign will be (or was) sent.
+  def lists_and_segments
+    response = get "listsandsegments", {}
+    Hashie::Mash.new(response)
   end
-  
-  def segments
-    # TODO: This needs to be implemented
-    []
+
+  # Retrieves the recipients of this campaign.
+  def recipients(page=1, page_size=1000, order_field="email", order_direction="asc")
+    options = { :query => { 
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
+    response = get 'recipients', options
+    Hashie::Mash.new(response)
   end
-  
-  def opens(date)
-    options = { :query => { :date => date } }
+
+  # Retrieves the opens for this campaign.
+  def opens(date, page=1, page_size=1000, order_field="date", order_direction="asc")
+    options = { :query => { 
+      :date => date,
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
     response = get "opens", options
-    response.map{|item| Hashie::Mash.new(item)}
+    Hashie::Mash.new(response)
   end
-  
-  def clicks(date)
-    options = { :query => { :date => date } }
+
+  # Retrieves the subscriber clicks for this campaign.
+  def clicks(date, page=1, page_size=1000, order_field="date", order_direction="asc")
+    options = { :query => { 
+      :date => date,
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
     response = get "clicks", options
-    response.map{|item| Hashie::Mash.new(item)}
+    Hashie::Mash.new(response)
   end
-  
-  def unsubscribes(date)
-    options = { :query => { :date => date } }
+
+  # Retrieves the unsubscribes for this campaign.
+  def unsubscribes(date, page=1, page_size=1000, order_field="date", order_direction="asc")
+    options = { :query => { 
+      :date => date,
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
     response = get "unsubscribes", options
-    response.map{|item| Hashie::Mash.new(item)}
+    Hashie::Mash.new(response)
   end
-  
-  def bounces
-    response = get "bounces", {}
-    response.map{|item| Hashie::Mash.new(item)}
+
+  # Retrieves the bounces for this campaign.
+  def bounces(page=1, page_size=1000, order_field="date", order_direction="asc")
+    options = { :query => { 
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
+    response = get "bounces", options
+    Hashie::Mash.new(response)
   end
 
   private

data/lib/client.rb

@@ -1,6 +1,7 @@
 require 'createsend'
 require 'json'
 
+# Represents a client and associated functionality.
 class Client
   attr_reader :client_id
 
@@ -8,6 +9,7 @@ class Client
     @client_id = client_id
   end
 
+  # Creates a client.
   def self.create(company, contact_name, email, timezone, country)
     options = { :body => { 
       :CompanyName => company, 
@@ -18,41 +20,54 @@ class Client
     CreateSend.post "/clients.json", options
   end
 
+  # Gets the details of this client.
   def details
     response = CreateSend.get "/clients/#{client_id}.json", {}
     Hashie::Mash.new(response)
   end
 
+  # Gets the sent campaigns belonging to this client.
   def campaigns
     response = get 'campaigns'
     response.map{|item| Hashie::Mash.new(item)}
   end
 
+  # Gets the draft campaigns belonging to this client.
   def drafts
     response = get 'drafts'
     response.map{|item| Hashie::Mash.new(item)}
   end
 
+  # Gets the subscriber lists belonging to this client.
   def lists
     response = get 'lists'
     response.map{|item| Hashie::Mash.new(item)}
   end
 
+  # Gets the segments belonging to this client.
   def segments
     response = get 'segments'
     response.map{|item| Hashie::Mash.new(item)}
   end
 
-  def suppressionlist
-    response = get 'suppressionlist'
-    response.map{|item| Hashie::Mash.new(item)}
+  # Gets this client's suppression list.
+  def suppressionlist(page=1, page_size=1000, order_field="email", order_direction="asc")
+    options = { :query => { 
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
+    response = get 'suppressionlist', options
+    Hashie::Mash.new(response)
   end
-  
+
+  # Gets the templates belonging to this client.
   def templates
     response = get 'templates'
     response.map{|item| Hashie::Mash.new(item)}
   end
 
+  # Sets the basic details for this client.
   def set_basics(company, contact_name, email, timezone, country)
     options = { :body => { 
       :CompanyName => company, 
@@ -63,6 +78,7 @@ class Client
     put 'setbasics', options
   end
 
+  # Sets the access settings for this client.
   def set_access(username, password, access_level)
     options = { :body => { 
       :Username => username, 
@@ -71,6 +87,7 @@ class Client
     put 'setaccess', options
   end
 
+  # Sets the PAYG billing settings for this client.
   def set_payg_billing(currency, can_purchase_credits, client_pays, markup_percentage, 
     markup_on_delivery=0, markup_per_recipient=0, markup_on_design_spam_test=0)
     options = { :body => { 
@@ -84,6 +101,7 @@ class Client
     put 'setpaygbilling', options
   end
 
+  # Sets the monthly billing settings for this client.
   def set_monthly_billing(currency, can_purchase_credits, client_pays, markup_percentage)
     options = { :body => { 
       :Currency => currency,
@@ -93,6 +111,7 @@ class Client
     put 'setmonthlybilling', options
   end
 
+  # Deletes this client.
   def delete
     CreateSend.delete "/clients/#{client_id}.json", {}
   end

data/lib/createsend.rb

@@ -17,14 +17,18 @@ $LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
 require 'client'
 require 'campaign'
 require 'list'
+require 'segment'
 require 'subscriber'
 require 'template'
 
+# Represents a CreateSend API error and contains specific data about the error.
 class CreateSendError < StandardError
   attr_reader :data
   def initialize(data)
     @data = data
-    super "The CreateSend API responded with the following error - #{@data.Code}: #{@data.Message}"
+    # @data should contain Code, Message and optionally ResultData
+    extra = @data.ResultData ? "\nExtra result data: #{@data.ResultData}" : ""
+    super "The CreateSend API responded with the following error - #{@data.Code}: #{@data.Message}#{extra}"
   end
 end
 
@@ -35,21 +39,24 @@ class Unauthorized < ClientError; end
 class NotFound < ClientError; end
 class Unavailable < StandardError; end
 
+# Provides high level CreateSend functionality/data you'll probably need.
 class CreateSend
   include HTTParty
-  headers 'Content-Type' => 'application/json'
+
+  VER = "0.0.2" unless defined?(CreateSend::VER)
+  headers({ 'User-Agent' => "createsend-ruby-#{CreateSend::VER}", 'Content-Type' => 'application/json' })
   base_uri CreateSendOptions['base_uri']
   basic_auth CreateSendOptions['api_key'], 'x'
-  
-  VER = "0.0.1" unless defined?(CreateSend::VER)
-  
+
+  # Sets the API key which will be used to make calls to the CreateSend API.
   def self.api_key(api_key=nil)
     return @@api_key unless api_key
     CreateSendOptions['api_key'] = api_key
     @@api_key = api_key
     basic_auth @@api_key, 'x'
   end
-  
+
+  # Gets your CreateSend API key, given your site url, username and password.
   def apikey(site_url, username, password) 
     site_url = CGI.escape(site_url)
     self.class.basic_auth username, password
@@ -59,21 +66,25 @@ class CreateSend
     Hashie::Mash.new(response)
   end
 
+  # Gets your clients.
   def clients
     response = CreateSend.get('/clients.json')
     response.map{|item| Hashie::Mash.new(item)}
   end
 
+  # Gets valid countries.
   def countries
     response = CreateSend.get('/countries.json')
     response.parsed_response
   end
 
+  # Gets the current date in your account's timezone.
   def systemdate
     response = CreateSend.get('/systemdate.json')
     Hashie::Mash.new(response)
   end
 
+  # Gets valid timezones.
   def timezones
     response = CreateSend.get('/timezones.json')
     response.parsed_response
@@ -84,7 +95,7 @@ class CreateSend
   def self.put(*args); handle_response super end
   def self.delete(*args); handle_response super end
 
-  def self.handle_response(response)
+  def self.handle_response(response) # :nodoc:
     case response.code
     when 400
       raise BadRequest.new(Hashie::Mash.new response)

data/lib/list.rb

@@ -1,6 +1,7 @@
 require 'createsend'
 require 'json'
 
+# Represents a subscriber list and associated functionality.
 class List
   attr_reader :list_id
 
@@ -8,6 +9,7 @@ class List
     @list_id = list_id
   end
 
+  # Creates a new list for a client.
   def self.create(client_id, title, unsubscribe_page, confirmed_opt_in, confirmation_success_page)
     options = { :body => {
       :Title => title,
@@ -18,10 +20,12 @@ class List
     response.parsed_response
   end
 
+  # Deletes this list.
   def delete
     response = CreateSend.delete "/lists/#{list_id}.json", {}
   end
-  
+
+  # Creates a new custom field for this list.
   def create_custom_field(field_name, data_type, options=[])
     options = { :body => {
       :FieldName => field_name,
@@ -31,44 +35,82 @@ class List
     response.parsed_response
   end
 
+  # Deletes a custom field associated with this list.
   def delete_custom_field(custom_field_key)
     custom_field_key = CGI.escape(custom_field_key)
     response = CreateSend.delete "/lists/#{list_id}/customfields/#{custom_field_key}.json", {}
   end
-  
+
+  # Updates the options of a multi-optioned custom field on this list.
+  def update_custom_field_options(custom_field_key, new_options, keep_existing_options)
+    custom_field_key = CGI.escape(custom_field_key)
+    options = { :body => {
+      :Options => new_options,
+      :KeepExistingOptions => keep_existing_options }.to_json }
+    response = put "customfields/#{custom_field_key}/options", options
+  end
+
+  # Gets the details of this list.
   def details
     response = CreateSend.get "/lists/#{list_id}.json", {}
     Hashie::Mash.new(response)
   end
-  
+
+  # Gets the custom fields for this list.
   def custom_fields
     response = get "customfields"
     response.map{|item| Hashie::Mash.new(item)}
   end
-  
+
+  # Gets the segments for this list.
+  def segments
+    response = get "segments"
+    response.map{|item| Hashie::Mash.new(item)}
+  end
+
+  # Gets the stats for this list.
   def stats
     response = get "stats"
     Hashie::Mash.new(response)
   end
 
-  def active(date)
-    options = { :query => { :date => date } }
+  # Gets the active subscribers for this list.
+  def active(date, page=1, page_size=1000, order_field="email", order_direction="asc")
+    options = { :query => { 
+      :date => date,
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
     response = get "active", options
-    response.map{|item| Hashie::Mash.new(item)}
+    Hashie::Mash.new(response)
   end
 
-  def bounced(date)
-    options = { :query => { :date => date } }
+  # Gets the bounced subscribers for this list.
+  def bounced(date, page=1, page_size=1000, order_field="email", order_direction="asc")
+    options = { :query => { 
+      :date => date,
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
     response = get "bounced", options
-    response.map{|item| Hashie::Mash.new(item)}
+    Hashie::Mash.new(response)
   end
 
-  def unsubscribed(date)
-    options = { :query => { :date => date } }
+  # Gets the unsubscribed subscribers for this list.
+  def unsubscribed(date, page=1, page_size=1000, order_field="email", order_direction="asc")
+    options = { :query => { 
+      :date => date,
+      :page => page,
+      :pagesize => page_size,
+      :orderfield => order_field,
+      :orderdirection => order_direction } }
     response = get "unsubscribed", options
-    response.map{|item| Hashie::Mash.new(item)}
+    Hashie::Mash.new(response)
   end
 
+  # Updates this list.
   def update(title, unsubscribe_page, confirmed_opt_in, confirmation_success_page)
     options = { :body => {
       :Title => title,