createsend 1.1.1 → 2.0.0

data/Gemfile.lock

@@ -9,11 +9,15 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
+    activesupport (3.2.8)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
     fakeweb (1.3.0)
     hashie (1.2.0)
     httparty (0.8.1)
       multi_json
       multi_xml
+    i18n (0.6.0)
     jnunemaker-matchy (0.4.0)
     json (1.6.1)
     metaclass (0.0.1)
@@ -22,11 +26,12 @@ GEM
     multi_json (1.0.3)
     multi_xml (0.4.1)
     rake (0.9.2.2)
-    shoulda (3.0.1)
-      shoulda-context (~> 1.0.0)
-      shoulda-matchers (~> 1.0.0)
+    shoulda (3.1.1)
+      shoulda-context (~> 1.0)
+      shoulda-matchers (~> 1.2)
     shoulda-context (1.0.0)
-    shoulda-matchers (1.0.0)
+    shoulda-matchers (1.2.0)
+      activesupport (>= 3.0.0)
 
 PLATFORMS
   ruby
@@ -37,4 +42,4 @@ DEPENDENCIES
   jnunemaker-matchy (~> 0.4)
   mocha (~> 0.9)
   rake
-  shoulda (~> 3.0.1)
+  shoulda (~> 3.1.1)

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010 James Dennes
+Copyright (c) 2010-2012 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
@@ -16,4 +16,4 @@ 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.
+THE SOFTWARE.

data/createsend.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.add_development_dependency('fakeweb', '~> 1.3')
   s.add_development_dependency('jnunemaker-matchy', '~> 0.4')
   s.add_development_dependency('mocha', '~> 0.9')
-  s.add_development_dependency('shoulda', '~> 3.0.1')
+  s.add_development_dependency('shoulda', '~> 3.1.1')
   s.add_runtime_dependency('json')
   s.add_runtime_dependency('hashie', '~> 1.0')
   s.add_runtime_dependency('httparty', '~> 0.8')

data/lib/createsend.rb

@@ -18,39 +18,46 @@ require 'createsend/administrator'
 
 module CreateSend
 
-  # Just allows callers to do CreateSend.api_key "..." rather than CreateSend::CreateSend.api_key "..." etc
+  # Just allows callers to do CreateSend.api_key "..." rather than
+  # CreateSend::CreateSend.api_key "..." etc
   class << self
     def api_key(api_key=nil)
       r = CreateSend.api_key api_key
     end
-    
+
     def base_uri(uri)
       r = CreateSend.base_uri uri
     end
   end
 
-  # Represents a CreateSend API error and contains specific data about the error.
+  # Represents a CreateSend API error. Contains specific data about the error.
   class CreateSendError < StandardError
     attr_reader :data
     def initialize(data)
       @data = data
       # @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}"
+      super "The CreateSend API responded with the following error"\
+            " - #{@data.Code}: #{@data.Message}#{extra}"
     end
   end
 
+  # Raised for HTTP response codes of 400...500
   class ClientError < StandardError; end
+  # Raised for HTTP response codes of 500...600
   class ServerError < StandardError; end
+  # Raised for HTTP response code of 400
   class BadRequest < CreateSendError; end
+  # Raised for HTTP response code of 401
   class Unauthorized < CreateSendError; end
+  # Raised for HTTP response code of 404
   class NotFound < ClientError; end
-  class Unavailable < StandardError; end
 
   # Provides high level CreateSend functionality/data you'll probably need.
   class CreateSend
     include HTTParty
-    
+
+    # Deals with an unfortunate situation where responses aren't valid json.
     class Parser::DealWithCreateSendInvalidJson < HTTParty::Parser
       # The createsend API returns an ID as a string when a 201 Created
       # response is returned. Unfortunately this is invalid json.
@@ -65,8 +72,8 @@ module CreateSend
     parser Parser::DealWithCreateSendInvalidJson
     @@base_uri = "https://api.createsend.com/api/v3"
     @@api_key = ""
-    headers({ 
-      'User-Agent' => "createsend-ruby-#{VERSION}", 
+    headers({
+      'User-Agent' => "createsend-ruby-#{VERSION}",
       'Content-Type' => 'application/json; charset=utf-8',
       'Accept-Encoding' => 'gzip, deflate' })
     base_uri @@base_uri
@@ -80,7 +87,7 @@ module CreateSend
     end
 
     # Gets your CreateSend API key, given your site url, username and password.
-    def apikey(site_url, username, password) 
+    def apikey(site_url, username, password)
       site_url = CGI.escape(site_url)
       self.class.basic_auth username, password
       response = CreateSend.get("/apikey.json?SiteUrl=#{site_url}")
@@ -112,18 +119,18 @@ module CreateSend
       response = CreateSend.get('/timezones.json')
       response.parsed_response
     end
-    
+
     # Gets the administrators
     def administrators
       response = CreateSend.get('/admins.json')
       response.map{|item| Hashie::Mash.new(item)}
     end
-    
+
     def get_primary_contact
       response = CreateSend.get('/primarycontact.json')
       Hashie::Mash.new(response)
     end
-    
+
     def set_primary_contact(email)
       options = { :query => { :email => email } }
       response = CreateSend.put("/primarycontact.json", options)

data/lib/createsend/administrator.rb

@@ -26,7 +26,7 @@ module CreateSend
       response = CreateSend.post "/admins.json", options
       Hashie::Mash.new(response)
     end
-  
+
     # Updates the administator details
     def update(new_email_address, name)
       options = {
@@ -44,6 +44,6 @@ module CreateSend
     def delete
       options = { :query => { :email => @email_address } }
       CreateSend.delete '/admins.json', options
-    end   
+    end
   end
 end

data/lib/createsend/campaign.rb

@@ -11,9 +11,9 @@ module CreateSend
     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, segment_ids)
-      options = { :body => { 
+    def self.create(client_id, subject, name, from_name, from_email,
+      reply_to, html_url, text_url, list_ids, segment_ids)
+      options = { :body => {
         :Subject => subject,
         :Name => name,
         :FromName => from_name,
@@ -30,7 +30,8 @@ module CreateSend
     # Sends a preview of this campaign.
     def send_preview(recipients, personalize="fallback")
       options = { :body => {
-        :PreviewRecipients => recipients.kind_of?(String) ? [ recipients ] : recipients,
+        :PreviewRecipients => recipients.kind_of?(String) ?
+          [ recipients ] : recipients,
         :Personalize => personalize }.to_json }
       response = post "sendpreview", options
     end
@@ -60,15 +61,17 @@ module CreateSend
       Hashie::Mash.new(response)
     end
 
-    # Retrieves the lists and segments to which this campaaign will be (or was) sent.
+    # 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
 
     # Retrieves the recipients of this campaign.
-    def recipients(page=1, page_size=1000, order_field="email", order_direction="asc")
-      options = { :query => { 
+    def recipients(page=1, page_size=1000, order_field="email",
+      order_direction="asc")
+      options = { :query => {
         :page => page,
         :pagesize => page_size,
         :orderfield => order_field,
@@ -78,8 +81,9 @@ module CreateSend
     end
 
     # Retrieves the opens for this campaign.
-    def opens(date, page=1, page_size=1000, order_field="date", order_direction="asc")
-      options = { :query => { 
+    def opens(date, page=1, page_size=1000, order_field="date",
+      order_direction="asc")
+      options = { :query => {
         :date => date,
         :page => page,
         :pagesize => page_size,
@@ -90,8 +94,9 @@ module CreateSend
     end
 
     # Retrieves the subscriber clicks for this campaign.
-    def clicks(date, page=1, page_size=1000, order_field="date", order_direction="asc")
-      options = { :query => { 
+    def clicks(date, page=1, page_size=1000, order_field="date",
+      order_direction="asc")
+      options = { :query => {
         :date => date,
         :page => page,
         :pagesize => page_size,
@@ -102,8 +107,9 @@ module CreateSend
     end
 
     # Retrieves the unsubscribes for this campaign.
-    def unsubscribes(date, page=1, page_size=1000, order_field="date", order_direction="asc")
-      options = { :query => { 
+    def unsubscribes(date, page=1, page_size=1000, order_field="date",
+      order_direction="asc")
+      options = { :query => {
         :date => date,
         :page => page,
         :pagesize => page_size,
@@ -114,8 +120,9 @@ module CreateSend
     end
 
     # Retrieves the bounces for this campaign.
-    def bounces(date="1900-01-01", page=1, page_size=1000, order_field="date", order_direction="asc")
-      options = { :query => { 
+    def bounces(date="1900-01-01", page=1, page_size=1000, order_field="date",
+      order_direction="asc")
+      options = { :query => {
         :date => date,
         :page => page,
         :pagesize => page_size,

data/lib/createsend/client.rb

@@ -11,14 +11,9 @@ module CreateSend
     end
 
     # Creates a client.
-    def self.create(company, contact_name, email, timezone, country)
-      warn "[DEPRECATION] Use person.add or person.update to set the name on a particular person in a client. For now, we will create a default person with the name provided." unless contact_name.to_s == ''
-      warn "[DEPRECATION] Use person.add or person.update to set the email on a particular person in a client. For now, we will create a default person with the email provided." unless email.to_s == ''
-      
-      options = { :body => { 
-        :CompanyName => company, 
-        :ContactName => contact_name,
-        :EmailAddress => email,
+    def self.create(company, timezone, country)
+      options = { :body => {
+        :CompanyName => company,
         :TimeZone => timezone,
         :Country => country }.to_json }
       CreateSend.post "/clients.json", options
@@ -35,7 +30,7 @@ module CreateSend
       response = get 'campaigns'
       response.map{|item| Hashie::Mash.new(item)}
     end
-    
+
     # Gets the currently scheduled campaigns belonging to this client.
     def scheduled
       response = get 'scheduled'
@@ -54,23 +49,32 @@ module CreateSend
       response.map{|item| Hashie::Mash.new(item)}
     end
 
+    # Gets the lists across a client, to which a subscriber with a particular
+    # email address belongs.
+    # email_address - A String representing the subcriber's email address
+    def lists_for_email(email_address)
+      options = { :query => { :email => email_address } }
+      response = get 'listsforemail', options
+      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
-    
+
     # Gets the people associated with this client
     def people
       response = get "people"
       response.map{|item| Hashie::Mash.new(item)}
     end
-    
+
     def get_primary_contact
       response = get "primarycontact"
       Hashie::Mash.new(response)
     end
-    
+
     def set_primary_contact(email)
       options = { :query => { :email => email } }
       response = put "primarycontact", options
@@ -78,8 +82,9 @@ module CreateSend
     end
 
     # Gets this client's suppression list.
-    def suppressionlist(page=1, page_size=1000, order_field="email", order_direction="asc")
-      options = { :query => { 
+    def suppressionlist(page=1, page_size=1000, order_field="email",
+      order_direction="asc")
+      options = { :query => {
         :page => page,
         :pagesize => page_size,
         :orderfield => order_field,
@@ -95,23 +100,19 @@ module CreateSend
     end
 
     # Sets the basic details for this client.
-    def set_basics(company, contact_name, email, timezone, country)
-      warn "[DEPRECATION] Use person.update to set name on a particular person in a client. This will fail if there are multiple persons in a client." unless contact_name.to_s == ''
-      warn "[DEPRECATION] Use person.update to set email on a particular person in a client. This will fail if there are multiple persons in a client." unless email.to_s == ''
-            
-      options = { :body => { 
-        :CompanyName => company, 
-        :ContactName => contact_name,
-        :EmailAddress => email,
+    def set_basics(company, timezone, country)
+      options = { :body => {
+        :CompanyName => company,
         :TimeZone => timezone,
         :Country => country }.to_json }
       put 'setbasics', 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 => { 
+    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 => {
         :Currency => currency,
         :CanPurchaseCredits => can_purchase_credits,
         :ClientPays => client_pays,
@@ -124,24 +125,12 @@ module CreateSend
 
     # Sets the monthly billing settings for this client.
     def set_monthly_billing(currency, client_pays, markup_percentage)
-      options = { :body => { 
+      options = { :body => {
         :Currency => currency,
         :ClientPays => client_pays,
         :MarkupPercentage => markup_percentage }.to_json }
       put 'setmonthlybilling', options
     end
-    
-    # THIS METHOD IS DEPRECATED. It should only be used with existing integrations.
-    # Sets the access settings for this client.
-    def set_access(username, password, access_level)
-      warn "[DEPRECATION] `set_access` is deprecated. Use Person.update to set access on a particular person in a client."
-          
-      options = { :body => { 
-        :Username => username, 
-        :Password => password, 
-        :AccessLevel => access_level }.to_json }
-      put 'setaccess', options
-    end
 
     # Deletes this client.
     def delete

data/lib/createsend/list.rb

@@ -11,12 +11,26 @@ module CreateSend
     end
 
     # Creates a new list for a client.
-    def self.create(client_id, title, unsubscribe_page, confirmed_opt_in, confirmation_success_page)
+    # client_id - String representing the ID of the client for whom the list
+    #   will be created
+    # title - String representing the list title/name
+    # unsubscribe_page - String representing the url of the unsubscribe
+    #   confirmation page
+    # confirmed_opt_in - A Boolean representing whether this should be a
+    #   confirmed opt-in (double opt-in) list
+    # confirmation_success_page - String representing the url of the
+    #   confirmation success page
+    # unsubscribe_setting - A String which must be either "AllClientLists" or
+    #   "OnlyThisList". See the documentation for details:
+    #   http://www.campaignmonitor.com/api/lists/#creating_a_list
+    def self.create(client_id, title, unsubscribe_page, confirmed_opt_in,
+      confirmation_success_page, unsubscribe_setting="AllClientLists")
       options = { :body => {
         :Title => title,
         :UnsubscribePage => unsubscribe_page,
         :ConfirmedOptIn => confirmed_opt_in,
-        :ConfirmationSuccessPage => confirmation_success_page }.to_json }
+        :ConfirmationSuccessPage => confirmation_success_page,
+        :UnsubscribeSetting => unsubscribe_setting }.to_json }
       response = CreateSend.post "/lists/#{client_id}.json", options
       response.parsed_response
     end
@@ -39,11 +53,13 @@ module CreateSend
     # 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", {}
+      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)
+    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,
@@ -76,8 +92,9 @@ module CreateSend
     end
 
     # Gets the active subscribers for this list.
-    def active(date, page=1, page_size=1000, order_field="email", order_direction="asc")
-      options = { :query => { 
+    def active(date, page=1, page_size=1000, order_field="email",
+      order_direction="asc")
+      options = { :query => {
         :date => date,
         :page => page,
         :pagesize => page_size,
@@ -88,8 +105,9 @@ module CreateSend
     end
 
     # Gets the bounced subscribers for this list.
-    def bounced(date, page=1, page_size=1000, order_field="email", order_direction="asc")
-      options = { :query => { 
+    def bounced(date, page=1, page_size=1000, order_field="email",
+      order_direction="asc")
+      options = { :query => {
         :date => date,
         :page => page,
         :pagesize => page_size,
@@ -100,8 +118,9 @@ module CreateSend
     end
 
     # Gets the unsubscribed subscribers for this list.
-    def unsubscribed(date, page=1, page_size=1000, order_field="email", order_direction="asc")
-      options = { :query => { 
+    def unsubscribed(date, page=1, page_size=1000, order_field="email",
+      order_direction="asc")
+      options = { :query => {
         :date => date,
         :page => page,
         :pagesize => page_size,
@@ -112,8 +131,9 @@ module CreateSend
     end
 
     # Gets the deleted subscribers for this list.
-    def deleted(date, page=1, page_size=1000, order_field="email", order_direction="asc")
-      options = { :query => { 
+    def deleted(date, page=1, page_size=1000, order_field="email",
+      order_direction="asc")
+      options = { :query => {
         :date => date,
         :page => page,
         :pagesize => page_size,
@@ -124,12 +144,33 @@ module CreateSend
     end
 
     # Updates this list.
-    def update(title, unsubscribe_page, confirmed_opt_in, confirmation_success_page)
+    # title - String representing the list title/name
+    # unsubscribe_page - String representing the url of the unsubscribe
+    #   confirmation page
+    # confirmed_opt_in - A Boolean representing whether this should be a
+    #   confirmed opt-in (double opt-in) list
+    # confirmation_success_page - String representing the url of the
+    #   confirmation success page
+    # unsubscribe_setting - A String which must be either "AllClientLists" or
+    #   "OnlyThisList". See the documentation for details:
+    #   http://www.campaignmonitor.com/api/lists/#updating_a_list
+    # add_unsubscribes_to_supp_list - When unsubscribe_setting is
+    #   "AllClientLists", a Boolean which represents whether unsubscribes from
+    #   this list should be added to the suppression list
+    # scrub_active_with_supp_list - When unsubscribe_setting is
+    #   "AllClientLists", a Boolean which represents whether active sunscribers
+    #   should be scrubbed against the suppression list
+    def update(title, unsubscribe_page, confirmed_opt_in,
+      confirmation_success_page, unsubscribe_setting="AllClientLists",
+      add_unsubscribes_to_supp_list=false, scrub_active_with_supp_list=false)
       options = { :body => {
         :Title => title,
         :UnsubscribePage => unsubscribe_page,
         :ConfirmedOptIn => confirmed_opt_in,
-        :ConfirmationSuccessPage => confirmation_success_page }.to_json }
+        :ConfirmationSuccessPage => confirmation_success_page,
+        :UnsubscribeSetting => unsubscribe_setting,
+        :AddUnsubscribesToSuppList => add_unsubscribes_to_supp_list,
+        :ScrubActiveWithSuppList => scrub_active_with_supp_list }.to_json }
       response = CreateSend.put "/lists/#{list_id}.json", options
     end
 
@@ -139,7 +180,7 @@ module CreateSend
       response.map{|item| Hashie::Mash.new(item)}
     end
 
-    # Creates a new webhook for the specified events (an array of strings). 
+    # Creates a new webhook for the specified events (an array of strings).
     # Valid events are "Subscribe", "Deactivate", and "Update".
     # Valid payload formats are "json", and "xml".
     def create_webhook(events, url, payload_format)
@@ -160,7 +201,8 @@ module CreateSend
 
     # Deletes a webhook associated with this list.
     def delete_webhook(webhook_id)
-      response = CreateSend.delete "/lists/#{list_id}/webhooks/#{webhook_id}.json", {}
+      response = CreateSend.delete(
+        "/lists/#{list_id}/webhooks/#{webhook_id}.json", {})
     end
 
     # Activates a webhook associated with this list.

data/lib/createsend/person.rb

@@ -19,7 +19,7 @@ module CreateSend
       Hashie::Mash.new(response)
     end
 
-    # Adds a person to the client. password is optional. if ommitted, an 
+    # Adds a person to the client. password is optional. if ommitted, an
     # email invitation will be sent to the person
     def self.add(client_id, email_address, name, access_level, password)
       options = { :body => {
@@ -30,8 +30,9 @@ module CreateSend
       response = CreateSend.post "/clients/#{client_id}/people.json", options
       Hashie::Mash.new(response)
     end
-  
-    # Updates the person details. password is optional and will only be updated if supplied
+
+    # Updates the person details. password is optional and will only be
+    # updated if supplied
     def update(new_email_address, name, access_level, password)
       options = {
         :query => { :email => @email_address },
@@ -50,7 +51,7 @@ module CreateSend
       options = { :query => { :email => @email_address } }
       CreateSend.delete uri_for(client_id), options
     end
-    
+
     def uri_for(client_id)
          "/clients/#{client_id}/people.json"
     end

data/lib/createsend/segment.rb

@@ -36,7 +36,8 @@ module CreateSend
     end
 
     # Gets the active subscribers in this segment.
-    def subscribers(date, page=1, page_size=1000, order_field="email", order_direction="asc")
+    def subscribers(date, page=1, page_size=1000, order_field="email",
+      order_direction="asc")
       options = { :query => {
         :date => date,
         :page => page,
@@ -62,7 +63,7 @@ module CreateSend
     def delete
       response = CreateSend.delete "/segments/#{segment_id}.json", {}
     end
-  
+
     private
 
     def get(action, options = {})

data/lib/createsend/subscriber.rb

@@ -20,31 +20,39 @@ module CreateSend
     end
 
     # Adds a subscriber to a subscriber list.
-    def self.add(list_id, email_address, name, custom_fields, resubscribe, restart_subscription_based_autoresponders=false)
+    def self.add(list_id, email_address, name, custom_fields, resubscribe,
+      restart_subscription_based_autoresponders=false)
       options = { :body => {
         :EmailAddress => email_address,
         :Name => name,
         :CustomFields => custom_fields,
         :Resubscribe => resubscribe,
-        :RestartSubscriptionBasedAutoresponders => restart_subscription_based_autoresponders }.to_json }
+        :RestartSubscriptionBasedAutoresponders =>
+          restart_subscription_based_autoresponders }.to_json }
       response = CreateSend.post "/subscribers/#{list_id}.json", options
       response.parsed_response
     end
 
     # Imports subscribers into a subscriber list.
-    def self.import(list_id, subscribers, resubscribe, queue_subscription_based_autoresponders=false, restart_subscription_based_autoresponders=false)
+    def self.import(list_id, subscribers, resubscribe,
+      queue_subscription_based_autoresponders=false,
+      restart_subscription_based_autoresponders=false)
       options = { :body => {
         :Subscribers => subscribers,
         :Resubscribe => resubscribe,
-        :QueueSubscriptionBasedAutoresponders => queue_subscription_based_autoresponders,
-        :RestartSubscriptionBasedAutoresponders => restart_subscription_based_autoresponders }.to_json }
+        :QueueSubscriptionBasedAutoresponders =>
+          queue_subscription_based_autoresponders,
+        :RestartSubscriptionBasedAutoresponders =>
+          restart_subscription_based_autoresponders }.to_json }
       begin
-        response = CreateSend.post "/subscribers/#{list_id}/import.json", options
+        response = CreateSend.post(
+          "/subscribers/#{list_id}/import.json", options)
       rescue BadRequest => br
-        # Subscriber import will throw BadRequest if some subscribers are not imported
-        # successfully. If this occurs, we want to return the ResultData property of
-        # the BadRequest exception (which is of the same "form" as the response we'd 
-        # receive upon a completely successful import)
+        # Subscriber import will throw BadRequest if some subscribers are not
+        # imported successfully. If this occurs, we want to return the
+        # ResultData property of the BadRequest exception (which is of the
+        # same "form" as the response we would receive upon a completely
+        # successful import).
         if br.data.ResultData
           return br.data.ResultData
         else
@@ -54,9 +62,10 @@ module CreateSend
       Hashie::Mash.new(response)
     end
 
-    # Updates any aspect of a subscriber, including email address, name, and 
+    # Updates any aspect of a subscriber, including email address, name, and
     # custom field data if supplied.
-    def update(new_email_address, name, custom_fields, resubscribe, restart_subscription_based_autoresponders=false)
+    def update(new_email_address, name, custom_fields, resubscribe,
+      restart_subscription_based_autoresponders=false)
       options = {
         :query => { :email => @email_address },
         :body => {
@@ -64,7 +73,8 @@ module CreateSend
           :Name => name,
           :CustomFields => custom_fields,
           :Resubscribe => resubscribe,
-          :RestartSubscriptionBasedAutoresponders => restart_subscription_based_autoresponders }.to_json }
+          :RestartSubscriptionBasedAutoresponders =>
+            restart_subscription_based_autoresponders }.to_json }
       CreateSend.put "/subscribers/#{@list_id}.json", options
       # Update @email_address, so this object can continue to be used reliably
       @email_address = new_email_address

data/lib/createsend/template.rb

@@ -12,7 +12,7 @@ module CreateSend
 
     # Creates a new email template.
     def self.create(client_id, name, html_url, zip_url)
-      options = { :body => { 
+      options = { :body => {
         :Name => name,
         :HtmlPageURL => html_url,
         :ZipFileURL => zip_url }.to_json }
@@ -28,7 +28,7 @@ module CreateSend
 
     # Updates this email template.
     def update(name, html_url, zip_url)
-      options = { :body => { 
+      options = { :body => {
         :Name => name,
         :HtmlPageURL => html_url,
         :ZipFileURL => zip_url }.to_json }

data/lib/createsend/version.rb

@@ -1,3 +1,3 @@
 module CreateSend
-  VERSION = "1.1.1" unless defined?(CreateSend::VERSION)
+  VERSION = "2.0.0" unless defined?(CreateSend::VERSION)
 end

data/test/client_test.rb

@@ -11,7 +11,7 @@ class ClientTest < Test::Unit::TestCase
 
     should "create a client" do
       stub_post(@api_key, "clients.json", "create_client.json")
-      client_id = CreateSend::Client.create "Client Company Name", "Client Contact Name", "client@example.com", "(GMT+10:00) Canberra, Melbourne, Sydney", "Australia"
+      client_id = CreateSend::Client.create "Client Company Name", "(GMT+10:00) Canberra, Melbourne, Sydney", "Australia"
       client_id.should == "32a381c49a2df99f1d0c6f3c112352b9"
     end
     
@@ -68,7 +68,18 @@ class ClientTest < Test::Unit::TestCase
       lists.first.ListID.should == 'a58ee1d3039b8bec838e6d1482a8a965'
       lists.first.Name.should == 'List One'
     end
-    
+
+    should "get all lists to which a subscriber with a particular email address belongs" do
+      email = "valid@example.com"
+      stub_get(@api_key, "clients/#{@client.client_id}/listsforemail.json?email=#{CGI.escape(email)}", "listsforemail.json")
+      lists = @client.lists_for_email(email)
+      lists.size.should == 2
+      lists.first.ListID.should == 'ab4a2b57c7c8f1ba62f898a1af1a575b'
+      lists.first.ListName.should == 'List Number One'
+      lists.first.SubscriberState.should == 'Active'
+      lists.first.DateSubscriberAdded.should == '2012-08-20 22:32:00'
+    end
+
     should "get all segments for a client" do
       stub_get(@api_key, "clients/#{@client.client_id}/segments.json", "segments.json")
       segments = @client.segments
@@ -94,7 +105,7 @@ class ClientTest < Test::Unit::TestCase
       res.Results.first.Date.should == "2010-10-26 10:55:31"
       res.Results.first.State.should == "Suppressed"
     end
-    
+
     should "get all people" do
       stub_get(@api_key, "clients/#{@client.client_id}/people.json", "people.json")
       people = @client.people
@@ -112,40 +123,35 @@ class ClientTest < Test::Unit::TestCase
       templates.first.TemplateID.should == '5cac213cf061dd4e008de5a82b7a3621'
       templates.first.Name.should == 'Template One'
     end
-    
+
     should "set primary contact" do
       email = 'person@blackhole.com'
       stub_put(@api_key, "clients/#{@client.client_id}/primarycontact.json?email=#{CGI.escape(email)}", 'client_set_primary_contact.json')
       result = @client.set_primary_contact email
       result.EmailAddress.should == email
     end
-    
+
     should "get primary contact" do
       stub_get(@api_key, "clients/#{@client.client_id}/primarycontact.json", 'client_get_primary_contact.json')
       result = @client.get_primary_contact
       result.EmailAddress.should == 'person@blackhole.com'
     end
-    
+
     should "set basics" do
       stub_put(@api_key, "clients/#{@client.client_id}/setbasics.json", nil)
-      @client.set_basics "Client Company Name", "Client Contact Name", "client@example.com", "(GMT+10:00) Canberra, Melbourne, Sydney", "Australia"
+      @client.set_basics "Client Company Name", "(GMT+10:00) Canberra, Melbourne, Sydney", "Australia"
     end
-    
-    should "set access" do
-      stub_put(@api_key, "clients/#{@client.client_id}/setaccess.json", nil)
-      @client.set_access "username", "password", 321
-    end
-    
+
     should "set payg billing" do
       stub_put(@api_key, "clients/#{@client.client_id}/setpaygbilling.json", nil)
       @client.set_payg_billing "CAD", true, true, 150
     end
-    
+
     should "set monthly billing" do
       stub_put(@api_key, "clients/#{@client.client_id}/setmonthlybilling.json", nil)
       @client.set_monthly_billing "CAD", true, 150
     end
-    
+
     should "delete a client" do
       stub_delete(@api_key, "clients/#{@client.client_id}.json", nil)
       @client.delete

data/test/createsend_test.rb

@@ -103,7 +103,7 @@ class CreateSendTest < Test::Unit::TestCase
       context "#{status.first}, a post" do
         should "raise a #{exception.name} error" do
           stub_post(@api_key, "clients.json", (status.first == '400' or status.first == '401') ? 'custom_api_error.json' : nil, status)
-          lambda { CreateSend::Client.create "Client Company Name", "Client Contact Name", "client@example.com", 
+          lambda { CreateSend::Client.create "Client Company Name", 
             "(GMT+10:00) Canberra, Melbourne, Sydney", "Australia" }.should raise_error(exception)
         end
       end

data/test/fixtures/list_details.json

@@ -3,5 +3,6 @@
   "Title": "a non-basic list :)",
   "UnsubscribePage": "",
   "ListID": "2fe4c8f0373ce320e2200596d7ef168f",
-  "ConfirmationSuccessPage": ""
+  "ConfirmationSuccessPage": "",
+  "UnsubscribeSetting": "AllClientLists"
 }

data/test/fixtures/listsforemail.json

@@ -0,0 +1,14 @@
+[
+  {
+    "ListID": "ab4a2b57c7c8f1ba62f898a1af1a575b",
+    "ListName": "List Number One",
+    "SubscriberState": "Active",
+    "DateSubscriberAdded": "2012-08-20 22:32:00"
+  },
+  {
+    "ListID": "d8e59b07138cf1316a6587007c443e21",
+    "ListName": "List Number Two",
+    "SubscriberState": "Unsubscribed",
+    "DateSubscriberAdded": "2012-08-21 01:35:00"
+  }
+]

data/test/list_test.rb

@@ -10,17 +10,33 @@ class ListTest < Test::Unit::TestCase
       @list = CreateSend::List.new @list_id
     end
 
-    should "create a list" do
+    should "create a list without passing in unsubscribe setting" do
       stub_post(@api_key, "lists/#{@client_id}.json", "create_list.json")
       list_id = CreateSend::List.create @client_id, "List One", "", false, ""
       list_id.should == "e3c5f034d68744f7881fdccf13c2daee"
     end
 
-    should "update a list" do
+    should "create a list passing in unsubscribe setting" do
+      stub_post(@api_key, "lists/#{@client_id}.json", "create_list.json")
+      list_id = CreateSend::List.create @client_id, "List One", "", false, "", "OnlyThisList"
+      list_id.should == "e3c5f034d68744f7881fdccf13c2daee"
+    end
+
+    should "update a list without passing in unsubscribe setting" do
       stub_put(@api_key, "lists/#{@list.list_id}.json", nil)
       @list.update "List One Renamed", "", false, ""
     end
 
+    should "update a list passing in unsubscribe setting" do
+      stub_put(@api_key, "lists/#{@list.list_id}.json", nil)
+      @list.update "List One Renamed", "", false, "", "OnlyThisList"
+    end
+
+    should "update a list passing in unsubscribe setting and suppression list options" do
+      stub_put(@api_key, "lists/#{@list.list_id}.json", nil)
+      @list.update "List One Renamed", "", false, "", "OnlyThisList", true, true
+    end
+
     should "delete a list" do
       stub_delete(@api_key, "lists/#{@list.list_id}.json", nil)
       @list.delete
@@ -53,6 +69,7 @@ class ListTest < Test::Unit::TestCase
       details.UnsubscribePage.should == ""
       details.ListID.should == "2fe4c8f0373ce320e2200596d7ef168f"
       details.ConfirmationSuccessPage.should == ""
+      details.UnsubscribeSetting.should == "AllClientLists"
     end
 
     should "get the custom fields for a list" do

metadata

@@ -1,115 +1,111 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: createsend
-version: !ruby/object:Gem::Version 
+version: !ruby/object:Gem::Version
+  version: 2.0.0
   prerelease: 
-  version: 1.1.1
 platform: ruby
-authors: 
+authors:
 - James Dennes
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-08-02 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-08-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rake
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70279968073360 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
   prerelease: false
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
+  version_requirements: *70279968073360
+- !ruby/object:Gem::Dependency
   name: fakeweb
-  requirement: &id002 !ruby/object:Gem::Requirement 
+  requirement: &70279968072660 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "1.3"
+      - !ruby/object:Gem::Version
+        version: '1.3'
   type: :development
   prerelease: false
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
+  version_requirements: *70279968072660
+- !ruby/object:Gem::Dependency
   name: jnunemaker-matchy
-  requirement: &id003 !ruby/object:Gem::Requirement 
+  requirement: &70279968072160 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "0.4"
+      - !ruby/object:Gem::Version
+        version: '0.4'
   type: :development
   prerelease: false
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
+  version_requirements: *70279968072160
+- !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &70279968071620 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "0.9"
+      - !ruby/object:Gem::Version
+        version: '0.9'
   type: :development
   prerelease: false
-  version_requirements: *id004
-- !ruby/object:Gem::Dependency 
+  version_requirements: *70279968071620
+- !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &70279968070900 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: 3.0.1
+      - !ruby/object:Gem::Version
+        version: 3.1.1
   type: :development
   prerelease: false
-  version_requirements: *id005
-- !ruby/object:Gem::Dependency 
+  version_requirements: *70279968070900
+- !ruby/object:Gem::Dependency
   name: json
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: &70279968070360 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *id006
-- !ruby/object:Gem::Dependency 
+  version_requirements: *70279968070360
+- !ruby/object:Gem::Dependency
   name: hashie
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  requirement: &70279968069500 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "1.0"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :runtime
   prerelease: false
-  version_requirements: *id007
-- !ruby/object:Gem::Dependency 
+  version_requirements: *70279968069500
+- !ruby/object:Gem::Dependency
   name: httparty
-  requirement: &id008 !ruby/object:Gem::Requirement 
+  requirement: &70279968068780 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
+    requirements:
     - - ~>
-      - !ruby/object:Gem::Version 
-        version: "0.8"
+      - !ruby/object:Gem::Version
+        version: '0.8'
   type: :runtime
   prerelease: false
-  version_requirements: *id008
+  version_requirements: *70279968068780
 description: Implements the complete functionality of the createsend API.
-email: 
+email:
 - jdennes@gmail.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - .travis.yml
 - Gemfile
@@ -172,6 +168,7 @@ files:
 - test/fixtures/list_stats.json
 - test/fixtures/list_webhooks.json
 - test/fixtures/lists.json
+- test/fixtures/listsforemail.json
 - test/fixtures/people.json
 - test/fixtures/person_details.json
 - test/fixtures/scheduled_campaigns.json
@@ -194,32 +191,30 @@ files:
 - test/template_test.rb
 homepage: http://github.com/campaignmonitor/createsend-ruby/
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
       version: 1.3.6
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.17
+rubygems_version: 1.8.15
 signing_key: 
 specification_version: 3
-summary: A library which implements the complete functionality of v3 of the createsend API.
-test_files: 
+summary: A library which implements the complete functionality of v3 of the createsend
+  API.
+test_files:
 - test/administrator_test.rb
 - test/campaign_test.rb
 - test/client_test.rb
@@ -264,6 +259,7 @@ test_files:
 - test/fixtures/list_stats.json
 - test/fixtures/list_webhooks.json
 - test/fixtures/lists.json
+- test/fixtures/listsforemail.json
 - test/fixtures/people.json
 - test/fixtures/person_details.json
 - test/fixtures/scheduled_campaigns.json