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 collapse

VALID_ATTRIBUTES = 
%w{ConfirmOptIn UnsubscribePage ConfirmationSuccessPage ListID Title}

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

#initialize(attrs = {}) ⇒ List

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

.[](k) ⇒ Object

loads a list by it’s ID



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

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

.GetDetail(id) ⇒ Object

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

#active_subscribers(date) ⇒ Object

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

#add_and_resubscribe(email, name = nil, custom_fields = nil) ⇒ Object 



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

#add_and_resubscribe_with_custom_fields(email, name, custom_fields) ⇒ Object

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

#add_subscriber(email, name = nil, custom_fields = nil) ⇒ Object

Example

@list = new List(12345)
result = @list.add_subscriber("[email protected]")

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

#add_subscriber_with_custom_fields(email, name, custom_fields) ⇒ Object

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

#bounced(date) ⇒ Object

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

#Create ⇒ Object 



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

#defaults ⇒ Object

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

#Delete ⇒ Object 



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

#GetDetail(overwrite = false) ⇒ Object 



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

#remove_subscriber(email) ⇒ Object

Example

@list = new List(12345)
result = @list.remove_subscriber("[email protected]")

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

#save ⇒ Object

AR like



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

def save
  id ? Update : Create
end

#unsubscribed(date) ⇒ Object

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

#Update ⇒ Object 



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