Class: CampaignMonitor::List

Inherits:
Base
  • Object
show all
Includes:
Helpers
Defined in:
lib/campaign_monitor/list.rb

Overview

Provides access to the subscribers and info about subscribers associated with a Mailing List

Constant Summary

VALID_ATTRIBUTES =
%w{ConfirmOptIn

Instance Attribute Summary

Attributes inherited from Base

#attributes, #cm_client, #result

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods included from Helpers

#formatted_timestamp, #handle_response, #timestamp_format

Methods inherited from Base

#[], #[]=, client, client=, #id, #id=, #name

Constructor Details

- (List) initialize(attrs = {})

Example

@list = new List(12345)


16
17
18
19
# File 'lib/campaign_monitor/list.rb', line 16

def initialize(attrs={})
  super
  @attributes=attrs
end

Class Method Details

+ (Object) [](k)

loads a list by it's ID



50
51
52
# File 'lib/campaign_monitor/list.rb', line 50

def self.[](k)
  GetDetail(k)
end

+ (Object) GetDetail(id)

Loads a list by it's ID



41
42
43
44
45
# File 'lib/campaign_monitor/list.rb', line 41

def self.GetDetail(id)
  list=self.new("ListID" => id)
  list.GetDetail(true)
  list.result.code == 101 ? nil : list
end

Instance Method Details

- (Object) active_subscribers(date)

Example

current_date = DateTime.new
@list = new List(12345)
@subscribers = @list.active_subscribers(current_date)

for subscriber in @subscribers
  puts subscriber.email
end


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

def active_subscribers(date)
  response = cm_client.Subscribers_GetActive('ListID' => self.id, 'Date' => formatted_timestamp(date))
  handle_response(response) do
    response['Subscriber'].collect{|s| Subscriber.new(s['EmailAddress'], s['Name'], s['Date'])}
  end
end

- (Object) add_and_resubscribe(email, name = nil, custom_fields = nil)



98
99
100
101
102
103
104
# File 'lib/campaign_monitor/list.rb', line 98

def add_and_resubscribe(email, name=nil, custom_fields=nil)
  if custom_fields.nil?
    Result.new(cm_client.Subscriber_AddAndResubscribe("ListID" => self.id, "Email" => email, "Name" => name))        
  else
    add_and_resubscribe_with_custom_fields(email, name, custom_fields)
  end
end

- (Object) add_and_resubscribe_with_custom_fields(email, name, custom_fields)

email The subscriber's email address. name The subscriber's name. custom_fields A hash of field name => value pairs.



136
137
138
139
140
141
142
143
144
145
146
147
# File 'lib/campaign_monitor/list.rb', line 136

def add_and_resubscribe_with_custom_fields(email, name, custom_fields)      
  response = cm_client.using_soap do |driver|
    driver.addAndResubscribeWithCustomFields \
        :ApiKey       => cm_client.api_key,
        :ListID       => self.id,
        :Email        => email,
        :Name         => name,
        :CustomFields => { :SubscriberCustomField => custom_fields_array(custom_fields) }
  end

  response.subscriber_AddAndResubscribeWithCustomFieldsResult
end

- (Object) add_subscriber(email, name = nil, custom_fields = nil)

Example

@list = new List(12345)
result = @list.add_subscriber("ralph.wiggum@simpsons.net")

if result.succeeded?
  puts "Added Subscriber"
end


90
91
92
93
94
95
96
# File 'lib/campaign_monitor/list.rb', line 90

def add_subscriber(email, name=nil, custom_fields=nil)
  if custom_fields.nil?
    Result.new(cm_client.Subscriber_Add("ListID" => self.id, "Email" => email, "Name" => name))
  else
    add_subscriber_with_custom_fields(email, name, custom_fields)
  end
end

- (Object) add_subscriber_with_custom_fields(email, name, custom_fields)

email The subscriber's email address. name The subscriber's name. custom_fields A hash of field name => value pairs.



120
121
122
123
124
125
126
127
128
129
130
131
# File 'lib/campaign_monitor/list.rb', line 120

def add_subscriber_with_custom_fields(email, name, custom_fields)
  response = cm_client.using_soap do |driver|
    driver.addSubscriberWithCustomFields \
        :ApiKey       => cm_client.api_key,
        :ListID       => self.id,
        :Email        => email,
        :Name         => name,
        :CustomFields => { :SubscriberCustomField => custom_fields_array(custom_fields) }
  end
  
  response.subscriber_AddWithCustomFieldsResult
end

- (Object) bounced(date)

Example

current_date = DateTime.new
@list = new List(12345)
@subscribers = @list.bounced(current_date)

for subscriber in @subscribers
  puts subscriber.email
end


190
191
192
193
194
195
196
# File 'lib/campaign_monitor/list.rb', line 190

def bounced(date)
  response = cm_client.Subscribers_GetBounced('ListID' => self.id, 'Date' => formatted_timestamp(date))

  handle_response(response) do
    response["Subscriber"].collect{|s| Subscriber.new(s["EmailAddress"], s["Name"], s["Date"])}        
  end
end

- (Object) Create



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

def Create
  @result=Result.new(cm_client.List_Create(@attributes))
  self.id = @result.content if @result.success?
  @result.success?
end

- (Object) defaults

Example



25
26
27
28
29
30
31
# File 'lib/campaign_monitor/list.rb', line 25

def defaults
  defaults={"ConfirmOptIn" => "false",
    "UnsubscribePage" => "",
    "ConfirmationSuccessPage" => ""}
  @attributes=defaults.merge(@attributes)
  self
end

- (Object) Delete



72
73
74
75
# File 'lib/campaign_monitor/list.rb', line 72

def Delete
  @result=Result.new(cm_client.List_Delete("ListID" => id))
  @result.success?
end

- (Object) GetDetail(overwrite = false)



54
55
56
57
58
59
# File 'lib/campaign_monitor/list.rb', line 54

def GetDetail(overwrite=false)
  @result=Result.new(cm_client.List_GetDetail("ListID" => id))
  @attributes=@result.raw.merge(@attributes)
  @attributes.merge!(@result.raw) if overwrite
  @result.success?
end

- (Object) remove_subscriber(email)

Example

@list = new List(12345)
result = @list.remove_subscriber("ralph.wiggum@simpsons.net")

if result.succeeded?
  puts "Deleted Subscriber"
end


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

def remove_subscriber(email)
  Result.new(cm_client.Subscriber_Unsubscribe("ListID" => self.id, "Email" => email))
end

- (Object) save

AR like



34
35
36
# File 'lib/campaign_monitor/list.rb', line 34

def save
  id ? Update : Create
end

- (Object) unsubscribed(date)

Example

current_date = DateTime.new
@list = new List(12345)
@subscribers = @list.unsubscribed(current_date)

for subscriber in @subscribers
  puts subscriber.email
end


172
173
174
175
176
177
178
179
180
# File 'lib/campaign_monitor/list.rb', line 172

def unsubscribed(date)
  date = formatted_timestamp(date) unless date.is_a?(String)
  
  response = cm_client.Subscribers_GetUnsubscribed('ListID' => self.id, 'Date' => date)
  
  handle_response(response) do
    response['Subscriber'].collect{|s| Subscriber.new(s['EmailAddress'], s['Name'], s['Date'])}
  end
end

- (Object) Update



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

def Update
  # if we're dealing with a half baked object that Client#lists has given
  # us then we need to popular all the fields before we can attempt an update
  unless @fully_baked
    self.GetDetail
    @fully_baked=true
  end
  @result=Result.new(cm_client.List_Update(@attributes))
  @result.success?
end