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
 
# File 'lib/campaigning/list.rb', line 11

def initialize(listID = nil, name = nil)
  @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.

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.



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

def self.create!(params)
  response = @@soap.createList(
  :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])
end

.delete!(list_id) ⇒ 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.



91
92
93
94
 
# File 'lib/campaigning/list.rb', line 91

def self.delete!(list_id)
  response = @@soap.deleteList(:apiKey => CAMPAIGN_MONITOR_API_KEY, :listID => list_id)
  handle_response response.list_DeleteResult
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.



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

def create_custom_field!(params)      
  response = @@soap.createListCustomField(
  :apiKey => CAMPAIGN_MONITOR_API_KEY,
  :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.



117
118
119
120
 
# File 'lib/campaigning/list.rb', line 117

def custom_fields
  response = @@soap.getListCustomFields(:apiKey => CAMPAIGN_MONITOR_API_KEY, :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.



78
79
80
81
 
# File 'lib/campaigning/list.rb', line 78

def delete!
  List.delete!(@listID)
  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.



104
105
106
107
 
# File 'lib/campaigning/list.rb', line 104

def delete_custom_field!(key)
  response = @@soap.deleteListCustomField(:apiKey => CAMPAIGN_MONITOR_API_KEY, :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.



130
131
132
133
 
# File 'lib/campaigning/list.rb', line 130

def details
  response = @@soap.getListDetail(:apiKey => CAMPAIGN_MONITOR_API_KEY, :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.



156
157
158
159
160
161
162
163
 
# File 'lib/campaigning/list.rb', line 156

def find_active_subscribers(joined_at)
  response = @@soap.getSubscribers(
  :apiKey => CAMPAIGN_MONITOR_API_KEY,
  :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.



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

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 => CAMPAIGN_MONITOR_API_KEY,
  :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.



176
177
178
179
180
181
182
183
 
# File 'lib/campaigning/list.rb', line 176

def find_unsubscribed(unjoined_at)
  response = @@soap.getUnsubscribed(
  :apiKey => CAMPAIGN_MONITOR_API_KEY,
  :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.



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

def get_all_active_subscribers
  find_active_subscribers(DateTime.new(y=1911,m=1,d=01, h=01,min=00,s=00))
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.



219
220
221
222
223
224
225
226
227
228
229
 
# File 'lib/campaigning/list.rb', line 219

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