Class: Campaigning::List

Inherits:
Object
  • Object
show all
Includes:
Helpers
Defined in:
lib/campaigning/soap/generated/default.rb,
lib/campaigning/types/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 Helpers

#handle_response, included

Constructor Details

#initialize(listID = nil, name = nil) ⇒ List

Returns a new instance of List.



13
14
15
16
17
 
# File 'lib/campaigning/types/list.rb', line 13

def initialize(listID = nil, name = nil)
  @listID = listID
  @name = name
  @soap = Campaigning::SOAPDriver.instance.get_driver
end

Instance Attribute Details

#listID ⇒ Object

Returns the value of attribute listID.



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

def listID
  @listID
end

#name ⇒ Object

Returns the value of attribute name.



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

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.



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

def self.create(params)
  response = Campaigning::SOAPDriver.instance.get_driver.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.



94
95
96
97
 
# File 'lib/campaigning/types/list.rb', line 94

def self.delete(list_id)
  response = Campaigning::SOAPDriver.instance.get_driver.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.



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

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.



120
121
122
123
 
# File 'lib/campaigning/types/list.rb', line 120

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.



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

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.



107
108
109
110
 
# File 'lib/campaigning/types/list.rb', line 107

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.



133
134
135
136
 
# File 'lib/campaigning/types/list.rb', line 133

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.



159
160
161
162
163
164
165
166
 
# File 'lib/campaigning/types/list.rb', line 159

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.



196
197
198
199
200
201
202
203
 
# File 'lib/campaigning/types/list.rb', line 196

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.



179
180
181
182
183
184
185
186
 
# File 'lib/campaigning/types/list.rb', line 179

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.



145
146
147
 
# File 'lib/campaigning/types/list.rb', line 145

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.



222
223
224
225
226
227
228
229
230
231
232
 
# File 'lib/campaigning/types/list.rb', line 222

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