Merge pull request #68 from campaignmonitor/EL-279

EL-279 Add v3.3 support

Author: cmtiml

HISTORY.md

@@ -1,5 +1,22 @@
 # createsend-ruby history
 
+## v6.0.0 - 15 Dec, 2021
+* Upgrades to Createsend API v3.3 which includes new breaking changes
+* Breaking: 'client.campaigns' now returned an object to support pagination (use .Results to ge the array of campaigns)
+* Added 'Tags' as another field that is returned in 'client.scheduled', 'client.drafts' and 'client.campaigns'
+* Added 'Name' as another field that is returned in 'campaign.summary'
+* Add new support for 'client.tags' endpoint (ie: getting list of tags for the client)
+* Add support for pagination, filtering and sorting to 'client.campaigns' endpoint
+* Bump `rake` to `~> 12.3.3`
+* Adding support for returning ListJoinedDate for each subscriber. 
+  * List.Active()
+  * List.Bounced()
+  * List.Unsubscribed()
+  * List.Unconfirmed()
+  * List.Deleted()
+  * Segment.Subscribers()
+  * Subscriber.Get()
+
 ## v5.1.1 - 8 Oct, 2021
 * increased default timeout for HTTP requests to 120secs
 

README.md

@@ -133,7 +133,7 @@ clients.each do |cl|
   p "Client: #{cl.Name}"
   client = CreateSend::Client.new auth, cl.ClientID
   p "- Campaigns:"
-  client.campaigns.each do |cm|
+  client.drafts.each do |cm|
     p "  - #{cm.Subject}"
   end
 end

createsend.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'json', '>= 1.0'
   s.add_runtime_dependency 'hashie', '~> 3.0'
   s.add_runtime_dependency 'httparty', '~> 0.14'
-  s.add_development_dependency 'rake', '~> 10.0'
+  s.add_development_dependency 'rake', '~> 12.3.3'
   s.add_development_dependency 'fakeweb', '~> 1.3'
   s.add_development_dependency 'jnunemaker-matchy', '~> 0.4'
   s.add_development_dependency 'shoulda-context', '~> 1.2'

lib/createsend/client.rb

@@ -25,9 +25,19 @@ def details
     end
 
     # Gets the sent campaigns belonging to this client.
-    def campaigns
-      response = get 'campaigns'
-      response.map{|item| Hashie::Mash.new(item)}
+    def campaigns(page=1, page_size=1000, order_direction="desc",
+      sent_from_date='', sent_to_date='', tags='')
+      options = { :query => {
+        :page => page,
+        :pagesize => page_size,
+        :orderdirection => order_direction,
+        :sentfromdate => sent_from_date,
+        :senttodate => sent_to_date,
+        :tags => tags
+      }}
+
+      response = get 'campaigns', options
+      Hashie::Mash.new(response)
     end
 
     # Gets the currently scheduled campaigns belonging to this client.
@@ -42,6 +52,12 @@ def drafts
       response.map{|item| Hashie::Mash.new(item)}
     end
 
+    # Gets all the tags belonging to this client.
+    def tags
+      response = get 'tags'
+      response.map{|item| Hashie::Mash.new(item)}
+    end
+
     # Gets the subscriber lists belonging to this client.
     def lists
       response = get 'lists'

lib/createsend/createsend.rb

@@ -111,7 +111,7 @@ def initialize(*args)
       end
     end
 
-    @@base_uri = "https://api.createsend.com/api/v3.2"
+    @@base_uri = "https://api.createsend.com/api/v3.3"
     @@oauth_base_uri = "https://api.createsend.com/oauth"
     @@oauth_token_uri = "#{@@oauth_base_uri}/token"
     headers({

lib/createsend/version.rb

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

samples/authentication_sample.rb

@@ -0,0 +1,64 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'createsend'
+
+class AuthorizationSample
+    def initialize
+        raise 'CREATESEND_API_KEY env var missing' if ENV['CREATESEND_API_KEY'].nil?
+        raise 'CREATESEND_CLIENT_ID env var missing' if ENV['CREATESEND_CLIENT_ID'].nil?
+        raise 'CREATESEND_OAUTH_CLIENT_ID env var missing' if ENV['CREATESEND_OAUTH_CLIENT_ID'].nil?
+        raise 'CREATESEND_OAUTH_CLIENT_SECRET env var missing' if ENV['CREATESEND_OAUTH_CLIENT_SECRET'].nil?
+        raise 'CREATESEND_OAUTH_REDIRECT_URL env var missing' if ENV['CREATESEND_OAUTH_REDIRECT_URL'].nil?
+        raise 'CREATESEND_OAUTH_SCOPE env var missing' if ENV['CREATESEND_OAUTH_SCOPE'].nil?
+       
+        @createsendApiKey = ENV['CREATESEND_API_KEY']
+        @oauthClientId = ENV['CREATESEND_OAUTH_CLIENT_ID']
+        @oauthClientSecret = ENV['CREATESEND_OAUTH_CLIENT_SECRET']
+        @oauthRedirectUrl = ENV['CREATESEND_OAUTH_REDIRECT_URL']
+        @oauthScope = ENV['CREATESEND_OAUTH_SCOPE']
+        )
+    end
+
+    def authentication_with_api_key
+        auth = {:api_key => @createsendApiKey}
+        @client = CreateSend::Client.new auth, @createsendClientId
+
+        @client.scheduled
+    end
+
+    def get_authorise_url
+        state = 'some state data'
+
+        @authorize_url = CreateSend::CreateSend.authorize_url(@oauthClientId, @oauthRedirectUrl, @oauthScope, state);
+    end
+
+    def exchange_token(code)
+        CreateSend::CreateSend.exchange_token(
+            client_id=@oauthClientId,
+            client_secret=@oauthClientSecret,
+            redirect_uri=@oauthRedirectUrl,
+            code=code # Get the code from the query string after hitting authorise url
+            )
+    end
+
+    def authentication_with_oauth(access_token, refresh_token)
+        auth = {:access_token => access_token, :refresh_token => refresh_token}
+        @client = CreateSend::Client.new auth, @createsendClientId
+
+        @client.scheduled
+    end
+end
+
+sample = AuthorizationSample.new
+authoriseUrl = sample.get_authorise_url
+# hit the authorise url, where you would be redirected and receive the code parameter in the query string
+access_token, expires_in, refresh_token = sample.exchange_token('code that you get once you hit authorize url')
+
+puts "Getting scheduled campaigns with api authentication: #{sample.authentication_with_api_key.to_json}\n\n"
+puts "Getting authorise url: #{authoriseUrl.to_json}\n\n"
+puts "Getting access_token: #{access_token.to_json}\n\n"
+puts "Getting scheduled campaigns with oauth authentication: #{sample.authentication_with_oauth(access_token, refresh_token).to_json}\n\n"
+
+
+        @client.scheduled
+    end
+end

samples/clients_sample.rb

@@ -0,0 +1,79 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'createsend'
+
+class ClientsSample
+    def initialize
+        raise 'CREATESEND_ACCESS_TOKEN env var missing' if ENV['CREATESEND_ACCESS_TOKEN'].nil?
+        raise 'CREATESEND_REFRESH_TOKEN env var missing' if ENV['CREATESEND_REFRESH_TOKEN'].nil?
+        raise 'CREATESEND_CLIENT_ID env var missing' if ENV['CREATESEND_CLIENT_ID'].nil?
+
+        auth = auth = {:access_token => ENV['CREATESEND_ACCESS_TOKEN'], :refresh_token => ENV['CREATESEND_REFRESH_TOKEN']}
+        @client = CreateSend::Client.new auth, ENV['CREATESEND_CLIENT_ID']
+    end
+
+    def get_all_sent_campaigns
+        campaigns = []
+        page_number = 1
+        loop do
+            page = @client.campaigns(page_number)
+            page_number += 1
+            campaigns.concat(page.Results)
+            if page.PageNumber == page.NumberOfPages
+                break
+            end
+        end
+
+        campaigns
+    end
+    
+    def get_sent_campaigns_with_tag_filter
+        filtered_campaigns = []
+        page_number = 1
+        loop do
+            page = @client.campaigns(page_number, 1000, 'desc', '', '', 'tag_example, tag_example_2')
+            page_number += 1
+            filtered_campaigns.concat(page.Results)
+            if page.PageNumber == page.NumberOfPages
+                break
+            end
+        end
+
+        filtered_campaigns
+    end
+
+    def get_2021_sent_campaigns
+        2021_campaigns = []
+        page_number = 1
+        loop do
+            page = @client.campaigns(1, 1000, 'desc', '2021-01-01', '2022-01-01', '')
+            page_number += 1
+            2021_campaigns.concat(page.Results)
+            if page.PageNumber == page.NumberOfPages
+                break
+            end
+        end
+
+        2021_campaigns
+    end
+
+    def get_all_scheduled_campaigns
+        @client.scheduled
+    end
+
+    def get_all_draft_campaigns
+        @client.drafts
+    end
+
+    def get_all_client_tags
+        @client.tags
+    end
+end
+
+sample = ClientsSample.new
+
+puts "All sent campaigns: #{sample.get_all_sent_campaigns.to_json}\n\n"
+puts "All sent campaigns with `tag_example` and `tag_example_2` tag: #{sample.get_sent_campaigns_with_tag_filter.to_json}\n\n"
+puts "All 2021 sent campaigns: #{sample.get_2021_sent_campaigns.to_json}\n\n"
+puts "All scheduled campaigns: #{sample.get_all_scheduled_campaigns.to_json}\n\n"
+puts "All draft campaigns: #{sample.get_all_draft_campaigns.to_json}\n\n"
+puts "All client tags: #{sample.get_all_client_tags.to_json}\n\n"

samples/journey_sample.rb

@@ -5,12 +5,13 @@ class JourneySample
   @date = "2019-01-01 00:00"
 
   def initialize
-    raise 'CREATESEND_API_KEY env var missing' if ENV['CREATESEND_API_KEY'].nil?
+    raise 'CREATESEND_ACCESS_TOKEN env var missing' if ENV['CREATESEND_ACCESS_TOKEN'].nil?
+    raise 'CREATESEND_REFRESH_TOKEN env var missing' if ENV['CREATESEND_REFRESH_TOKEN'].nil?
     raise 'CREATESEND_CLIENT_ID env var missing' if ENV['CREATESEND_CLIENT_ID'].nil?
     raise 'CREATESEND_JOURNEY_ID env var missing' if ENV['CREATESEND_JOURNEY_ID'].nil?
     raise 'CREATESEND_EMAIL_ID env var missing' if ENV['CREATESEND_EMAIL_ID'].nil?
 
-    auth = {:api_key => ENV['CREATESEND_API_KEY']}
+    auth = {:access_token => ENV['CREATESEND_ACCESS_TOKEN'], :refresh_token => ENV['CREATESEND_REFRESH_TOKEN']}
     @client = CreateSend::Client.new auth, ENV['CREATESEND_CLIENT_ID']
     @journey = CreateSend::Journey.new auth, ENV['CREATESEND_JOURNEY_ID']
   end

samples/lists_sample.rb

@@ -0,0 +1,41 @@
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'createsend'
+
+class ListsSample
+    def initialize
+        raise 'CREATESEND_ACCESS_TOKEN env var missing' if ENV['CREATESEND_ACCESS_TOKEN'].nil?
+        raise 'CREATESEND_REFRESH_TOKEN env var missing' if ENV['CREATESEND_REFRESH_TOKEN'].nil?
+        raise 'CREATESEND_LIST_ID env var missing' if ENV['CREATESEND_LIST_ID'].nil?
+
+        auth = {:access_token => ENV['CREATESEND_ACCESS_TOKEN'], :refresh_token => ENV['CREATESEND_REFRESH_TOKEN']}
+        @list = CreateSend::List.new auth, ENV['CREATESEND_LIST_ID']
+    end
+
+    def get_active_subscribers
+        @list.active
+    end
+
+    def get_bounced_subscribers
+        @list.bounced
+    end
+
+    def get_unsubscribed_subscribers
+        @list.unsubscribed
+    end
+
+    def get_unconfirmed_subscribers
+        @list.unconfirmed
+    end
+
+    def get_deleted_subscribers
+        @list.deleted
+    end
+end
+
+sample = ListsSample.new
+
+puts "All active subscribers: #{sample.get_active_subscribers.to_json}\n\n"
+puts "All bounced subscribers: #{sample.get_bounced_subscribers.to_json}\n\n"
+puts "All unsubscribed subscribers: #{sample.get_unsubscribed_subscribers.to_json}\n\n"
+puts "All unconfirmed subscribers: #{sample.get_unconfirmed_subscribers.to_json}\n\n"
+puts "All deleted subscribers: #{sample.get_deleted_subscribers.to_json}\n\n"