createsend 2.4.0 → 2.5.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    createsend (2.4.0)
+    createsend (2.5.0)
       hashie (~> 1.0)
       httparty (~> 0.8)
       json
@@ -25,7 +25,7 @@ GEM
     mocha (0.10.0)
       metaclass (~> 0.0.1)
     multi_json (1.0.3)
-    multi_xml (0.4.4)
+    multi_xml (0.5.1)
     rake (0.9.2.2)
     shoulda (3.3.0)
       shoulda-context (~> 1.0)

data/HISTORY.md

@@ -1,5 +1,14 @@
 # createsend-ruby history
 
+## v2.5.0 - 11 Dec, 2012   (3054885)
+
+* Added support for including from name, from email, and reply to email in
+drafts, scheduled, and sent campaigns.
+* Added support for campaign text version urls.
+* Added support for transferring credits to/from a client.
+* Added support for getting account billing details as well as client credits.
+* Made all date fields optional when getting paged results.
+
 ## v2.4.0 - 5 Nov, 2012   (4277d8d9)
 
 * Added CreateSend::Campaign#email_client_usage.

data/README.md

@@ -8,10 +8,14 @@ A ruby library which implements the complete functionality of v3 of the [Campaig
 
     gem install createsend
 
+## Documentation
+
+Full documentation is hosted by [RubyDoc.info](http://rubydoc.info/gems/createsend/frames).
+
 ## Examples
 
 ### Basic usage
-Retrieve a list of all your clients.
+This example of listing all your clients demonstrates basic usage of the library:
 
     require 'createsend'
 
@@ -24,13 +28,13 @@ Retrieve a list of all your clients.
       puts "#{c.ClientID}: #{c.Name}"
     end
 
-Results in:
-    
+Running this example will result in something like:
+
     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:
+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'
 

data/lib/createsend.rb

@@ -102,6 +102,12 @@ module CreateSend
       response.map{|item| Hashie::Mash.new(item)}
     end
 
+    # Get your billing details.
+    def billing_details
+      response = CreateSend.get('/billingdetails.json')
+      Hashie::Mash.new(response)
+    end
+
     # Gets valid countries.
     def countries
       response = CreateSend.get('/countries.json')

data/lib/createsend/campaign.rb

@@ -138,7 +138,7 @@ module CreateSend
     end
 
     # Retrieves the opens for this campaign.
-    def opens(date, page=1, page_size=1000, order_field="date",
+    def opens(date="", page=1, page_size=1000, order_field="date",
       order_direction="asc")
       options = { :query => {
         :date => date,
@@ -151,7 +151,7 @@ module CreateSend
     end
 
     # Retrieves the subscriber clicks for this campaign.
-    def clicks(date, page=1, page_size=1000, order_field="date",
+    def clicks(date="", page=1, page_size=1000, order_field="date",
       order_direction="asc")
       options = { :query => {
         :date => date,
@@ -164,7 +164,7 @@ module CreateSend
     end
 
     # Retrieves the unsubscribes for this campaign.
-    def unsubscribes(date, page=1, page_size=1000, order_field="date",
+    def unsubscribes(date="", page=1, page_size=1000, order_field="date",
       order_direction="asc")
       options = { :query => {
         :date => date,
@@ -177,7 +177,7 @@ module CreateSend
     end
 
     # Retrieves the spam complaints for this campaign.
-    def spam(date, page=1, page_size=1000, order_field="date",
+    def spam(date="", page=1, page_size=1000, order_field="date",
       order_direction="asc")
       options = { :query => {
         :date => date,
@@ -190,7 +190,7 @@ module CreateSend
     end
 
     # Retrieves the bounces for this campaign.
-    def bounces(date="1900-01-01", page=1, page_size=1000, order_field="date",
+    def bounces(date="", page=1, page_size=1000, order_field="date",
       order_direction="asc")
       options = { :query => {
         :date => date,

data/lib/createsend/client.rb

@@ -150,6 +150,33 @@ module CreateSend
       put 'setmonthlybilling', options
     end
 
+    # Transfer credits to or from this client.
+    #
+    # credits - An Integer representing the number of credits to transfer.
+    #   This value may be either positive if you want to allocate credits from
+    #   your account to the client, or negative if you want to deduct credits
+    #   from the client back into your account.
+    # can_use_my_credits_when_they_run_out - A Boolean value representing
+    #   which, if set to true, will allow the client to continue sending using
+    #   your credits or payment details once they run out of credits, and if
+    #   set to false, will prevent the client from using your credits to
+    #   continue sending until you allocate more credits to them.
+    #
+    # Returns an object of the following form representing the result:
+    # {
+    #   AccountCredits # Integer representing credits in your account now
+    #   ClientCredits # Integer representing credits in this client's
+    #     account now
+    # }
+    def transfer_credits(credits, can_use_my_credits_when_they_run_out)
+      options = { :body => {
+        :Credits => credits,
+        :CanUseMyCreditsWhenTheyRunOut => can_use_my_credits_when_they_run_out
+      }.to_json }
+      response = post 'credits', options
+      Hashie::Mash.new(response)
+    end
+
     # Deletes this client.
     def delete
       CreateSend.delete "/clients/#{client_id}.json", {}

data/lib/createsend/list.rb

@@ -117,7 +117,7 @@ module CreateSend
     end
 
     # Gets the active subscribers for this list.
-    def active(date, page=1, page_size=1000, order_field="email",
+    def active(date="", page=1, page_size=1000, order_field="email",
       order_direction="asc")
       options = { :query => {
         :date => date,
@@ -130,7 +130,7 @@ module CreateSend
     end
 
     # Gets the unconfirmed subscribers for this list.
-    def unconfirmed(date, page=1, page_size=1000, order_field="email",
+    def unconfirmed(date="", page=1, page_size=1000, order_field="email",
       order_direction="asc")
       options = { :query => {
         :date => date,
@@ -143,7 +143,7 @@ module CreateSend
     end
 
     # Gets the bounced subscribers for this list.
-    def bounced(date, page=1, page_size=1000, order_field="email",
+    def bounced(date="", page=1, page_size=1000, order_field="email",
       order_direction="asc")
       options = { :query => {
         :date => date,
@@ -156,7 +156,7 @@ module CreateSend
     end
 
     # Gets the unsubscribed subscribers for this list.
-    def unsubscribed(date, page=1, page_size=1000, order_field="email",
+    def unsubscribed(date="", page=1, page_size=1000, order_field="email",
       order_direction="asc")
       options = { :query => {
         :date => date,
@@ -169,7 +169,7 @@ module CreateSend
     end
 
     # Gets the deleted subscribers for this list.
-    def deleted(date, page=1, page_size=1000, order_field="email",
+    def deleted(date="", page=1, page_size=1000, order_field="email",
       order_direction="asc")
       options = { :query => {
         :date => date,

data/lib/createsend/segment.rb

@@ -36,7 +36,7 @@ module CreateSend
     end
 
     # Gets the active subscribers in this segment.
-    def subscribers(date, page=1, page_size=1000, order_field="email",
+    def subscribers(date="", page=1, page_size=1000, order_field="email",
       order_direction="asc")
       options = { :query => {
         :date => date,

data/lib/createsend/version.rb

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

data/test/campaign_test.rb

@@ -149,6 +149,7 @@ class CampaignTest < Test::Unit::TestCase
       summary.Forwards.should == 11
       summary.Likes.should == 32
       summary.WebVersionURL.should == "http://createsend.com/t/r-3A433FC72FFE3B8B"
+      summary.WebVersionTextURL.should == "http://createsend.com/t/r-3A433FC72FFE3B8B/t"
       summary.WorldviewURL.should == "http://client.createsend.com/reports/wv/r/3A433FC72FFE3B8B"
       summary.SpamComplaints.should == 23
     end
@@ -189,7 +190,7 @@ class CampaignTest < Test::Unit::TestCase
       res.Results.first.EmailAddress.should == "subs+6g76t7t0@example.com"
       res.Results.first.ListID.should == "a994a3caf1328a16af9a69a730eaa706"
     end
-    
+
     should "get the opens for a campaign" do
       min_date = "2010-01-01"
       stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/opens.json?page=1&pagesize=1000&orderfield=date&orderdirection=asc&date=#{CGI.escape(min_date)}", "campaign_opens.json")
@@ -238,7 +239,7 @@ class CampaignTest < Test::Unit::TestCase
       clicks.TotalNumberOfRecords.should == 3
       clicks.NumberOfPages.should == 1
     end
-    
+
     should "get the unsubscribes for a campaign" do
       min_date = "2010-01-01"
       stub_get(@api_key, "campaigns/#{@campaign.campaign_id}/unsubscribes.json?page=1&pagesize=1000&orderfield=date&orderdirection=asc&date=#{CGI.escape(min_date)}", "campaign_unsubscribes.json")

data/test/client_test.rb

@@ -24,6 +24,7 @@ class ClientTest < Test::Unit::TestCase
       cl.AccessDetails.Username.should == "clientone"
       cl.AccessDetails.AccessLevel.should == 23
       cl.BillingDetails.MonthlyScheme.should == "Basic"
+      cl.BillingDetails.Credits.should == 500
     end
 
     should "get all campaigns" do
@@ -32,10 +33,14 @@ class ClientTest < Test::Unit::TestCase
       campaigns.size.should == 2
       campaigns.first.CampaignID.should == 'fc0ce7105baeaf97f47c99be31d02a91'
       campaigns.first.WebVersionURL.should == 'http://createsend.com/t/r-765E86829575EE2C'
+      campaigns.first.WebVersionTextURL.should == 'http://createsend.com/t/r-765E86829575EE2C/t'
       campaigns.first.Subject.should == 'Campaign One'
       campaigns.first.Name.should == 'Campaign One'
       campaigns.first.SentDate.should == '2010-10-12 12:58:00'
       campaigns.first.TotalRecipients.should == 2245
+      campaigns.first.FromName.should == 'My Name'
+      campaigns.first.FromEmail.should == 'myemail@example.com'
+      campaigns.first.ReplyTo.should == 'myemail@example.com'
     end
 
     should "get scheduled campaigns" do
@@ -49,6 +54,10 @@ class ClientTest < Test::Unit::TestCase
       campaigns.first.Subject.should == "Magic Issue One"
       campaigns.first.DateCreated.should == "2011-05-24 10:37:00"
       campaigns.first.PreviewURL.should == "http://createsend.com/t/r-DD543521A87C9B8B"
+      campaigns.first.PreviewTextURL.should == "http://createsend.com/t/r-DD543521A87C9B8B/t"
+      campaigns.first.FromName.should == 'My Name'
+      campaigns.first.FromEmail.should == 'myemail@example.com'
+      campaigns.first.ReplyTo.should == 'myemail@example.com'
     end
 
     should "get all drafts" do
@@ -60,6 +69,10 @@ class ClientTest < Test::Unit::TestCase
       drafts.first.Subject.should == 'Draft One'
       drafts.first.DateCreated.should == '2010-08-19 16:08:00'
       drafts.first.PreviewURL.should == 'http://createsend.com/t/r-E97A7BB2E6983DA1'
+      drafts.first.PreviewTextURL.should == 'http://createsend.com/t/r-E97A7BB2E6983DA1/t'
+      drafts.first.FromName.should == 'My Name'
+      drafts.first.FromEmail.should == 'myemail@example.com'
+      drafts.first.ReplyTo.should == 'myemail@example.com'
     end
 
     should "get all lists" do
@@ -194,7 +207,14 @@ class ClientTest < Test::Unit::TestCase
       request.include?("\"MarkupPercentage\":120").should == true
       request.include?("\"MonthlyScheme\":\"Unlimited\"").should == true
     end
-     
+
+    should "transfer credits to a client" do
+      stub_post(@api_key, "clients/#{@client.client_id}/credits.json", "transfer_credits.json")
+      result = @client.transfer_credits 200, false
+      result.AccountCredits.should == 800
+      result.ClientCredits.should == 200
+    end
+
     should "delete a client" do
       stub_delete(@api_key, "clients/#{@client.client_id}.json", nil)
       @client.delete

data/test/createsend_test.rb

@@ -34,7 +34,13 @@ class CreateSendTest < Test::Unit::TestCase
       clients.first.ClientID.should == '4a397ccaaa55eb4e6aa1221e1e2d7122'
       clients.first.Name.should == 'Client One'
     end
-    
+
+    should "get billing details" do
+      stub_get(@api_key, "billingdetails.json", "billingdetails.json")
+      bd = @cs.billing_details
+      bd.Credits.should == 3021
+    end
+
     should "get all countries" do
       stub_get(@api_key, "countries.json", "countries.json")
       countries = @cs.countries

data/test/fixtures/billingdetails.json

@@ -0,0 +1,3 @@
+{
+  "Credits": 3021
+}

data/test/fixtures/campaign_summary.json

@@ -9,6 +9,7 @@
   "Forwards": 11,
   "Likes": 32,
   "WebVersionURL": "http://createsend.com/t/r-3A433FC72FFE3B8B",
+  "WebVersionTextURL": "http://createsend.com/t/r-3A433FC72FFE3B8B/t",
   "WorldviewURL": "http://client.createsend.com/reports/wv/r/3A433FC72FFE3B8B",
   "SpamComplaints": 23
 }

data/test/fixtures/campaigns.json

@@ -1,17 +1,25 @@
 [
   {
     "WebVersionURL": "http://createsend.com/t/r-765E86829575EE2C",
+    "WebVersionTextURL": "http://createsend.com/t/r-765E86829575EE2C/t",
     "CampaignID": "fc0ce7105baeaf97f47c99be31d02a91",
     "Subject": "Campaign One",
     "Name": "Campaign One",
+    "FromName": "My Name",
+    "FromEmail": "myemail@example.com",
+    "ReplyTo": "myemail@example.com",
     "SentDate": "2010-10-12 12:58:00",
     "TotalRecipients": 2245
   },
   {
     "WebVersionURL": "http://createsend.com/t/r-DD543566A87C9B8B",
+    "WebVersionTextURL": "http://createsend.com/t/r-DD543566A87C9B8B/t",
     "CampaignID": "072472b88c853ae5dedaeaf549a8d607",
     "Subject": "Campaign Two",
     "Name": "Campaign Two",
+    "FromName": "My Name",
+    "FromEmail": "myemail@example.com",
+    "ReplyTo": "myemail@example.com",
     "SentDate": "2010-10-06 16:20:00",
     "TotalRecipients": 11222
   }

data/test/fixtures/client_details.json

@@ -14,6 +14,7 @@
   },
   "BillingDetails": {
      "CanPurchaseCredits": true,
+     "Credits": 500,
      "MarkupOnDesignSpamTest": 0.0,
      "ClientPays": true,
      "BaseRatePerRecipient": 1.0,

data/test/fixtures/drafts.json

@@ -3,14 +3,22 @@
     "CampaignID": "7c7424792065d92627139208c8c01db1",
     "Name": "Draft One",
     "Subject": "Draft One",
+    "FromName": "My Name",
+    "FromEmail": "myemail@example.com",
+    "ReplyTo": "myemail@example.com",
     "DateCreated": "2010-08-19 16:08:00",
-    "PreviewURL": "http://createsend.com/t/r-E97A7BB2E6983DA1"
+    "PreviewURL": "http://createsend.com/t/r-E97A7BB2E6983DA1",
+    "PreviewTextURL": "http://createsend.com/t/r-E97A7BB2E6983DA1/t"
   },
   {
     "CampaignID": "2e928e982065d92627139208c8c01db1",
     "Name": "Draft Two",
     "Subject": "Draft Two",
+    "FromName": "My Name",
+    "FromEmail": "myemail@example.com",
+    "ReplyTo": "myemail@example.com",
     "DateCreated": "2010-08-19 16:08:00",
-    "PreviewURL": "http://createsend.com/t/r-E97A7BB2E6983DA1"
+    "PreviewURL": "http://createsend.com/t/r-E97A7BB2E6983DA1",
+    "PreviewTextURL": "http://createsend.com/t/r-E97A7BB2E6983DA1/t"
   }
 ]

data/test/fixtures/scheduled_campaigns.json

@@ -5,8 +5,12 @@
     "CampaignID": "827dbbd2161ea9989fa11ad562c66937",
     "Name": "Magic Issue One",
     "Subject": "Magic Issue One",
+    "FromName": "My Name",
+    "FromEmail": "myemail@example.com",
+    "ReplyTo": "myemail@example.com",
     "DateCreated": "2011-05-24 10:37:00",
-    "PreviewURL": "http://createsend.com/t/r-DD543521A87C9B8B"
+    "PreviewURL": "http://createsend.com/t/r-DD543521A87C9B8B",
+    "PreviewTextURL": "http://createsend.com/t/r-DD543521A87C9B8B/t"
   },
   {
     "DateScheduled": "2011-05-29 11:20:00",
@@ -14,7 +18,11 @@
     "CampaignID": "4f54bbd2161e65789fa11ad562c66937",
     "Name": "Magic Issue Two",
     "Subject": "Magic Issue Two",
+    "FromName": "My Name",
+    "FromEmail": "myemail@example.com",
+    "ReplyTo": "myemail@example.com",
     "DateCreated": "2011-05-24 10:39:00",
-    "PreviewURL": "http://createsend.com/t/r-DD913521A87C9B8B"
+    "PreviewURL": "http://createsend.com/t/r-DD913521A87C9B8B",
+    "PreviewTextURL": "http://createsend.com/t/r-DD913521A87C9B8B/t"
   }
 ]

data/test/fixtures/transfer_credits.json

@@ -0,0 +1,4 @@
+{
+    "AccountCredits": 800,
+    "ClientCredits": 200
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: createsend
 version: !ruby/object:Gem::Version
-  version: 2.4.0
+  version: 2.5.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-11-05 00:00:00.000000000 Z
+date: 2012-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70098807897300 !ruby/object:Gem::Requirement
+  requirement: &70131066006280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70098807897300
+  version_requirements: *70131066006280
 - !ruby/object:Gem::Dependency
   name: fakeweb
-  requirement: &70098807896180 !ruby/object:Gem::Requirement
+  requirement: &70131066005780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '1.3'
   type: :development
   prerelease: false
-  version_requirements: *70098807896180
+  version_requirements: *70131066005780
 - !ruby/object:Gem::Dependency
   name: jnunemaker-matchy
-  requirement: &70098807915080 !ruby/object:Gem::Requirement
+  requirement: &70131066005280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: '0.4'
   type: :development
   prerelease: false
-  version_requirements: *70098807915080
+  version_requirements: *70131066005280
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &70098807914240 !ruby/object:Gem::Requirement
+  requirement: &70131066004820 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '0.9'
   type: :development
   prerelease: false
-  version_requirements: *70098807914240
+  version_requirements: *70131066004820
 - !ruby/object:Gem::Dependency
   name: shoulda
-  requirement: &70098807913600 !ruby/object:Gem::Requirement
+  requirement: &70131065602620 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -65,10 +65,10 @@ dependencies:
         version: 3.3.0
   type: :development
   prerelease: false
-  version_requirements: *70098807913600
+  version_requirements: *70131065602620
 - !ruby/object:Gem::Dependency
   name: cane
-  requirement: &70098807912660 !ruby/object:Gem::Requirement
+  requirement: &70131065601720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70098807912660
+  version_requirements: *70131065601720
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70098807911800 !ruby/object:Gem::Requirement
+  requirement: &70131065600740 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,10 +87,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70098807911800
+  version_requirements: *70131065600740
 - !ruby/object:Gem::Dependency
   name: hashie
-  requirement: &70098807911160 !ruby/object:Gem::Requirement
+  requirement: &70131065599540 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -98,10 +98,10 @@ dependencies:
         version: '1.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70098807911160
+  version_requirements: *70131065599540
 - !ruby/object:Gem::Dependency
   name: httparty
-  requirement: &70098807910060 !ruby/object:Gem::Requirement
+  requirement: &70131065598900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -109,7 +109,7 @@ dependencies:
         version: '0.8'
   type: :runtime
   prerelease: false
-  version_requirements: *70098807910060
+  version_requirements: *70131065598900
 description: Implements the complete functionality of the Campaign Monitor API.
 email:
 - jdennes@gmail.com
@@ -149,6 +149,7 @@ files:
 - test/fixtures/admin_set_primary_contact.json
 - test/fixtures/administrators.json
 - test/fixtures/apikey.json
+- test/fixtures/billingdetails.json
 - test/fixtures/bounced_subscribers.json
 - test/fixtures/campaign_bounces.json
 - test/fixtures/campaign_clicks.json
@@ -196,6 +197,7 @@ files:
 - test/fixtures/template_details.json
 - test/fixtures/templates.json
 - test/fixtures/timezones.json
+- test/fixtures/transfer_credits.json
 - test/fixtures/unconfirmed_subscribers.json
 - test/fixtures/unsubscribed_subscribers.json
 - test/fixtures/update_custom_field.json
@@ -244,6 +246,7 @@ test_files:
 - test/fixtures/admin_set_primary_contact.json
 - test/fixtures/administrators.json
 - test/fixtures/apikey.json
+- test/fixtures/billingdetails.json
 - test/fixtures/bounced_subscribers.json
 - test/fixtures/campaign_bounces.json
 - test/fixtures/campaign_clicks.json
@@ -291,6 +294,7 @@ test_files:
 - test/fixtures/template_details.json
 - test/fixtures/templates.json
 - test/fixtures/timezones.json
+- test/fixtures/transfer_credits.json
 - test/fixtures/unconfirmed_subscribers.json
 - test/fixtures/unsubscribed_subscribers.json
 - test/fixtures/update_custom_field.json