Class: Campaigning::Campaign

Inherits:
Object
  • Object
show all
Includes:
ModuleMixin
Defined in:
lib/campaigning/soap/generated/default.rb,
lib/campaigning/campaign.rb

Overview

/Campaign

campaignID - SOAP::SOAPString
subject - SOAP::SOAPString
name - SOAP::SOAPString
sentDate - SOAP::SOAPString
totalRecipients - SOAP::SOAPInt

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from ModuleMixin

#handle_response, included

Constructor Details

#initialize(campaignID = nil, subject = nil, name = nil, sentDate = nil, totalRecipients = nil) ⇒ Campaign

Returns a new instance of Campaign.



15
16
17
18
19
20
21
22
 
# File 'lib/campaigning/campaign.rb', line 15

def initialize(campaignID = nil, subject = nil, name = nil, sentDate = nil, totalRecipients = nil, opts={})
  @apiKey     = opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY
  @campaignID = campaignID
  @subject    = subject
  @name       = name
  @sentDate   = sentDate
  @totalRecipients = totalRecipients
end

Instance Attribute Details

#campaignID ⇒ Object

Returns the value of attribute campaignID.



9
10
11
 
# File 'lib/campaigning/campaign.rb', line 9

def campaignID
  @campaignID
end

#name ⇒ Object

Returns the value of attribute name.



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

def name
  @name
end

#sentDate ⇒ Object

Returns the value of attribute sentDate.



12
13
14
 
# File 'lib/campaigning/campaign.rb', line 12

def sentDate
  @sentDate
end

#subject ⇒ Object

Returns the value of attribute subject.



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

def subject
  @subject
end

#totalRecipients ⇒ Object

Returns the value of attribute totalRecipients.



13
14
15
 
# File 'lib/campaigning/campaign.rb', line 13

def totalRecipients
  @totalRecipients
end

Class Method Details

.create!(params) ⇒ Object

Creates a campaign for an existing client. This campaign will be imported and ready to send to the subscribers in the specified lists and segments. The campaign must have both HTML and plain text content, imported from the internet. Styling for the HTML content will be automatically brought inline.

Available params argument are:

* :clientID - The ID of the Client you want to create a campaign
* :campaignName - The name of the new campaign. This must be unique across all draft campaigns for the client.
* :campaignSubject - The subject of the new campaign.
* :fromName - The name to appear in the From field in the recipients email client when they receive the new campaign.
* :fromEmail - The email address that the new campaign will come from.
* :replyTo - The email address that any replies to the new campaign will be sent to.
* :htmlUrl - The URL of the HTML content for the new campaign. If no unsubscribe link is found then one will be added automatically. Styling in
             the campaign will be automatically brought inline. If your URL has querystring values, you will need to encode them.
* :textUrl - The URL of the Text content for the new campaign. If no unsubscribe link is found then one will be added automatically.
* :subscriberListIDs - An array of lists to send the campaign to. See http://www.campaignmonitor.com/api/required/#listid for more details.
* :listSegments - An array of Segment Names and their appropriate List ID s to send the campaign to.
* :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.

Return:

Success: Upon a successful call, this method will return a Campaigning::Campaign object which was recently created.

Error: An Exception containing the cause of the error will be raised.



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/campaigning/campaign.rb', line 48

def self.create!(params)  
    response = @@soap.createCampaign(
       :apiKey => params[:apiKey] || CAMPAIGN_MONITOR_API_KEY,
       :clientID => params[:clientID],
       :campaignName => params[:campaignName],
       :campaignSubject => params[:campaignSubject],
       :fromName => params[:fromName],
       :fromEmail => params[:fromEmail],
       :replyTo => params[:replyTo],
       :htmlUrl => params[:htmlUrl],
       :textUrl => params[:textUrl],
       :subscriberListIDs => params[:subscriberListIDs],
       :listSegments => params[:listSegments]
      )

    campaign_id = handle_response response.campaign_CreateResult
    Campaign.new( campaign_id, nil, params[:campaignName], nil, nil, :apiKey=> (params[:apiKey] || CAMPAIGN_MONITOR_API_KEY) )
end

.delete!(campaign_id, opts = {}) ⇒ Object

Deletes an existing campaign.

Available opts argument are:

* :apiKey - optional API key to use to make request. Will use CAMPAIGN_MONITOR_API_KEY if not set.

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.



91
92
93
94
 
# File 'lib/campaigning/campaign.rb', line 91

def self.delete!(campaign_id, opts={})
  response = @@soap.deleteCampaign(:apiKey => opts[:apiKey] || CAMPAIGN_MONITOR_API_KEY, :campaignID => campaign_id)
  handle_response response.campaign_DeleteResult
end

Instance Method Details

#bounces ⇒ Object

Gets a list of all subscribers who bounced for a given campaign, and the type of bounce (H=Hard Bounce, S=Soft Bounce).

Return:

Success: Upon a successful call, this method will return a collection of SubscriberBounce objects, each of which consists of the subscribers :emailAddress, the listID they belong to, and the bounceType of bounce they experienced, whether hard or soft.

Error: An Exception containing the cause of the error will be raised.



105
106
107
108
 
# File 'lib/campaigning/campaign.rb', line 105

def bounces
  response = @@soap.getCampaignBounces(:apiKey => @apiKey, :campaignID => @campaignID )
  handle_response response.campaign_GetBouncesResult
end

#delete! ⇒ Object

Deletes an existing campaign.

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.



75
76
77
78
 
# File 'lib/campaigning/campaign.rb', line 75

def delete!
  Campaign.delete!(@campaignID, :apiKey=> @apiKey)
  self.campaignID, self.subject, self.sentDate, self.totalRecipients  = nil, nil, nil, nil
end

#lists ⇒ Object

Returns an array of Campaigning::List objects that a given campaign was sent to.

Return:

Success: Upon a successful call, this method will return a collection of Campaigning::List object.

Error: An Exception containing the cause of the error will be raised.



117
118
119
120
121
122
123
 
# File 'lib/campaigning/campaign.rb', line 117

def lists
  response = @@soap.getCampaignLists(:apiKey => @apiKey, :campaignID => @campaignID )
  lists = handle_response response.campaign_GetListsResult
  lists.collect do |list|  
    List.new(list.listID, list.name, :apiKey=> @apiKey)
  end
end

#opens ⇒ Object

Gets a list of all subscribers who opened a given campaign, and the number of times they opened the campaign.

Return:

Success: Upon a successful call, this method will return a collection of SubscriberOpen objects, each of which consists of the subscribers :emailAddress, the listID they belong to, and the numberOfOpens representing the number of times they opened the given campaign.

Error: An Exception containing the cause of the error will be raised.



134
135
136
137
 
# File 'lib/campaigning/campaign.rb', line 134

def opens
  response = @@soap.getCampaignOpens(:apiKey => @apiKey, :campaignID => @campaignID )
  handle_response response.campaign_GetOpensResult
end

#send!(params) ⇒ Object

Schedules an existing campaign for sending.

The campaign must be imported with defined recipients. For campaigns with more than 5 recipients the user must have sufficient credits or their credit card details saved within the application for the campaign to be sent via the API. For campaigns with 5 recipients or less the user must have enough test campaigns remaining in their API account. For further information about credits for campaigns please check at: www.campaignmonitor.com/api/method/campaign-send/

Available params argument are:

* :confirmationEmail - The email address that the confirmation email that the campaign has been sent will go to.
* :sendDate - The date the campaign should be scheduled to be sent. To send a campaign immediately pass in "Immediately".
               This date should be in the users timezone and formatted as YYYY-MM-DD HH:MM:SS.

Return: Upon a successful call, this method will return a Result object with the newly create Campaign’s ID as the Code.

Error: An Exception containing the cause of the error will be raised.



207
208
209
210
211
212
213
214
215
 
# File 'lib/campaigning/campaign.rb', line 207

def send!(params)
  response = @@soap.sendCampaign(
    :apiKey => @apiKey,
    :campaignID => @campaignID,
    :confirmationEmail => params[:confirmationEmail],
    :sendDate => params[:sendDate]
     )
  handle_response response.campaign_SendResult
end

#subscriber_clicks ⇒ Object

Gets a list of all subscribers who clicked a link for a given campaign, the ID of the list they belong to, the links they clicked, and the number of times they clicked the link.

Example of usage:

campaign_obj.subscriber_clicks.each do |subscriber|

puts "Subscriber: #{subscriber.emailAddress}"
subscriber.clickedLinks.each do |clicked| 
  puts "Clicked link: #{clicked.link} - Number of clicks: #{clicked.clicks}"
end

end

Return:

Success: Upon a successful call, this method will return a collection of SubscriberClick objects, each of which consists of the subscribers emailAddress, the listID representing list they belong to, and the clickedLinksarray representing the links they have clicked and the number of times they clicked each link.

Error: An Exception containing the cause of the error will be raised.



159
160
161
162
 
# File 'lib/campaigning/campaign.rb', line 159

def subscriber_clicks
  response = @@soap.getSubscriberClicks(:apiKey => @apiKey, :campaignID => @campaignID )
  handle_response response.campaign_GetSubscriberClicksResult
end

#summary ⇒ Object

Gets a statistical summary, including number of recipients and open count, for a given campaign.

Return:

Success: Upon a successful call, this method will return summary statistical values about this particular campaign including the number of recipients, the number of total opens, the number of link clicks, the number of recipients who unsubscribed and the number who bounced.

Error: An Exception containing the cause of the error will be raised.



173
174
175
176
 
# File 'lib/campaigning/campaign.rb', line 173

def summary
  response = @@soap.getCampaignSummary(:apiKey => @apiKey, :campaignID => @campaignID )
  handle_response response.campaign_GetSummaryResult
end

#unsubscribes ⇒ Object

Gets a list of all subscribers who unsubscribed for a given campaign.

Return:

Success: Upon a successful call, this method will return a collection of SubscriberUnsubscribe objects, each of which consists of the emailAddress representing subscribers email address and the listID representing the list they belong to.

Error: An Exception containing the cause of the error will be raised.



186
187
188
189
 
# File 'lib/campaigning/campaign.rb', line 186

def unsubscribes
  response = @@soap.getCampaignUnsubscribes(:apiKey => @apiKey, :campaignID => @campaignID )
  handle_response response.campaign_GetUnsubscribesResult
end