campaigning 0.15.0

data/lib/campaigning/subscriber.rb

@@ -0,0 +1,158 @@
+# Subscriber is defined in default.rb which is automatically generated.
+# In this file we add additional methods to the Subscriber class.
+require File.expand_path(File.dirname(__FILE__)) + '/module_mixin'
+
+module Campaigning
+  class Subscriber
+    include ModuleMixin   
+    attr_accessor :emailAddress
+    attr_accessor :name
+    attr_accessor :date
+    attr_accessor :state
+    attr_accessor :customFields
+
+    def initialize(emailAddress = nil, name = nil, date = nil, state = nil, customFields = nil, opts={})
+      @apiKey = opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY
+      @emailAddress = emailAddress
+      @name = name
+      @date = date
+      @state = state
+      @customFields = customFields
+    end
+
+
+    #Adds a subscriber to a subscriber list, including adding custom field data for the subscriber. If the subscriber
+    #(email address) already exists, the name value is updated with whatever is passed in.
+    #
+    #If the list has been set as double opt-in, they will be sent the verification email, otherwise they will be sent the
+    #confirmation email you have set up for the list being subscribed to.
+    #
+    #<b>Please note</b>: If the subscriber is in an inactive state or has previously been unsubscribed, they will *not* be re-added
+    #to the active list. Therefore, this method should be used with caution and only where suitable.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def add!(list_id, custom_fields={})
+      params = {
+        :apiKey => @apiKey,
+        :listID => list_id,
+        :email => @emailAddress,
+        :name => @name
+      }
+      if custom_fields.empty?
+        response = @@soap.addSubscriber(params)
+        handle_response response.subscriber_AddResult
+      else
+        params.merge!({:customFields => custom_fields_array(custom_fields)})
+        response = @@soap.addSubscriberWithCustomFields(params)
+        handle_response response.subscriber_AddWithCustomFieldsResult
+      end  
+    end
+
+
+    #Adds a subscriber to a subscriber list, including adding custom field data for the subscriber. If the subscriber (email address) already exists,
+    #the name value is updated with whatever is passed in.
+    #
+    #If the list has been set as double opt-in, they will be sent the verification email, otherwise they will be sent the
+    #confirmation email you have set up for the list being subscribed to.
+    #
+    #<b>Please note</b>: If the subscriber is in an inactive state or has previously been unsubscribed, they will be re-added to
+    #the active list. Therefore, this method should be used with caution and only where suitable.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def add_and_resubscribe!(list_id, custom_fields={})
+      params = {
+        :apiKey => @apiKey,
+        :listID => list_id,
+        :email => @emailAddress,
+        :name => @name
+      }
+      if custom_fields.empty?
+        response = @@soap.addAndResubscribe(params)
+        handle_response response.subscriber_AddAndResubscribeResult
+      else
+        params.merge!({:customFields => custom_fields_array(custom_fields)})
+        response = @@soap.addAndResubscribeWithCustomFields(params)
+        handle_response response.subscriber_AddAndResubscribeWithCustomFieldsResult
+      end  
+    end
+
+
+    #Changes the status of an Active Subscriber to an Unsubscribed Subscriber who will no longer receive
+    #campaigns sent to that Subscriber List.
+    #
+    #If the list is set to add unsubscribing subscribers to the suppression list, then the subscriber’s email address will
+    #also be added to the suppression list.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def unsubscribe!(list_id)
+      Subscriber.unsubscribe!(@emailAddress, list_id, :apiKey=> @apiKey)
+    end
+
+
+    #Changes the status of an Active Subscriber to an Unsubscribed Subscriber who will no longer receive
+    #campaigns sent to that Subscriber List (Same that the instance method with the same name).
+    #
+    #Aviable _opts_ arguments are:
+    #   * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
+    def self.unsubscribe!(email, list_id, opts={})
+      response = @@soap.unsubscribe(
+      :apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
+      :listID => list_id,
+      :email => email
+      )
+      handle_response response.subscriber_UnsubscribeResult
+    end
+
+    #Returns True or False as to the existence of the given email address in the list supplied.
+    def is_subscribed?(list_id)
+      Subscriber.is_subscribed?(@emailAddress, list_id, :apiKey=> @apiKey)
+    end
+
+    #Returns True or False as to the existence of the given email address in the list supplied.
+    #
+    #Aviable _opts_ arguments are:
+    #   * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
+    def self.is_subscribed?(email, list_id, opts={})
+      response = @@soap.getIsSubscribed(
+      :apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
+      :listID => list_id,
+      :email => email
+      )
+      response = handle_response response.subscribers_GetIsSubscribedResult
+      response == 'True' ? true : false
+    end
+
+
+    protected
+
+    def custom_fields_array(custom_fields) #:nodoc:
+      arr = []
+      custom_fields.each do |key, value|
+        if value.is_a? Array
+          value.each do |v|
+            arr << {:key => key, :value => v}
+          end
+        else
+          arr << { :key => key, :value => value }
+        end
+      end
+      arr
+    end
+
+  end
+end

data/lib/campaigning/template.rb

@@ -0,0 +1,124 @@
+# Template is defined in soap/default.rb which is automatically generated.
+# In this file we add additional methods to the Template class.
+require File.expand_path(File.dirname(__FILE__)) + '/module_mixin'
+
+
+module Campaigning
+  class Template
+    include ModuleMixin
+    attr_accessor :templateID
+    attr_accessor :name
+    attr_accessor :previewURL
+    attr_accessor :screenshotURL
+    
+    def initialize(templateID = nil, name = nil, previewURL = nil, screenshotURL = nil, opts = {})
+      @apiKey = opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY
+      @templateID = templateID
+      @name = name
+      @previewURL = previewURL
+      @screenshotURL = screenshotURL
+    end
+    
+    #Creates a new template for a client.
+    #
+    #Available _params_ argument are:
+    #   * :clientID - The ID of the client who will owner of the list.
+    #   * :templateName - The name of the template. Maximum of 30 characters (will be truncated to 30 characters if longer).
+    #   * :htmlPageURL - The URL of the HTML page you have created for the template.
+    #   * :zipFileURL - Optional URL of a zip file containing any other files required by the template.
+    #   * :screenshotURL - Optional URL of a screenshot of the template. Must be in jpeg format and at least 218 pixels wide.
+    #   * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Template object representing the newly created
+    #template. The object returned isn't filled with previewURL and screenShotURL once the CampaignMonitor API generate a new
+    #value for that and doesn't return it on te create! method. In order to get a complete filled object call the Template.details
+    #method.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def self.create!(params)
+      response = @@soap.createTemplate(
+        :apiKey => params[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
+        :clientID => params[:clientID],
+        :templateName => params[:templateName],
+        :hTMLPageURL => params[:htmlPageURL],
+        :zipFileURL => params[:zipFileURL],
+        :screenshotURL => params[:screenshotURL]    
+      )
+      Template.new( handle_response(response.template_CreateResult), params[:templateName], nil, nil, :apiKey=> params[:apiKey] )
+    end
+    
+    #Gets the details of a template.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Template object, which consists of the template ID,
+    #the template name, a preview URL and a screenshot URL.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def details
+      response = @@soap.getTemplateDetail(:apiKey => @apiKey, :templateID => @templateID)
+      handle_response response.template_GetDetailResult
+    end
+
+    #Updates an existing template.
+    #
+    #Available _params_ argument are:
+    #   * :templateID - The ID of the template to be updated.  
+    #   * :templateName - The name of the template. Maximum of 30 characters (will be truncated to 30 characters if longer).
+    #   * :htmlPageURL - The URL of the HTML page you have created for the template.
+    #   * :zipFileURL - Optional URL of a zip file containing any other files required by the template.
+    #   * :screenshotURL - Optional URL of a screenshot of the template. Must be in jpeg format and at least 218 pixels wide.
+    #   * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def update!(params)
+      response = @@soap.updateTemplate(
+        :apiKey => params[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
+        :templateID => @templateID,
+        :templateName =>  params[:templateName],
+        :hTMLPageURL => params[:htmlPageURL],
+        :zipFileURL => params[:zipFileURL],
+        :screenshotURL => params[:screenshotURL]
+      )
+      handle_response response.template_UpdateResult
+    end
+    
+    
+    #Deletes a template.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def delete!
+      response = Template.delete!(@templateID, :apiKey=> @apiKey)
+      self.templateID, self.name  = nil, nil
+      response
+    end
+    
+
+    #Deletes a template.
+    #
+    #Aviable _opts_ arguments are:
+    #   * :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.
+    #
+    #*Return*:
+    #
+    #*Success*: Upon a successful call, this method will return a Campaigning::Result object wich consists of a +code+ and +message+ fields
+    #containing a successful message.
+    #
+    #*Error*: An Exception containing the cause of the error will be raised.
+    def self.delete!(template_id, opts={})
+      response = @@soap.deleteTemplate(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :templateID => template_id)
+      handle_response response.template_DeleteResult
+    end
+    
+  end
+end

data/sample/campaign_sample.rb

@@ -0,0 +1,116 @@
+require 'rubygems'
+require 'campaigning'
+
+CAMPAIGN_MONITOR_API_KEY  = '__PUT__YOUR__API__KEY__HERE__'
+
+
+# SETUP FOR THIS SAMPLE ---------------------------------------------------------------------
+#Creating a Client for this sample execution
+client = Campaigning::Client.create!(
+  :companyName => "Client to Sample",
+  :contactName => "Marcus Cesar",
+  :emailAddress => "og3@example.com",
+  :country => "Ireland",
+  :timezone => "(GMT) Casablanca" #alternatively you can use "Campaigning.timezones" to get valid time zones list
+)
+puts "New Client created is: #{client.inspect}"
+list = Campaigning::List.create!(
+  :clientID => client.clientID,
+  :title => "List from Sample Exec",
+  :unsubscribePage => "http://www.mycompany.com/campaign/ubsubscribe.html", #If not suplied or equals blank (""), default value will be used
+  :confirmOptIn => false,
+  :confirmationSuccessPage => "" #Default value will be used
+)
+# /SETUP FOR THIS SAMPLE ---------------------------------------------------------------------
+
+
+# Here is how to create a campaign and send that campaign
+client = Campaigning::Client.find_by_name("Client to Sample")
+campaign = Campaigning::Campaign.create!(
+  :clientID => client.clientID,
+  :campaignName => "Campaign created for Campaign Sample",
+  :campaignSubject => "Campaign by myself - OK",
+  :fromName => "Mr. Gordon2",
+  :fromEmail => "gordon2@example.com",
+  :replyTo => "no-reply@example.com",
+  :htmlUrl => "http://www.mycompany.com/campaign_html",
+  :textUrl => "http://www.mycompany.com/campaign_text",
+  :subscriberListIDs => [list.listID],
+  :listSegments => client.segments
+)
+puts "New Campaign created is: #{campaign.inspect}"
+#After create a campaign you can send as follow:
+campaign.send!(
+  :confirmationEmail => "userhdhd@example.com",
+  :sendDate => DateTime.now #To send a campaign immediately pass in “Immediately”.
+                             #This date should be in the users timezone and formatted as YYYY-MM-DD HH:MM:SS.
+)
+
+
+#Here is how to find a Campaign by subject.
+#Return: It will return an Array of Campaign Objects
+client = Campaigning::Client.find_by_name("Client to Sample")
+campaigns = client.find_campaigns_by_subject("Campaign by myself - OK")    
+puts "Campaigns found are: #{campaigns.inspect}"
+
+
+# Here is how to get all the bounces from a client Campaign
+client = Campaigning::Client.find_by_name("Client to Sample")
+client.campaigns.each do |campaign|
+  puts campaign.subject
+  puts campaign.bounces.inspect
+end
+# OR you could filter your campaigns by subject (Unortunately there is no way to get a campaign by his name, wich would be better):
+client = Campaigning::Client.find_by_name("Client to Sample")
+campaigns = client.find_campaigns_by_subject("Campaign by myself - OK")
+puts "Bounces from a given campaign:"
+campaigns.each do |campaign|
+  puts campaign.subject
+  puts campaign.bounces.inspect
+end
+
+
+#Here is how to get the Lists bellonging to a client Campaign
+client = Campaigning::Client.find_by_name("Client to Sample")
+campaigns = client.find_campaigns_by_subject("Campaign by myself - OK")
+puts "Lists belonging to a given campaign: "
+campaigns.each do |campaign|
+  puts campaign.subject
+  puts campaign.lists.inspect
+end
+
+
+#Here is how to get a list of all subscribers who opened a given campaign, and the number of times they opened the campaign
+client = Campaigning::Client.find_by_name("Client One Company")
+campaigns = client.find_campaigns_by_subject("Campaign by myself - OK") 
+subs_open = client.campaigns[0].opens
+puts "Who opened a given campaign: #{subs_open.inspect}"
+
+
+
+#Gets a list of all subscribers who clicked a link for a given campaign, the ID of the list they belong to,
+#the links they clicked, and the number of times they clicked the link.
+client = Campaigning::Client.find_by_name("Client to Sample")
+subscriber_clicks = client.campaigns[0].subscriber_clicks
+puts "Subscriber Clicks for a given campaign: #{subscriber_clicks.inspect}"
+
+
+#Gets a statistical summary, including number of recipients and open count, for a given campaign.
+client = Campaigning::Client.find_by_name("Client to Sample")
+campaign = client.campaigns[1].summary
+puts "Summary for a given campaign: #{campaign.inspect}"
+
+
+#Gets a list of all subscribers who unsubscribed for a given campaign.  
+client = Campaigning::Client.find_by_name("Client to Sample")
+campaign = client.campaigns[0].unsubscribes
+puts "all subscribers who unsubscribed for a given campaign: #{campaign.inspect}"
+
+
+
+
+# TEARDOWN FOR THIS SAMPLE --------------------------------------------------------------------
+# Deleting a client created for this sample
+client = Campaigning::Client.find_by_name("Client to Sample")
+result = Campaigning::Client.delete!(client.clientID)  
+puts "Client deleted successfuly? #{result.message}"

data/sample/campaigning_sample.rb

@@ -0,0 +1,25 @@
+require 'rubygems'
+require 'campaigning'
+
+CAMPAIGN_MONITOR_API_KEY  = '__PUT__YOUR__API__KEY__HERE__'
+
+
+#How to get a system Date from the API server
+date_time = Campaigning.system_date
+
+puts "API get the system date from the API server: #{date_time.inspect}"
+
+
+#Here is how to set the debug mode for the SOAP requests
+timezones = Campaigning.set_debug_mode! true
+puts "API set debug mode to true"
+
+
+#Here is how to get all the timezones
+timezones = Campaigning.timezones
+puts "All the timezones supported: #{timezones.inspect}"
+
+
+#Here is how to get all countries supported by the API
+countries = Campaigning.countries
+puts "All supported countries: #{countries.inspect}"

data/sample/client_sample.rb

@@ -0,0 +1,139 @@
+require 'rubygems'
+require 'campaigning'
+
+CAMPAIGN_MONITOR_API_KEY  = '__PUT__YOUR__API__KEY__HERE__'
+
+
+# Here is how to get a list of all clients...
+clients = Campaigning::Client.get_all_clients
+puts "All my clients: #{clients.inspect}"
+
+
+# Here is how to create a new client
+client = Campaigning::Client.create!(
+  :companyName => "Company to Sample Client",
+  :contactName => "Oswald Green Sample",
+  :emailAddress => "og233@example.com",
+  :country => "Ireland",
+  :timezone => "(GMT) Greenwich Mean Time : Dublin, Edinburgh, Lisbon, London" #alternatively you can use "Campaigning.timezones" to get valid time zones list
+)
+puts "New Client created is: #{client.inspect}"
+
+client_two = Campaigning::Client.create!(
+  :companyName => "Company Gordon",
+  :contactName => "Mr. Gordon",
+  :emailAddress => "gordon3@example.com",
+  :country => "Ireland",
+  :timezone => "(GMT) Greenwich Mean Time : Dublin, Edinburgh, Lisbon, London" #alternatively you can use "Campaigning.timezones" to get valid time zones list
+)
+puts "Other new Client created is: #{client_two.inspect}"
+
+
+
+# SETUP FOR THIS SAMPLE ---------------------------------------------------------------------
+#Creating a list for this sample execution
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+list = Campaigning::List.create!(
+  :clientID => client.clientID,
+  :title => "List people from Chicago",
+  :confirmOptIn => false
+)
+# /SETUP FOR THIS SAMPLE ---------------------------------------------------------------------
+
+
+#How to find a client by his name
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+puts "Client retrieved by his name: #{client.inspect}"
+
+
+#How to get all Lists belonging to a client
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+lists = client.lists
+puts "Lists belonging to the client: #{lists.inspect}"
+
+
+#How to get a List by it's name and belonging to a client
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+list = client.find_list_by_name("List people from Chicago")
+puts "Lists belonging by his name: #{lists.inspect}"
+
+
+#How to get a list of all campaigns that have been sent for a client.
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+campaigns = client.campaigns
+puts "Campaigns that have been sent for a client: #{campaigns.inspect}"
+
+
+#How to get a list of all subscriber segments for a client.
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+puts "All subscriber segments for a client: #{client.segments.inspect}"
+
+
+#How to get all subscribers in the client-wide suppression list.
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+puts "Client suppression list: #{client.suppression_list}"
+
+
+#How to update the access and billing settings of an existing client, leaving the basic details untouched.
+#Consult the API website for more information: http://www.campaignmonitor.com/api/method/client-updateaccessandbilling/
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+response = client.update_access_and_billing!(
+   :accessLevel => 5 ,
+   :username => "client_comp_s",
+   :password => "1234560",
+   :billingType => "UserPaysOnClientsBehalf",
+   :currency => "USD",
+   :deliveryFee => 6.5,
+   :costPerRecipient => 1.5 ,
+   :designAndSpamTestFee => 5
+  )
+puts "Was the Client successfuly updated?: #{response.message}"
+
+
+#How to get the complete account and billing details for a particular client.
+client = Campaigning::Client.find_by_name("Company to Sample Client")
+#puts "Client details: #{client.details.inspect}"
+puts "Client details: "
+client_details = client.details
+basic_details = client_details.basicDetails
+access_and_billing_details = client_details.accessAndBilling
+puts "Basic details:"
+puts "Client ID: #{basic_details.clientID}\n
+      Company: #{basic_details.companyName}\n
+      Contact: #{basic_details.contactName}\n
+      Country: #{basic_details.country}\n
+      Timezone: #{basic_details.timezone}"
+
+puts "Access and Billing Details:"
+puts "Username: #{access_and_billing_details.username}\n 
+      Password: #{access_and_billing_details.password}\n
+      Billing Type: #{access_and_billing_details.billingType}\n
+      Currency: #{access_and_billing_details.currency}\n
+      Delivery Fee: #{access_and_billing_details.deliveryFee}\n
+      Cost per Recipient: #{access_and_billing_details.costPerRecipient}\n
+      Design and Span test Fee: #{access_and_billing_details.designAndSpamTestFee}\n
+      Access Level: #{access_and_billing_details.accessLevel}"
+
+
+
+#How to update the basic details of an existing client.
+#Please note that the client’s existing access and billing details will remain unchanged by a call to Client.update_basics!.
+client_two = Campaigning::Client.find_by_name("Company Gordon")
+response = client.update_basics!(
+  :companyName => "My new Company",
+  :contactName => "Mr. Gordon Newman",
+  :emailAddress => "gordon-newman43@example.com",
+  :country => "Ireland",
+  :timezone => "(GMT) Greenwich Mean Time : Dublin, Edinburgh, Lisbon, London"
+)
+puts "Was the other Client successfuly updated?: #{response.message}"
+
+
+# Here is how to delete a client
+result = Campaigning::Client.delete!(client.clientID)  
+puts "Client deleted successfuly? #{result.message}"
+#Or you can use a instance method like:
+client = Campaigning::Client.find_by_name("My new Company")
+result = client.delete!
+puts "Client two deleted successfuly? #{result.message}"
+