Class: CreateSend::List

Inherits:
CreateSend show all
Defined in:
lib/createsend/list.rb

Overview

Represents a subscriber list and associated functionality.

Constant Summary

Constants included from CreateSend

USER_AGENT_STRING, VERSION

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(auth, list_id) ⇒ List

Returns a new instance of List.



6
7
8
9
 
# File 'lib/createsend/list.rb', line 6

def initialize(auth, list_id)
  @list_id = list_id
  super
end

Instance Attribute Details

#list_id ⇒ Object (readonly)

Returns the value of attribute list_id.



4
5
6
 
# File 'lib/createsend/list.rb', line 4

def list_id
  @list_id
end

Class Method Details

.create(auth, client_id, title, unsubscribe_page, confirmed_opt_in, confirmation_success_page, unsubscribe_setting = "AllClientLists") ⇒ Object

Creates a new list for a client. client_id - String representing the ID of the client for whom the list

will be created

title - String representing the list title/name unsubscribe_page - String representing the url of the unsubscribe

confirmation page

confirmed_opt_in - A Boolean representing whether this should be a

confirmed opt-in (double opt-in) list

confirmation_success_page - String representing the url of the

confirmation success page

unsubscribe_setting - A String which must be either “AllClientLists” or

"OnlyThisList". See the documentation for details:
http://www.campaignmonitor.com/api/lists/#creating_a_list



24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/createsend/list.rb', line 24

def self.create(auth, client_id, title, unsubscribe_page, confirmed_opt_in,
  confirmation_success_page, unsubscribe_setting="AllClientLists")
  options = { :body => {
    :Title => title,
    :UnsubscribePage => unsubscribe_page,
    :ConfirmedOptIn => confirmed_opt_in,
    :ConfirmationSuccessPage => confirmation_success_page,
    :UnsubscribeSetting => unsubscribe_setting }.to_json }
  cs = CreateSend.new auth
  response = cs.post "/lists/#{client_id}.json", options
  response.parsed_response
end

Instance Method Details

#activate_webhook(webhook_id) ⇒ Object

Activates a webhook associated with this list.



214
215
216
217
 
# File 'lib/createsend/list.rb', line 214

def activate_webhook(webhook_id)
  options = { :body => '' }
  put "webhooks/#{webhook_id}/activate", options
end

#active(date = "", page = 1, page_size = 1000, order_field = "email", order_direction = "asc", include_tracking_preference = false) ⇒ Object

Gets the active subscribers for this list.



118
119
120
121
122
 
# File 'lib/createsend/list.rb', line 118

def active(date="", page=1, page_size=1000, order_field="email",
  order_direction="asc", include_tracking_preference=false)
  paged_result_by_date("active", date, page, page_size, order_field,
    order_direction, include_tracking_preference)
end

#bounced(date = "", page = 1, page_size = 1000, order_field = "email", order_direction = "asc", include_tracking_preference = false) ⇒ Object

Gets the bounced subscribers for this list.



132
133
134
135
136
 
# File 'lib/createsend/list.rb', line 132

def bounced(date="", page=1, page_size=1000, order_field="email",
  order_direction="asc", include_tracking_preference=false)
  paged_result_by_date("bounced", date, page, page_size, order_field,
    order_direction, include_tracking_preference)
end

#create_custom_field(field_name, data_type, options = [], visible_in_preference_center = true) ⇒ Object

Creates a new custom field for this list. field_name - String representing the name to be given to the field data_type - String representing the data type of the field. Valid data

types are 'Text', 'Number', 'MultiSelectOne', 'MultiSelectMany',
'Date', 'Country', and 'USState'.

options - Array of Strings representing the options for the field if it

is of type 'MultiSelectOne' or 'MultiSelectMany'.

visible_in_preference_center - Boolean indicating whether or not the

field should be visible in the subscriber preference center



51
52
53
54
55
56
57
58
59
60
 
# File 'lib/createsend/list.rb', line 51

def create_custom_field(field_name, data_type, options=[],
  visible_in_preference_center=true)
  options = { :body => {
    :FieldName => field_name,
    :DataType => data_type,
    :Options => options,
    :VisibleInPreferenceCenter => visible_in_preference_center }.to_json }
  response = post "customfields", options
  response.parsed_response
end

#create_webhook(events, url, payload_format) ⇒ Object

Creates a new webhook for the specified events (an array of strings). Valid events are “Subscribe”, “Deactivate”, and “Update”. Valid payload formats are “json”, and “xml”.



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

def create_webhook(events, url, payload_format)
  options = { :body => {
    :Events => events,
    :Url => url,
    :PayloadFormat => payload_format }.to_json }
  response = post "webhooks", options
  response.parsed_response
end

#custom_fields ⇒ Object

Gets the custom fields for this list.



100
101
102
103
 
# File 'lib/createsend/list.rb', line 100

def custom_fields
  response = get "customfields"
  response.map{|item| Hashie::Mash.new(item)}
end

#deactivate_webhook(webhook_id) ⇒ Object

De-activates a webhook associated with this list.



220
221
222
223
 
# File 'lib/createsend/list.rb', line 220

def deactivate_webhook(webhook_id)
  options = { :body => '' }
  put "webhooks/#{webhook_id}/deactivate", options
end

#delete ⇒ Object

Deletes this list.



38
39
40
 
# File 'lib/createsend/list.rb', line 38

def delete
  super "/lists/#{list_id}.json", {}
end

#delete_custom_field(custom_field_key) ⇒ Object

Deletes a custom field associated with this list.



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

def delete_custom_field(custom_field_key)
  custom_field_key = CGI.escape(custom_field_key)
  cs_delete("/lists/#{list_id}/customfields/#{custom_field_key}.json", {})
end

#delete_webhook(webhook_id) ⇒ Object

Deletes a webhook associated with this list.



209
210
211
 
# File 'lib/createsend/list.rb', line 209

def delete_webhook(webhook_id)
  cs_delete("/lists/#{list_id}/webhooks/#{webhook_id}.json", {})
end

#deleted(date = "", page = 1, page_size = 1000, order_field = "email", order_direction = "asc", include_tracking_preference = false) ⇒ Object

Gets the deleted subscribers for this list.



146
147
148
149
150
 
# File 'lib/createsend/list.rb', line 146

def deleted(date="", page=1, page_size=1000, order_field="email",
  order_direction="asc", include_tracking_preference=false)
  paged_result_by_date("deleted", date, page, page_size, order_field,
    order_direction, include_tracking_preference)
end

#details ⇒ Object

Gets the details of this list.



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

def details
  response = cs_get "/lists/#{list_id}.json"
  Hashie::Mash.new(response)
end

#segments ⇒ Object

Gets the segments for this list.



106
107
108
109
 
# File 'lib/createsend/list.rb', line 106

def segments
  response = get "segments"
  response.map{|item| Hashie::Mash.new(item)}
end

#stats ⇒ Object

Gets the stats for this list.



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

def stats
  response = get "stats"
  Hashie::Mash.new(response)
end

#test_webhook(webhook_id) ⇒ Object

Tests that a post can be made to the endpoint specified for the webhook identified by webhook_id.



203
204
205
206
 
# File 'lib/createsend/list.rb', line 203

def test_webhook(webhook_id)
  get "webhooks/#{webhook_id}/test"
  true # An exception will be raised if any error occurs
end

#unconfirmed(date = "", page = 1, page_size = 1000, order_field = "email", order_direction = "asc", include_tracking_preference = false) ⇒ Object

Gets the unconfirmed subscribers for this list.



125
126
127
128
129
 
# File 'lib/createsend/list.rb', line 125

def unconfirmed(date="", page=1, page_size=1000, order_field="email",
  order_direction="asc", include_tracking_preference=false)
  paged_result_by_date("unconfirmed", date, page, page_size, order_field,
    order_direction, include_tracking_preference)
end

#unsubscribed(date = "", page = 1, page_size = 1000, order_field = "email", order_direction = "asc", include_tracking_preference = false) ⇒ Object

Gets the unsubscribed subscribers for this list.



139
140
141
142
143
 
# File 'lib/createsend/list.rb', line 139

def unsubscribed(date="", page=1, page_size=1000, order_field="email",
  order_direction="asc", include_tracking_preference=false)
  paged_result_by_date("unsubscribed", date, page, page_size, order_field,
    order_direction, include_tracking_preference)
end

#update(title, unsubscribe_page, confirmed_opt_in, confirmation_success_page, unsubscribe_setting = "AllClientLists", add_unsubscribes_to_supp_list = false, scrub_active_with_supp_list = false) ⇒ Object

Updates this list. title - String representing the list title/name unsubscribe_page - String representing the url of the unsubscribe

confirmation page

confirmed_opt_in - A Boolean representing whether this should be a

confirmed opt-in (double opt-in) list

confirmation_success_page - String representing the url of the

confirmation success page

unsubscribe_setting - A String which must be either “AllClientLists” or

"OnlyThisList". See the documentation for details:
http://www.campaignmonitor.com/api/lists/#updating_a_list

add_unsubscribes_to_supp_list - When unsubscribe_setting is

"AllClientLists", a Boolean which represents whether unsubscribes from
this list should be added to the suppression list

scrub_active_with_supp_list - When unsubscribe_setting is

"AllClientLists", a Boolean which represents whether active sunscribers
should be scrubbed against the suppression list



169
170
171
172
173
174
175
176
177
178
179
180
181
 
# File 'lib/createsend/list.rb', line 169

def update(title, unsubscribe_page, confirmed_opt_in,
  confirmation_success_page, unsubscribe_setting="AllClientLists",
  add_unsubscribes_to_supp_list=false, scrub_active_with_supp_list=false)
  options = { :body => {
    :Title => title,
    :UnsubscribePage => unsubscribe_page,
    :ConfirmedOptIn => confirmed_opt_in,
    :ConfirmationSuccessPage => confirmation_success_page,
    :UnsubscribeSetting => unsubscribe_setting,
    :AddUnsubscribesToSuppList => add_unsubscribes_to_supp_list,
    :ScrubActiveWithSuppList => scrub_active_with_supp_list }.to_json }
  cs_put "/lists/#{list_id}.json", options
end

#update_custom_field(custom_field_key, field_name, visible_in_preference_center) ⇒ Object

Updates a custom field belonging to this list. custom_field_key - String which represents the key for the custom field field_name - String representing the name to be given to the field visible_in_preference_center - Boolean indicating whether or not the

field should be visible in the subscriber preference center



67
68
69
70
71
72
73
74
75
 
# File 'lib/createsend/list.rb', line 67

def update_custom_field(custom_field_key, field_name,
  visible_in_preference_center)
  custom_field_key = CGI.escape(custom_field_key)
  options = { :body => {
    :FieldName => field_name,
    :VisibleInPreferenceCenter => visible_in_preference_center }.to_json }
  response = put "customfields/#{custom_field_key}", options
  response.parsed_response
end

#update_custom_field_options(custom_field_key, new_options, keep_existing_options) ⇒ Object

Updates the options of a multi-optioned custom field on this list.



84
85
86
87
88
89
90
91
 
# File 'lib/createsend/list.rb', line 84

def update_custom_field_options(custom_field_key, new_options,
  keep_existing_options)
  custom_field_key = CGI.escape(custom_field_key)
  options = { :body => {
    :Options => new_options,
    :KeepExistingOptions => keep_existing_options }.to_json }
  put "customfields/#{custom_field_key}/options", options
end

#webhooks ⇒ Object

Gets the webhooks for this list.



184
185
186
187
 
# File 'lib/createsend/list.rb', line 184

def webhooks
  response = get "webhooks"
  response.map{|item| Hashie::Mash.new(item)}
end