Class: CampaignMonitor

Inherits:
Object
  • Object
show all
Includes:
Helpers
Defined in:
lib/campaign_monitor.rb,
lib/campaign_monitor/base.rb,
lib/campaign_monitor/list.rb,
lib/campaign_monitor/misc.rb,
lib/campaign_monitor/client.rb,
lib/campaign_monitor/result.rb,
lib/campaign_monitor/helpers.rb,
lib/campaign_monitor/campaign.rb,
lib/campaign_monitor/subscriber.rb

Overview

A wrapper class to access the Campaign Monitor API. Written using the wonderful Flickr interface by Scott Raymond as a guide on how to access remote web services

For more information on the Campaign Monitor API, visit campaignmonitor.com/api

Author

Jordan Brock <[email protected]>

Copyright

Copyright © 2006 Jordan Brock <[email protected]>

License

MIT <www.opensource.org/licenses/mit-license.php>

USAGE:

require 'campaign_monitor'
cm = CampaignMonitor.new(API_KEY)     # creates a CampaignMonitor object
                                      # Can set CAMPAIGN_MONITOR_API_KEY in environment.rb
cm.clients                            # Returns an array of clients associated with
                                      #   the user account
cm.campaigns(client_id)
cm.lists(client_id)
cm.add_subscriber(list_id, email, name)

CLIENT

client = Client[client_id] # find an existing client
client = Client.new(attributes)
client.Create
client.Delete
client.GetDetail
client.UpdateAccessAndBilling
client.UpdateBasics
client.update # update basics, access, and billing
client.lists # OR
client.GetLists
client.lists.build # to create a new unsaved list for a client
client.campaigns # OR
client.GetCampaigns

LIST

list = List[list_id] # find an existing list
list = List.new(attributes)
list.Create
list.Delete
list.Update
list.add_subscriber(email, name)
list.remove_subscriber(email)
list.active_subscribers(date)
list.unsubscribed(date)
list.bounced(date)

CAMPAIGN

campaign = Campaign.new(campaign_id)
campaign.clicks
campaign.opens
campaign.bounces
campaign.unsubscribes
campaign.number_recipients
campaign.number_clicks
campaign.number_opens
campaign.number_bounces
campaign.number_unsubscribes

SUBSCRIBER

subscriber = Subscriber.new(email)
subscriber.add(list_id)
subscriber.unsubscribe(list_id)

Data Types

SubscriberBounce
SubscriberClick
SubscriberOpen
SubscriberUnsubscribe
Result

Defined Under Namespace

Modules: Helpers Classes: ApiError, Base, Campaign, Client, ClientLists, InvalidAPIKey, List, Result, Subscriber, SubscriberBounce, SubscriberClick, SubscriberOpen, SubscriberUnsubscribe

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Helpers

#formatted_timestamp, #handle_response, #timestamp_format

Constructor Details

#initialize(api_key = CAMPAIGN_MONITOR_API_KEY) ⇒ CampaignMonitor

Replace this API key with your own (www.campaignmonitor.com/api/)



101
102
103
104
105
 
# File 'lib/campaign_monitor.rb', line 101

def initialize(api_key=CAMPAIGN_MONITOR_API_KEY)
 @api_key = api_key
 @api_url = 'http://api.createsend.com/api/api.asmx'
 CampaignMonitor::Base.client=self
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method_id, params = {}) ⇒ Object

By overriding the method_missing method, it is possible to easily support all of the methods available in the API



143
144
145
146
147
148
 
# File 'lib/campaign_monitor.rb', line 143

def method_missing(method_id, params = {})
  puts "  CM: #{method_id} (#{params.inspect})" if $debug
  res=request(method_id.id2name.gsub(/_/, '.'), params)
  puts "    returning: #{res.inspect}" if $debug
  res
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



98
99
100
 
# File 'lib/campaign_monitor.rb', line 98

def api_key
  @api_key
end

#api_url ⇒ Object (readonly)

Returns the value of attribute api_url.



98
99
100
 
# File 'lib/campaign_monitor.rb', line 98

def api_url
  @api_url
end

Instance Method Details

#add_subscriber(list_id, email, name) ⇒ Object

A quick method of adding a subscriber to a list. Returns a Result object

Example

@cm = CampaignMonitor.new()
result = @cm.add_subscriber(12345, "[email protected]", "Ralph Wiggum")

if result.succeeded?
  puts "Subscriber Added to List"
end



228
229
230
 
# File 'lib/campaign_monitor.rb', line 228

def add_subscriber(list_id, email, name)
  Result.new(Subscriber_Add("ListID" => list_id, "Email" => email, "Name" => name))
end

#campaigns(client_id) ⇒ Object

Returns an array of Campaign objects associated with the specified Client ID

Example

@cm = CampaignMonitor.new()
@campaigns = @cm.campaigns(12345)

for campaign in @campaigns
  puts campaign.subject
end



198
199
200
201
202
 
# File 'lib/campaign_monitor.rb', line 198

def campaigns(client_id)
  handle_response(Client_GetCampaigns("ClientID" => client_id)) do |response|
    response["Campaign"].collect{|c| Campaign.new(c) }
  end
end

#clients ⇒ Object

Returns an array of Client objects associated with the API Key

Example

@cm = CampaignMonitor.new()
@clients = @cm.clients

for client in @clients
  puts client.name
end



159
160
161
162
163
 
# File 'lib/campaign_monitor.rb', line 159

def clients
  handle_response(User_GetClients()) do |response|
    response["Client"].collect{|c| Client.new({"ClientID" => c["ClientID"], "CompanyName" => c["Name"]})}
  end
end

#countries ⇒ Object 



177
178
179
180
181
 
# File 'lib/campaign_monitor.rb', line 177

def countries
  handle_response(User_GetCountries()) do | response |
    response["string"]
  end
end

#http_get(url) ⇒ Object

Does an HTTP GET on a given URL and returns the response body



136
137
138
139
 
# File 'lib/campaign_monitor.rb', line 136

def http_get(url)
  response=Net::HTTP.get_response(URI.parse(url))
  response.body.to_s
end

#lists(client_id) ⇒ Object

Returns an array of Subscriber Lists for the specified Client ID

Example

@cm = CampaignMonitor.new()
@lists = @cm.lists(12345)

for list in @lists
  puts list.name
end



213
214
215
216
217
 
# File 'lib/campaign_monitor.rb', line 213

def lists(client_id)
  handle_response(Client_GetLists("ClientID" => client_id)) do |response|
    response["List"].collect{|l| List.new({"ListID" => l["ListID"], "Title" => l["Name"]})}
  end
end

#new_client ⇒ Object 



165
166
167
 
# File 'lib/campaign_monitor.rb', line 165

def new_client
  Client.new(nil)
end

#parsed_system_date ⇒ Object 



173
174
175
 
# File 'lib/campaign_monitor.rb', line 173

def parsed_system_date
  DateTime.strptime(system_date, timestamp_format)
end

#request(method, params) ⇒ Object

Takes a CampaignMonitor API method name and set of parameters; returns an XmlSimple object with the response



109
110
111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/campaign_monitor.rb', line 109

def request(method, params)
  request_xml=http_get(request_url(method, params))
  begin
    response = PARSER.xml_in(request_xml, { 'keeproot' => false,
      'forcearray' => %w[List Campaign Subscriber Client SubscriberOpen SubscriberUnsubscribe SubscriberClick SubscriberBounce],
      'noattr' => true })
    response.delete('d1p1:type')
    response.delete("d1p1:http://www.w3.org/2001/XMLSchema-instance:type")
    response
  # rescue XML::Parser::ParseError
  rescue XML::Error
    { "Code" => 500, "Message" => request_xml.split(/\r?\n/).first, "FullError" => request_xml }
  end
end

#request_url(method, params = {}) ⇒ Object

Takes a CampaignMonitor API method name and set of parameters; returns the correct URL for the REST API.



125
126
127
128
129
130
131
132
133
 
# File 'lib/campaign_monitor.rb', line 125

def request_url(method, params={})
  params.merge!('ApiKey' => api_key)
  
  query = params.collect do |key, value|
    "#{CGI.escape(key.to_s)}=#{CGI.escape(value.to_s)}"
  end.sort * '&'
  
  "#{api_url}/#{method}?#{query}"
end

#system_date ⇒ Object 



169
170
171
 
# File 'lib/campaign_monitor.rb', line 169

def system_date
  User_GetSystemDate()
end

#timezones ⇒ Object 



183
184
185
186
187
 
# File 'lib/campaign_monitor.rb', line 183

def timezones
  handle_response(User_GetTimezones()) do | response |
    response["string"]
  end
end

#using_soap ⇒ Object 



232
233
234
235
236
237
238
239
 
# File 'lib/campaign_monitor.rb', line 232

def using_soap
  driver = wsdl_driver_factory.create_rpc_driver
  driver.wiredump_dev = STDERR if $debug
  response = yield(driver)
  driver.reset_stream
  
  response
end