Class: Campaigning::List

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

Overview

/List

listID - 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(listID = nil, name = nil) ⇒ List

Returns a new instance of List.



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

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

Instance Attribute Details

#listID ⇒ Object

Returns the value of attribute listID.



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

def listID
  @listID
end

#name ⇒ Object

Returns the value of attribute name.



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

def name
  @name
end

Class Method Details

.create!(params) ⇒ Object

Creates a brand new subscriber list

Available params argument are:

* :clientID - The ID of the client who will owner of the list.
* :title - The list title. Must be unique for this client.
* :unsubscribePage - The URL to which subscribers will be directed when unsubscribing from the list.
                      If left blank or omitted a generic unsubscribe page is used.
* :confirmOptIn - Either true or false depending on whether the list requires email confirmation or not. Please see
                    the help documentation for more details of what this means.
* :confirmationSuccessPage - Successful email confirmations will be redirected to this URL. Ignored if ConfirmOptIn
                               is false. If left blank or omitted a generic confirmation page is used.
* :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::List object representing the newly created list.

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



34
35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/campaigning/list.rb', line 34

def self.create!(params)
  response = @@soap.createList(
  :apiKey => params[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
  :clientID => params[:clientID],
  :title => params[:title],
  :unsubscribePage => params.fetch(:unsubscribePage, ""),
  :confirmOptIn => params[:confirmOptIn],
  :confirmationSuccessPage => params.fetch(:confirmationSuccessPage, "")
  )      
  new_list_id = handle_response response.list_CreateResult
  List.new(new_list_id, params[:title], :apiKey=> params[:apiKey])
end

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

Deletes a list

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.



96
97
98
99
 
# File 'lib/campaigning/list.rb', line 96

def self.delete!(list_id, opts={})
  response = @@soap.deleteList(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :listID => list_id)
  handle_response response.list_DeleteResult
end

.stats(list_id, opts = {}) ⇒ Object

Gets statistics for a subscriber list

Return:

Success: A successful call to List.GetStats will return a ListStatistics object, consisting of TotalActiveSubscribers, NewActiveSubscribersToday, NewActiveSubscribersYesterday, NewActiveSubscribersThisWeek, NewActiveSubscribersThisMonth, NewActiveSubscribersThisYear, TotalUnsubscribes, UnsubscribesToday, UnsubscribesYesterday, UnsubscribesThisWeek, UnsubscribesThisMonth, UnsubscribesThisYear, TotalDeleted, DeletedToday, DeletedYesterday, DeletedThisWeek, DeletedThisMonth, DeletedThisYear, TotalBounces, BouncesToday, BouncesYesterday, BouncesThisWeek, BouncesThisMonth and BouncesThisYear.

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



128
129
130
131
 
# File 'lib/campaigning/list.rb', line 128

def self.stats(list_id, opts={})
  response = @@soap.getListStats(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :listID => list_id)
  handle_response response.list_GetStatsResult
end

Instance Method Details

#create_custom_field!(params) ⇒ Object

Creates a new custom field for a list

Available params argument are:

* :fieldName - The Name for the new Custom Field. This will be used to generate the custom fields Key.
* :dataType - The Data Type for the new Custom Field. This must be one of Text, Number, MultiSelectOne, or MultiSelectMany
* :options - The available options for a multi-valued custom field. Options should be an Array of Strings, like: %w[Brazil Ireland England].
             You can't pass this field for Text and Number custom fields

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.



61
62
63
64
65
66
67
68
69
70
 
# File 'lib/campaigning/list.rb', line 61

def create_custom_field!(params)      
  response = @@soap.createListCustomField(
  :apiKey => @apiKey,
  :listID => @listID,
  :fieldName => params[:fieldName],
  :dataType => params[:dataType],
  :options => params.fetch(:options, "") 
  )
  handle_response response.list_CreateCustomFieldResult
end

#custom_fields ⇒ Object

Gets all the Custom Fields available for a list

Return:

Success: Upon a successful call, this method will return a collection of Campaigning::ListCustomField complex types. The individual ListCustomField record consists of a fieldName, key, dataType and a fieldOptions containing a list of possible options for multi-valued custom fields.

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



155
156
157
158
 
# File 'lib/campaigning/list.rb', line 155

def custom_fields
  response = @@soap.getListCustomFields(:apiKey => @apiKey, :listID => @listID)
  handle_response response.list_GetCustomFieldsResult
end

#delete! ⇒ Object

Deletes a 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.



80
81
82
83
 
# File 'lib/campaigning/list.rb', line 80

def delete!
  List.delete!(@listID, :apiKey=> @apiKey)
  self.listID, self.name  = nil, nil
end

#delete_custom_field!(key) ⇒ Object

Deletes a custom field from a 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.



142
143
144
145
 
# File 'lib/campaigning/list.rb', line 142

def delete_custom_field!(key)
  response = @@soap.deleteListCustomField(:apiKey => @apiKey, :listID => @listID, :key => '['+key+']')
  handle_response response.list_DeleteCustomFieldResult
end

#details ⇒ Object

Gets a list’s configuration detail

Return:

Success: A successful call to this method will return a Campaigning::ListDetail object, consisting of listID, title, unsubscribePage, confirmOptIn, and confirmationSuccessPage (all as described in Campaigning::List#update and Campaigning::List.create).

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



168
169
170
171
 
# File 'lib/campaigning/list.rb', line 168

def details
  response = @@soap.getListDetail(:apiKey => @apiKey, :listID => @listID)
  handle_response response.list_GetDetailResult
end

#find_active_subscribers(joined_at) ⇒ Object

Gets a list of all active subscribers for a list that have been joined since the specified date. The joined_at param has to be a DateTime object, like:

list.find_active_subscribers(DateTime.new(y=2009,m=4,d=01, h=01,min=00,s=00))

Return:

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

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



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

def find_active_subscribers(joined_at)
  response = @@soap.getSubscribers(
  :apiKey => @apiKey,
  :listID => @listID,
  :date =>joined_at.strftime('%Y-%m-%d %H:%M:%S')
  )
  handle_response response.subscribers_GetActiveResult
end

#find_single_subscriber(email_address) ⇒ Object

This method returns all of a particular subscribers details, including email address, name, active/inactive status and all custom field data. If a subscriber with that email address does not exist in that list, a nil value is returned.

Return: Success: Upon a successful call, this method will return a collection of Campaigning::Subscriber objects. In this case every returned object will contain the value “Unsubscribed” in the state field.

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



231
232
233
234
235
236
237
238
 
# File 'lib/campaigning/list.rb', line 231

def find_single_subscriber(email_address) # TODO: Create a mehod to handle with custom fields returned like (names from "State Name" to "state_name")
  response = @@soap.getSingleSubscriber(
  :apiKey => @apiKey,
  :listID => @listID,
  :emailAddress => email_address
  )
  handle_response response.subscribers_GetSingleSubscriberResult
end

#find_unsubscribed(unjoined_at) ⇒ Object

Gets a list of all subscribers for a list that have unsubscribed since the specified date. The unjoined_at param has to be a DateTime object, like:

list.find_unsubscribed(DateTime.new(y=2009,m=4,d=01, h=01,min=00,s=00))

Return:

Success: Upon a successful call, this method will return a collection of Campaigning::Subscriber objects. In this case every returned object will contain the value “Unsubscribed” in the state field.

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



214
215
216
217
218
219
220
221
 
# File 'lib/campaigning/list.rb', line 214

def find_unsubscribed(unjoined_at)
  response = @@soap.getUnsubscribed(
  :apiKey => @apiKey,
  :listID => @listID,
  :date => unjoined_at.strftime('%Y-%m-%d %H:%M:%S') # TODO: Move that to a helper method
  )
  handle_response response.subscribers_GetUnsubscribedResult
end

#get_all_active_subscribers ⇒ Object

Gets a list of all active subscribers for a list.

Return:

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

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



180
181
182
 
# File 'lib/campaigning/list.rb', line 180

def get_all_active_subscribers
  find_active_subscribers(DateTime.new(y=1911,m=1,d=01, h=01,min=00,s=00))
end

#stats ⇒ Object

Gets statistics for a subscriber list

Return:

Success: A successful call to List.GetStats will return a ListStatistics object, consisting of TotalActiveSubscribers, NewActiveSubscribersToday, NewActiveSubscribersYesterday, NewActiveSubscribersThisWeek, NewActiveSubscribersThisMonth, NewActiveSubscribersThisYear, TotalUnsubscribes, UnsubscribesToday, UnsubscribesYesterday, UnsubscribesThisWeek, UnsubscribesThisMonth, UnsubscribesThisYear, TotalDeleted, DeletedToday, DeletedYesterday, DeletedThisWeek, DeletedThisMonth, DeletedThisYear, TotalBounces, BouncesToday, BouncesYesterday, BouncesThisWeek, BouncesThisMonth and BouncesThisYear.

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



112
113
114
 
# File 'lib/campaigning/list.rb', line 112

def stats
  List.stats(@listID, :apiKey=> @apiKey)
end

#update!(params) ⇒ Object

Update a subscriber list’s details

Available params argument are:

* :title - The list title, as it will be shown in the application and through the API.
* :unsubscribePage - The URL to which subscribers will be directed when unsubscribing from the list.
                      If left blank or omitted a generic unsubscribe page is used.
* :confirmOptIn - Either true or false depending on whether the list requires email confirmation or not. Please see
                    the help documentation for more details of what this means.
* :confirmationSuccessPage - Successful email confirmations will be redirected to this URL. Ignored if ConfirmOptIn
                               is false. If left blank or omitted a generic confirmation page is used.

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.



257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/campaigning/list.rb', line 257

def update!(params)
  response = @@soap.updateList(
  :apiKey => @apiKey,
  :listID => @listID,
  :title => params[:title],
  :unsubscribePage => params.fetch(:unsubscribePage, ""),
  :confirmOptIn => params[:confirmOptIn],
  :confirmationSuccessPage => params.fetch(:confirmationSuccessPage, "") 
  )
  handle_response response.list_UpdateResult
end