Class: Campaigning::Client

Inherits:
Object
  • Object
show all
Includes:
ModuleMixin
Defined in:
lib/campaigning/soap/generated/default.rb,
lib/campaigning/client.rb

Overview

/Client

clientID - SOAP::SOAPString
name - SOAP::SOAPString

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ModuleMixin

#handle_response, included

Constructor Details

#initialize(clientID = nil, name = nil) ⇒ Client

Returns a new instance of Client.



11
12
13
14
15
 
# File 'lib/campaigning/client.rb', line 11

def initialize(clientID = nil, name = nil, opts={})
  @apiKey     = opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY
  @clientID   = clientID
  @name       = name
end

Instance Attribute Details

#clientID ⇒ Object

Returns the value of attribute clientID.



8
9
10
 
# File 'lib/campaigning/client.rb', line 8

def clientID
  @clientID
end

#name ⇒ Object

Returns the value of attribute name.



9
10
11
 
# File 'lib/campaigning/client.rb', line 9

def name
  @name
end

Class Method Details

.create!(params) ⇒ Object

This method creates a brand new client with no access to the application. By default a new client has no direct access to the application. Access and billing settings (if needed) must be set by means of a subsequent call to Campaigning::Client#update_access_and_billing!.

Available params argument are:

* :companyName - The client company name.
* :contactName - The personal name of the principle contact for this client.
* :emailAddress - An email address to which this client will be sent application-related emails.
* :country - This client's country. A valid country list is available in http://www.campaignmonitor.com/api/countries/ or by
             using the API procedure Campaigning.countries
* :timezone - Client timezone for tracking and reporting data. A valid timezone list is available here or by using the API
               procedure Campaigning.timezones.
* :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::Client object representing the newly created client.

Error: An Exception containing the cause of the error will be raised.



114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/campaigning/client.rb', line 114

def self.create!(params)
  response = @@soap.createClient(
  :apiKey => params[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
  :companyName => params[:companyName],
  :contactName => params[:contactName],
  :emailAddress => params[:emailAddress],
  :country => params[:country],
  :timezone => params[:timezone]
  )
  Client.new( handle_response(response.client_CreateResult), params[:companyName], :apiKey=> params[:apiKey] )
end

.delete!(client_id, opts = {}) ⇒ Object

Deletes a client from your account.

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.



151
152
153
154
 
# File 'lib/campaigning/client.rb', line 151

def self.delete!(client_id, opts={})
  response = @@soap.deleteClient(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :clientID => client_id)
  handle_response response.client_DeleteResult
end

.find_by_name(name, opts = {}) ⇒ Object

This method find a Client by a given name

Aviable opts arguments are:

* :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.

Return:

Client FOUND: If it found any client with the given name it will return a Campaigning::Client object containing the found client.

Client NOT FOUND: If it doesn’t found a client with the given name it will return nil .

Error: An Exception containing the cause of the error will be raised. – TODO: Refactor this method and increase performance? – TODO: Tha campaign monitor permit two users with the same name, what to do?



73
74
75
76
77
 
# File 'lib/campaigning/client.rb', line 73

def self.find_by_name(name, opts={})
  client_list = Client.get_all_clients(opts)
  client_found = client_list.find {|client| name == client.name}
  Client.new(client_found.clientID, client_found.name, :apiKey=> opts[:apiKey]) if client_found
end

.get_all_clients(opts = {}) ⇒ Object

Gets all clients for a given user (CAMPAIGN_MONITOR_API_KEY).

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 collection of Campaigning::Client objects.

Error: An Exception containing the cause of the error will be raised.



89
90
91
92
93
 
# File 'lib/campaigning/client.rb', line 89

def self.get_all_clients(opts={})
  response  = @@soap.getClients(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY)
  clients   = handle_response response.user_GetClientsResult
  clients.collect {|client| Client.new(client.clientID, client.name, :apiKey=> opts[:apiKey])}
end

Instance Method Details

#campaigns ⇒ Object

Gets a list of all campaigns that have been sent for a client.

Return:

Success: Upon a successful call, this method will return a collection of Campaigning::Campaign objects.

Error: An Exception containing the cause of the error will be raised.



195
196
197
198
199
200
201
 
# File 'lib/campaigning/client.rb', line 195

def campaigns
  response = @@soap.getClientCampaigns(:apiKey => @apiKey, :clientID => @clientID )
  campaign_list = handle_response response.client_GetCampaignsResult
  campaign_list.collect do |campaign|  
    Campaign.new(campaign.campaignID, campaign.subject, campaign.name, campaign.sentDate, campaign.totalRecipients, :apiKey=> @apiKey)
  end
end

#delete! ⇒ Object

Deletes a client from your account.

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.



134
135
136
137
138
 
# File 'lib/campaigning/client.rb', line 134

def delete!
  response = Client.delete!(@clientID, :apiKey=> @apiKey)
  self.clientID, self.name = nil
  response
end

#details ⇒ Object

This method gets the complete account and billing details for a particular client.

Example of usage: client_details = client_obj.details basic_details = client_details.basicDetails access_and_billing_details = client_details.accessAndBilling puts “Basic details:” puts “Client ID: #Campaigning::Client.basic_detailsbasic_details.clientIDn

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: #Campaigning::Client.access_and_billing_detailsaccess_and_billing_details.usernamen 

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}"

Return:

Success: A successful call to this method will return a ClientDetail object, comprised of ClientBasicDetails and ClientAccessAndBilling.

Error: An Exception containing the cause of the error will be raised.



232
233
234
235
 
# File 'lib/campaigning/client.rb', line 232

def details
  response = @@soap.getClientDetail(:apiKey => @apiKey, :clientID => @clientID )
  handle_response response.client_GetDetailResult
end

#find_campaigns_by_subject(subject) ⇒ Object

This method finds campaigns by a given subject, since the subject isn’t unique, it returns an collection of Campaigning::Campaign object.

Return:

Success: Upon a successful call, this method will return a collection of Campaigning::Campaign objects.

Campaign FOUND: If it found any campaign with the given subject it will return a collection of Campaigning::Campaign that match the criteria.

Campaign NOT FOUND: If it doesn’t found a campaign with the given subject it will return an empty array.

Error: An Exception containing the cause of the error will be raised.



181
182
183
184
185
186
 
# File 'lib/campaigning/client.rb', line 181

def find_campaigns_by_subject(subject)#-- TODO: Refactor this method
  arr = []
  #return campaigns.find {|campaign| subject == campaign.subject} if params[:single] 
  campaigns.each { |campaign| arr << campaign if campaign.subject == subject }
  arr
end

#find_list_by_name(list_name) ⇒ Object

This method find a List by a given name

Return:

Success:

List FOUND: If it found any client with the given name it will return a Campaigning::List object containing the found list.

List NOT FOUND: If it doesn’t found a list with the given name it will return nil .

Error: An Exception containing the cause of the error will be raised.



55
56
57
 
# File 'lib/campaigning/client.rb', line 55

def find_list_by_name(list_name)
  lists.find {|list| list_name == list.name}
end

#lists ⇒ Object

Gets a list of all subscriber lists for a client.

Return:

Success: Upon a successful call, this method will return a collection of Campaigning::List objects.

Error: An Exception containing the cause of the error will be raised.



38
39
40
41
42
 
# File 'lib/campaigning/client.rb', line 38

def lists
  response = @@soap.getClientLists(:apiKey => @apiKey, :clientID => @clientID)
  lists = handle_response response.client_GetListsResult
  lists.collect {|list| List.new(list.listID, list.name, :apiKey=> @apiKey)}
end

#segments ⇒ Object

Gets a list of all subscriber segments for a client.

Return:

Success: Upon a successful call, this method will return a collection of Campaigning::List objects, each of which consists of the ListID for the parent list and Segment Name for each segment for a client.

Error: An Exception containing the cause of the error will be raised.



164
165
166
167
 
# File 'lib/campaigning/client.rb', line 164

def segments # TODO: Verify the type return for this method.
  response = @@soap.getClientSegments(:apiKey => @apiKey, :clientID => @clientID )
  handle_response response.client_GetSegmentsResult
end

#suppression_list ⇒ Object

Gets all subscribers in the client-wide suppression list.

Return:

Success: Upon a successful call, this method will return a collection of Subscriber objects.

Error: An Exception containing the cause of the error will be raised.



244
245
246
247
 
# File 'lib/campaigning/client.rb', line 244

def suppression_list
  response = @@soap.getClientSuppressionList(:apiKey => @apiKey, :clientID => @clientID )
  handle_response response.client_GetSuppressionListResult    
end

#templates ⇒ Object

Gets a list of all templates for a client.

Return:

Success: Upon a successful call, this method will return a collection of Campaigning::Template objects.

Error: An Exception containing the cause of the error will be raised.



24
25
26
27
28
 
# File 'lib/campaigning/client.rb', line 24

def templates      
  response = @@soap.getClientTemplates(:apiKey => @apiKey, :clientID => @clientID)
  templates = handle_response response.client_GetTemplatesResult
  templates.collect {|template| Template.new(template.templateID, template.name, template.previewURL, template.screenshotURL, :apiKey=> @apiKey)}
end

#update_access_and_billing!(params) ⇒ Object

Update the access and billing settings of an existing client, leaving the basic details untouched.

Here’s a list of all the parameters you’ll need to pass to the Campaigning::Client#update_access_and_billing! method. Only the :access_level parameter is required for all calls. The relevance and necessity of the other parameters depends on the chosen AccessLevel (and BillingType), and will be fully described along with each parameter.

Available params argument are:

* :accessLevel - An integer describing the client's ability to access different areas of the application. Influences the significance
                  and requirements of the following parameters. See http://www.campaignmonitor.com/api/method/client-updateaccessandbilling/#accesslevels
                  for a full description of available levels.
* :username - Client login username. Not required and ignored if AccessLevel is set to 0.
* :password - Client login password. Not required and ignored if AccessLevel is set to 0.
* :billingType - Client billing type, only required if :accessLevel is set to allow the client to create and send campaigns
* :currency - Billing currency for this client, only required if :billingType is set to either ClientPaysAtStandardRate or
              ClientPaysWithMarkup. See full details: http://www.campaignmonitor.com/api/method/client-updateaccessandbilling/#currencies.
* :deliveryFee - Flat rate delivery fee to be charged to the client for each campaign sent, expressed in the chosen currency's
                  major unit, but without the currency symbol (for example, sending "6.5" means "$6.50" if USD is used). Only
                  required if BillingType is set to ClientPaysWithMarkup, in which case it should be at least equal to the standard rate.
                  Further detail is available at http://help.campaignmonitor.com/topic.aspx?t=118.
* :costPerRecipient - Additional cost added to the campaign for each email address the campaign is sent to, expressed in the chosen
                        currency's minor unit (for example, sending "1.5" means 1.5 cents per email address if USD is used). Only required
                        if BillingType is set to ClientPaysWithMarkup, in which case it should be at least equal to the standard cost/recipient
                        rate. Further detail is available at http://help.campaignmonitor.com/topic.aspx?t=118.
* :designAndSpamTestFee - Expressed in the chosen currency's major unit (for example, sending "10" means "$10" if USD is used). Only required
                              if BillingType is set to ClientPaysWithMarkup and client has access to design and spam tests, in which case the fee
                              should be equal to or higher than the standard rate (identical to the standard DeliveryFee for that currency).

Please note that for reasons of security there is no way to set a client’s credit card details via the API. It will have to be done in the application.

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.



286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
 
# File 'lib/campaigning/client.rb', line 286

def update_access_and_billing!(params)
  response = @@soap.updateClientAccessAndBilling(
  :apiKey => @apiKey,
  :clientID => @clientID,
  :accessLevel => params[:accessLevel],
  :username => params.fetch(:username, ""),
  :password => params.fetch(:password, ""),
  :billingType => params.fetch(:billingType, ""),
  :currency => params.fetch(:currency, ""),
  :deliveryFee => params.fetch(:deliveryFee, ""),
  :costPerRecipient => params.fetch(:costPerRecipient, ""),
  :designAndSpamTestFee => params.fetch(:designAndSpamTestFee, "")
  )
  handle_response response.client_UpdateAccessAndBillingResult
end

#update_basics!(params) ⇒ Object

Updates the basic details of an existing client. If you wish to change only some details, the others must be included as they currently are. Please note that the client’s existing access and billing details will remain unchanged by a call to this method.

Available params argument are:

* :companyName - The client company name.
* :contactName - The personal name of the principle contact for this client.
* :emailAddress - An email address to which this client will be sent application-related emails.
* :country - This client's country.
* :timezone - Client timezone for tracking and reporting data. Valid timezone strings are obtainable by means of the
               API procedure Campaigning.timezones.

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.



320
321
322
323
324
325
326
327
328
329
330
331
 
# File 'lib/campaigning/client.rb', line 320

def update_basics!(params)
  response = @@soap.updateClientBasics(
  :apiKey => @apiKey,
  :clientID => @clientID,
  :companyName => params[:companyName],
  :contactName => params[:contactName],
  :emailAddress => params[:emailAddress],
  :country => params[:country],
  :timezone => params[:timezone]
  )
  handle_response response.client_UpdateBasicsResult
end