lib/hominid/campaign.rb in hominid-2.0.1 vs lib/hominid/campaign.rb in hominid-2.0.2
- old
+ new
@@ -1,172 +1,662 @@
module Hominid
-
- class Campaign < Base
-
- # Campaign related methods
- # --------------------------------
-
- attr_reader :campaign_id
- attr_reader :attributes
-
- def initialize(*args)
- options = args.last.is_a?(Hash) ? args.last : {}
- raise StandardError.new('Please provide a Campaign ID.') unless options[:id]
- @campaign_id = options.delete(:id)
- @attributes = options.delete(:attributes)
- super(options)
+ module Campaign
+
+ # CAMPAIGN RELATED METHODS
+
+ def campaigns(filters = {}, start = 0, limit = 25)
+ # Get all the campaigns for this account.
+ #
+ # Parameters:
+ # filters (Hash) = A hash of filters to apply to query. See the Mailchimp API documentation for more info.
+ # start (Integer) = Control paging of results.
+ # limit (Integer) = Number of campaigns to return. Upper limit set at 1000.
+ #
+ # Returns:
+ # An array of campaigns.
+ #
+ call("campaigns", filters, start, limit)
end
-
- def self.all
- # Get all campaigns for this mailchimp account
- new(:id => 0).call("campaigns").to_a.collect { |c| Campaign.new(:id => c.delete('id'), :attributes => c) }
+
+ def find_campaign_by_id(campaign_id)
+ # Find a campaign by id
+ #
+ # Parameters:
+ # campaign_id (String) = The unique ID of the campaign to return.
+ #
+ # Returns:
+ # A single campaign.
+ #
+ call("campaigns", {:campaign_id => campaign_id}).first
end
- def self.find_by_list_name(list_name)
- new(:id => 0).call("campaigns", {:list_id => List.find_by_name(list_name).list_id}).to_a.collect { |c| Campaign.new(:id=> c.delete('id'), :attributes => c) }
+ def find_campaign_by_web_id(campaign_web_id)
+ # Find a campaign by web_id
+ #
+ # Parameters:
+ # campaign_web_id (Integer) = The unique ID of the campaign to return.
+ #
+ # Returns:
+ # A single campaign.
+ #
+ call("campaigns").find {|campaign| campaign["web_id"] == campaign_web_id}
end
-
- def self.find_by_list_id(list_id)
- # Find all campaigns for the given list
- new(:id => 0).call("campaigns", {:list_id => list_id}).to_a.collect { |c| Campaign.new(:id=> c.delete('id'), :attributes => c) }
+
+ def find_campaigns_by_title(title)
+ # Find a campaign by name
+ #
+ # Parameters:
+ # title (String) = The title of the campaign to return.
+ #
+ # Returns:
+ # An array of campaigns.
+ #
+ call("campaigns", {:title => title})
end
-
- def self.find_by_title(title)
- # Find campaign by title
- all.find { |c| c.attributes['title'] =~ /#{title}/ }
+
+ def find_campaigns_by_list_name(list_name, start = 0, limit = 25)
+ # Find campaigns by list name
+ #
+ # Parameters:
+ # list_name (String) = The name of the mailing list to return campaigns for.
+ # start (Integer) = Control paging of results.
+ # limit (Integer) = Number of campaigns to return. Upper limit set at 1000.
+ #
+ # Returns:
+ # An array of campaigns.
+ #
+ call("campaigns", {:list_id => find_list_id_by_name(list_name)}, start, limit)
end
-
- def self.find_by_type(type)
- # Find campaign by type. Possible choices are:
- # 'regular'
- # 'plaintext'
- # 'absplit'
- # 'rss'
- # 'inspection'
- # 'trans'
- # 'auto'
- all.find { |campaign| campaign.attributes['type'] =~ /#{type}/ }
+
+ def find_campaigns_by_list_id(list_id, start = 0, limit = 25)
+ # Find campaigns by list id
+ #
+ # Parameters:
+ # list_id (String) = The ID of the mailing list to return campaigns for.
+ # start (Integer) = Control paging of results.
+ # limit (Integer) = Number of campaigns to return. Upper limit set at 1000.
+ #
+ # Returns:
+ # An array of campaigns.
+ #
+ call("campaigns", {:list_id => list_id}, start, limit)
end
-
- def self.find_by_web_id(web_id)
- # Find campaigns by web_id
- all.find { |campaign| campaign.attributes['web_id'] == web_id.to_i }
+
+ def find_campaigns_by_type(type, start = 0, limit = 25)
+ # Find campaigns by type
+ #
+ # Parameters:
+ # type (String) = One of: 'regular', 'plaintext', 'absplit', 'rss', 'inspection', 'trans', 'auto'
+ # start (Integer) = Control paging of results.
+ # limit (Integer) = Number of campaigns to return. Upper limit set at 1000.
+ #
+ # Returns:
+ # An array of campaigns.
+ #
+ call("campaigns", {:type => type}, start, limit)
end
-
- def self.find_by_id(id)
- # Find campaign by id
- all.find { |campaign| (campaign.campaign_id == id.to_s) }
+
+ def create_campaign(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
+ # Create a new draft campaign to send.
+ #
+ # Parameters:
+ # type (String) = One of "regular", "plaintext", "absplit", "rss", "trans" or "auto".
+ # options (Hash) = A hash of options for creating this campaign including:
+ # :list_id = (String) The ID of the list to send this campaign to.
+ # :subject = (String) The subject of the campaign.
+ # :from_email = (String) The email address this campaign will come from.
+ # :from_name = (String) The name that this campaign will come from.
+ # :to_email = (String) The To: name recipients will see.
+ # :template_id = (Integer) The ID of the template to use for this campaign (optional).
+ # :folder_id = (Integer) The ID of the folder to file this campaign in (optional).
+ # :tracking = (Array) What to track for this campaign (optional).
+ # :title = (String) Internal title for this campaign (optional).
+ # :authenticate = (Boolean) Set to true to authenticate campaign (optional).
+ # :analytics = (Array) Google analytics tags (optional).
+ # :auto_footer = (Boolean) Auto-generate the footer (optional)?
+ # :inline_css = (Boolean) Inline the CSS styles (optional)?
+ # :generate_text = (Boolean) Auto-generate text from HTML email (optional)?
+ # content (Hash) = The content for this campaign - use a struct with the following keys:
+ # :html (String) = The HTML content of the campaign.
+ # :text (String) = The text content of the campaign.
+ # :url (String) = A URL to pull content from. This will override other content settings.
+ # :archive (String) = To send a Base64 encoded archive file for Mailchimp to import all media from.
+ # :archive_type (String) = Only necessary for the "archive" option. Supported formats are: zip, tar.gz,
+ # tar.bz2, tar, tgz, tbz. Defaults to zip. (optional)
+ # segment_options (Hash) = Segmentation options. See the Mailchimp API documentation for more information.
+ # type_opts (Hash) = An array of options for this campaign type. See the Mailchimp API documentation for
+ # for more information.
+ #
+ # Returns:
+ # The ID for the created campaign. (String)
+ #
+ call("campaignCreate", type, options, content, segment_options, type_opts)
+ # TODO: Should we return the new campaign instead of the ID returned from the API?
end
-
- def self.find(id_or_web_id)
- # Campaign finder method
- all = self.all
- campaign = self.find_by_id(id_or_web_id.to_s).to_a + self.find_by_web_id(id_or_web_id.to_i).to_a
- return campaign.blank? ? nil : campaign.first
+
+ def folders
+ # List all the folders for a user account.
+ #
+ # Returns:
+ # An array of templates for this campaign including:
+ # folder_id (Integer) = Folder Id for the given folder, this can be used in the campaigns() function to filter on.
+ # name (String) = Name of the given folder.
+ #
+ call("campaignFolders")
end
-
- def self.create(type = 'regular', options = {}, content = {}, segment_options = {}, type_opts = {})
- # Create a new campaign
- # The options hash should be structured as follows:
+
+ def templates
+ # Retrieve all templates defined for your user account.
#
- # :list_id = (string) The ID of the list to send this campaign to.
- # :subject = (string) The subject of the campaign.
- # :from_email = (string) The email address this campaign will come from.
- # :from_name = (string) The name that this campaign will come from.
- # :to_email = (string) The To: name recipients will see.
- # :template_id = (integer) The ID of the template to use for this campaign (optional).
- # :folder_id = (integer) The ID of the folder to file this campaign in (optional).
- # :tracking = (array) What to track for this campaign (optional).
- # :title = (string) Internal title for this campaign (optional).
- # :authenticate = (boolean) Set to true to authenticate campaign (optional).
- # :analytics = (array) Google analytics tags (optional).
- # :auto_footer = (boolean) Auto-generate the footer (optional)?
- # :inline_css = (boolean) Inline the CSS styles (optional)?
- # :generate_text = (boolean) Auto-generate text from HTML email (optional)?
+ # Returns:
+ # An array of templates for this campaign including:
+ # id (Integer) = The ID of the template.
+ # name (String) = The name of the template.
+ # layout (String) = The layout of the template - "basic", "left_column", "right_column", or "postcard".
+ # sections (Array) = An associative array of editable sections in the template that can accept custom HTML
+ # when sending a campaign.
#
- # Visit http://www.mailchimp.com/api/1.2/campaigncreate.func.php for more information about creating
- # campaigns via the API.
+ call("campaignTemplates")
+ end
+
+ def campaign_abuse_reports(campaign_id, start = 0, limit = 500, since = "2000-01-01 00:00:00")
+ # Get all email addresses that complained about a given campaign.
#
- new(:id => 0).call("campaignCreate", type, options, content, segment_options, type_opts)
- ## TODO: Return the new campaign with the ID returned from the API
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = Page number to start at. Defaults to 0.
+ # limit (Integer) = Number of results to return. Defaults to 500. Upper limit is 1000.
+ # since (DateTime) = Only return email reports since this date. Must be in YYYY-MM-DD HH:II:SS format (GMT).
+ #
+ # Returns:
+ # An array of abuse reports for this list in the format:
+ #
+ call("campaignAbuseReports", campaign_id, start, limit, since)
end
-
- def self.templates
- # Get the templates for this account
- new(:id => 0).call("campaignTemplates")
+
+ def advice(campaign_id)
+ # Retrieve the text presented in our app for how a campaign performed and any advice we may have for you - best
+ # suited for display in customized reports pages. Note: some messages will contain HTML - clean tags as necessary.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # An array of advice on the campaign's performance including:
+ # msg (String) = Advice message.
+ # type (String) = One of: negative, positive, or neutral.
+ #
+ call("campaignAdvice", campaign_id)
end
-
- def add_order(order)
- # Attach Ecommerce Order Information to a campaign.
- # The order hash should be structured as follows:
+
+ def add_order(campaign_id, order)
+ # Attach Ecommerce Order Information to a Campaign.
#
- # :id = (string) the order id
- # :email_id = (string) email id of the subscriber (mc_eid query string)
- # :total = (double) Show only campaigns with this from_name.
- # :shipping = (string) *optional - the total paid for shipping fees.
- # :tax = (string) *optional - the total tax paid.
- # :store_id = (string) a unique id for the store sending the order in
- # :store_name = (string) *optional - A readable name for the store, typicaly the hostname.
- # :plugin_id = (string) the MailChimp-assigned Plugin Id. Using 1214 for the moment.
- # :items = (array) the individual line items for an order, using the following keys:
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # order (Hash) = A hash of order information including:
+ # id (String) = The order id
+ # email_id (String) = Email id of the subscriber (mc_eid query string)
+ # total (Double) = Show only campaigns with this from_name.
+ # shipping (String) = The total paid for shipping fees. (optional)
+ # tax (String) = The total tax paid. (optional)
+ # store_id (String) = A unique id for the store sending the order in
+ # store_name (String) = A readable name for the store, typicaly the hostname. (optional)
+ # plugin_id (String) = The MailChimp-assigned Plugin Id. Using 1214 for the moment.
+ # items (Array) = The individual line items for an order, using the following keys:
+ # line_num (Integer) = The line number of the item on the order. (optional)
+ # product_id (Integer) = Internal product id.
+ # product_name (String) = The name for the product_id associated with the item.
+ # category_id (Integer) = Internal id for the (main) category associated with product.
+ # category_name (String) = The category name for the category id.
+ # qty (Double) = The quantity of items ordered.
+ # cost (Double) = The cost of a single item (Ex. Not the extended cost of the line).
#
- # :line_num = (integer) *optional - line number of the item on the order
- # :product_id = (integer) internal product id
- # :product_name = (string) the name for the product_id associated with the item
- # :category_id = (integer) internal id for the (main) category associated with product
- # :category_name = (string) the category name for the category id
- # :qty = (double) the quantity of items ordered
- # :cost = (double) the cost of a single item (i.e., not the extended cost of the line)
- order = order.merge(:campaign_id => @campaign_id)
+ # Returns:
+ # True if successful, error code if not.
+ #
+ order = order.merge(:campaign_id => campaign_id)
call("campaignEcommAddOrder", order)
end
-
- def campaign_stats()
- # Get the stats of a campaign
- call("campaignStats", @campaign_id)
+ alias :ecomm_add_order :add_order
+
+ def analytics(campaign_id)
+ # Retrieve the Google Analytics data we've collected for this campaign. Note, requires Google
+ # Analytics Add-on to be installed and configured.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # An array of analytics for the passed campaign including:
+ # visits (Integer) = Number of visits.
+ # pages (Integer) = Number of page views.
+ # new_visits (Integer) = New visits recorded.
+ # bounces (Integer) = Vistors who "bounced" from your site.
+ # time_on_site (Double) =
+ # goal_conversions (Integer) = Number of goals converted.
+ # goal_value (Double) = Value of conversion in dollars.
+ # revenue (Double) = Revenue generated by campaign.
+ # transactions (Integer) = Number of transactions tracked.
+ # ecomm_conversions (Integer) = Number Ecommerce transactions tracked.
+ # goals (Array) = An array containing goal names and number of conversions.
+ #
+ call("campaignAnalytics", campaign_id)
end
-
- # Get the HTML & text content for a campaign
- # :for_archive = (boolean) default true, true returns the content as it would appear in the archive, false returns the raw HTML/text
- def campaign_content(for_archive = true)
- # Get the content of a campaign
- call("campaignContent", @campaign_id, for_archive)
+
+ def bounce_messages(campaign_id, start = 0, limit = 25, since = "2000-01-01")
+ # Retrieve the full bounce messages for the given campaign. Note that this can return very large amounts
+ # of data depending on how large the campaign was and how much cruft the bounce provider returned. Also,
+ # messages over 30 days old are subject to being removed.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 50.
+ # since (Date) = Pull only messages since this time - use YYYY-MM-DD format in GMT.
+ #
+ # Returns:
+ # An array of full bounce messages for this campaign including:
+ # date (String) = Date/time the bounce was received and processed.
+ # email (String) = The email address that bounced.
+ # message (String) = The entire bounce message received.
+ #
+ call("campaignBounceMessages", campaign_id, start, limit, since)
end
-
- def delete_campaign()
- # Delete a campaign
- call("campaignDelete", @campaign_id)
+
+ def click_details(campaign_id, url, start = 0, limit = 1000)
+ # Return the list of email addresses that clicked on a given url, and how many times they clicked.
+ # Note: Requires the AIM module to be installed.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # url (String) = The URL of the link that was clicked on.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
+ #
+ # Returns:
+ # An array of structs containing email addresses and click counts including:
+ # email (String) = Email address that opened the campaign.
+ # clicks (Integer) = Total number of times the URL was clicked on by this email address.
+ #
+ call("campaignClickDetailAIM", campaign_id, url, start, limit)
end
-
- def replicate_campaign()
- # Replicate a campaign (returns ID of new campaign)
- call("campaignReplicate", @campaign_id)
+ alias :click_detail_aim :click_details
+
+ def click_stats(campaign_id)
+ # Get an array of the urls being tracked, and their click counts for a given campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # A struct of URLs and associated statistics including:
+ # clicks (Integer) = Number of times the specific link was clicked.
+ # unique (Integer) = Number of unique people who clicked on the specific link.
+ #
+ call("campaignClickStats", campaign_id)
end
-
- def schedule_campaign(time = "#{1.day.from_now}")
- # Schedule a campaign
- ## TODO: Add support for A/B Split scheduling
- call("campaignSchedule", @campaign_id, time)
+
+ def content(campaign_id, for_archive = true)
+ # Get the content (both html and text) for a campaign either as it would appear in the campaign archive
+ # or as the raw, original content.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # for_archive (Boolean) = Controls whether we return the Archive version (true) or the Raw version (false),
+ # defaults to true.
+ #
+ # Returns:
+ # A struct containing all content for the campaign including:
+ # html (String) = The HTML content used for the campgain with merge tags intact.
+ # text (String) = The Text content used for the campgain with merge tags intact.
+ #
+ call("campaignContent", campaign_id, for_archive)
end
-
- def send_now()
- # Send a campaign
- call("campaignSendNow", @campaign_id)
+ alias :campaign_content :content
+
+ def delete(campaign_id)
+ # Delete a campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # True if successful, error code if not.
+ #
+ call("campaignDelete", campaign_id)
end
-
- # Send a test of a campaign
- def send_test(emails = {})
- call("campaignSendTest", @campaign_id, emails)
+ alias :delete_campaign :delete
+
+ def email_domain_performance(campaign_id)
+ # Get the top 5 performing email domains for this campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # An array of email domains and their associated stats including:
+ # domain (String) = Domain name or special "Other" to roll-up stats past 5 domains.
+ # total_sent (Integer) = Total Email across all domains - this will be the same in every row.
+ # emails (Integer) = Number of emails sent to this domain.
+ # bounces (Integer) = Number of bounces.
+ # opens (Integer) = Number of opens.
+ # clicks (Integer) = Number of clicks.
+ # unsubs (Integer) = Number of unsubscribes.
+ # delivered (Integer) = Number of deliveries.
+ # emails_pct (Integer) = Percentage of emails that went to this domain (whole number).
+ # bounces_pct (Integer) = Percentage of bounces from this domain (whole number).
+ # opens_pct (Integer) = Percentage of opens from this domain (whole number).
+ # clicks_pct (Integer) = Percentage of clicks from this domain (whole number).
+ # unsubs_pct (Integer) = Percentage of unsubs from this domain (whole number).
+ #
+ call("campaignEmailDomainPerformance", campaign_id)
end
-
- def update(name, value)
- # Update a campaign
- call("campaignUpdate", @campaign_id, name, value)
+ alias :email_performance :email_domain_performance
+
+ def email_stats(campaign_id, email)
+ # Given a campaign and email address, return the entire click and open history with timestamps, ordered by time.
+ # Note: Requires the AIM module to be installed.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # email (String) = The email address to check OR the email "id" returned from listMemberInfo, Webhooks, and Campaigns.
+ #
+ # Returns:
+ # An array of structs containing the actions including:
+ # action (String) = The action taken (open or click).
+ # timestamp (DateTime) = Time the action occurred.
+ # url (String) = For clicks, the URL that was clicked.
+ #
+ call("campaignEmailStatsAIM", campaign_id, email)
end
-
- def unschedule()
- # Unschedule a campaign
- call("campaignUnschedule", @campaign_id)
+ alias :email_stats_aim :email_stats
+
+ def email_stats_all(campaign_id, start = 0, limit = 100)
+ # Given a campaign and correct paging limits, return the entire click and open history with timestamps, ordered by time,
+ # for every user a campaign was delivered to.
+ # Note: Requires the AIM module to be installed.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 1000.
+ #
+ # Returns:
+ # An array of structs containing actions (opens and clicks) for each email, with timestamps including:
+ # action (String) = The action taken (open or click).
+ # timestamp (DateTime) = Time the action occurred.
+ # url (String) = For clicks, the URL that was clicked.
+ #
+ call("campaignEmailStatsAIMAll", campaign_id, start, limit)
end
+ alias :email_stats_aim_all :email_stats_all
+
+ def hard_bounces(campaign_id, start = 0, limit = 1000)
+ # Get all email addresses with Hard Bounces for a given campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
+ #
+ # Returns:
+ # An array of email addresses with Hard Bounces.
+ #
+ call("campaignHardBounces", campaign_id, start, limit)
+ end
+
+ def not_opened(campaign_id, start = 0, limit = 1000)
+ # Retrieve the list of email addresses that did not open a given campaign.
+ # Note: Requires the AIM module to be installed.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
+ #
+ # Returns:
+ # A list of email addresses that did not open a campaign.
+ #
+ call("campaignNotOpenedAIM", campaign_id, start, limit)
+ end
+ alias :not_opened_aim :not_opened
+
+ def opened(campaign_id, start = 0, limit = 1000)
+ # Retrieve the list of email addresses that opened a given campaign with how many times they opened.
+ # Note: this AIM function is free and does not actually require the AIM module to be installed.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
+ #
+ # Returns:
+ # An array of structs containing email addresses and open counts including:
+ # email (String) = Email address that opened the campaign.
+ # open_count (Integer) = Total number of times the campaign was opened by this email address.
+ #
+ call("campaignOpenedAIM", campaign_id, start, limit)
+ end
+ alias :opened_aim :opened
+
+ def orders(campaign_id, start = 0, limit = 100, since = "2001-01-01 00:00:00")
+ # Retrieve the Ecommerce Orders.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 500.
+ # since (DateTime) = Pull only messages since this time - use YYYY-MM-DD HH:II:SS format in GMT.
+ #
+ # Returns:
+ # An array of orders and their details for this campaign, including:
+ # store_id (String) = The store id generated by the plugin used to uniquely identify a store.
+ # store_name (String) = The store name collected by the plugin - often the domain name.
+ # order_id (Integer) = The internal order id the store tracked this order by.
+ # email (String) = The email address that received this campaign and is associated with this order.
+ # order_total (Double) = The order total.
+ # tax_total (Double) = The total tax for the order (if collected).
+ # ship_total (Double) = The shipping total for the order (if collected).
+ # order_date (String) = The date the order was tracked - from the store if possible, otherwise the GMT time received.
+ # lines (Array) = Containing details of the order - product, category, quantity, item cost.
+ #
+ call("campaignEcommOrders", campaign_id, start, limit, since)
+ end
+ alias :ecomm_orders :orders
+
+ def pause(campaign_id)
+ # Pause an AutoResponder orRSS campaign from sending.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # True if successful.
+ call("campaignPause", campaign_id)
+ end
+
+ def replicate(campaign_id)
+ # Replicate a campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # The ID of the newly created replicated campaign. (String)
+ #
+ call("campaignReplicate", campaign_id)
+ end
+ alias :replicate_campaign :replicate
+
+ def resume(campaign_id)
+ # Resume sending an AutoResponder or RSS campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # True if successful.
+ #
+ call("campaignResume", campaign_id)
+ end
+
+ def schedule(campaign_id, time = "#{1.day.from_now}", time_b = "")
+ # Schedule a campaign to be sent in the future.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # time (DateTime) = The time to schedule the campaign. For A/B Split "schedule" campaigns, the time
+ # for Group A - in YYYY-MM-DD HH:II:SS format in GMT.
+ # time_b (DateTime) = The time to schedule Group B of an A/B Split "schedule" campaign - in
+ # YYYY-MM-DD HH:II:SS format in GMT. (optional)
+ #
+ # Returns:
+ # True if successful.
+ #
+ call("campaignSchedule", campaign_id, time, time_b)
+ end
+ alias :schedule_campaign :schedule
+
+ def send(campaign_id)
+ # Send this campaign immediately.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign to send.
+ #
+ # Returns:
+ # True if successful.
+ call("campaignSendNow", campaign_id)
+ end
+ alias :send_now :send
+
+ def send_test(campaign_id, emails = {}, send_type = nil)
+ # Send a test of this campaign to the provided email address(es).
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # emails (Hash) = A hash of email addresses to receive the test message.
+ # send_type (String) = One of 'html', 'text' or nil (send both). Defaults to nil.
+ #
+ # Returns:
+ # True if successful.
+ #
+ call("campaignSendTest", campaign_id, emails, send_type)
+ end
+
+ def share_report(campaign_id, options = {})
+ # Get the URL to a customized VIP Report for the specified campaign and optionally send an email
+ # to someone with links to it. Note subsequent calls will overwrite anything already set for the
+ # same campign (eg, the password).
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # options (Hash) = A hash of parameters which can be used to configure the shared report, including: (optional)
+ # header_type (String) = One of "text" or "image". Defaults to 'text'. (optional)
+ # header_data (String) = If "header_type" is text, the text to display. If "header_type" is "image"
+ # a valid URL to an image file. Note that images will be resized to be no more
+ # than 500x150. Defaults to the Accounts Company Name. (optional)
+ # secure (Boolean) = Whether to require a password for the shared report. Defaults to "true". (optional)
+ # password (String) = If secure is true and a password is not included, we will generate one. It is always returned. (optional)
+ # to_email (String) = Email address to share the report with - no value means an email will not be sent. (optional)
+ # theme (Array) = An array containing either 3 or 6 character color code values for: "bg_color",
+ # "header_color", "current_tab", "current_tab_text", "normal_tab", "normal_tab_text",
+ # "hover_tab", "hover_tab_text". (optional)
+ # css_url (String) = A link to an external CSS file to be included after our default CSS
+ # (http://vip-reports.net/css/vip.css) only if loaded via the "secure_url"
+ # - max 255 characters. (optional)
+ #
+ # Returns:
+ # A struct containing details for the shared report including:
+ # title (String) = The Title of the Campaign being shared.
+ # url (String) = The URL to the shared report.
+ # secure_url (String) = The URL to the shared report, including the password (good for loading in an IFRAME).
+ # For non-secure reports, this will not be returned.
+ # password (String) = If secured, the password for the report, otherwise this field will not be returned.
+ #
+ call("campaignShareReport", campaign_id, options)
+ end
+
+ def soft_bounces(campaign_id, start = 0, limit = 1000)
+ # Get all email addresses with Soft Bounces for a given campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
+ #
+ # Returns:
+ # An array of email addresses with Soft Bounces.
+ #
+ call("campaignSoftBounces", campaign_id, start, limit)
+ end
+
+ def stats(campaign_id)
+ # Get all the relevant campaign statistics for this campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # An array of statistics for this campaign including:
+ # syntax_error (Integer) = Number of email addresses in campaign that had syntactical errors.
+ # hard_bounces (Integer) = Number of email addresses in campaign that hard bounced.
+ # soft_bounces (Integer) = Number of email addresses in campaign that soft bounced.
+ # unsubscribes (Integer) = Number of email addresses in campaign that unsubscribed.
+ # abuse_reports (Integer) = Number of email addresses in campaign that reported campaign for abuse.
+ # forwards (Integer) = Number of times email was forwarded to a friend.
+ # forwards_opens (Integer) = Number of times a forwarded email was opened.
+ # opens (Integer) = Number of times the campaign was opened.
+ # last_open (Date) = Date of the last time the email was opened.
+ # unique_opens (Integer) = Number of people who opened the campaign.
+ # clicks (Integer) = Number of times a link in the campaign was clicked.
+ # unique_clicks (Integer) = Number of unique recipient/click pairs for the campaign.
+ # last_click (Date) = Date of the last time a link in the email was clicked.
+ # users_who_clicked (Integer) = Number of unique recipients who clicked on a link in the campaign.
+ # emails_sent (Integer) = Number of email addresses campaign was sent to.
+ #
+ call("campaignStats", campaign_id)
+ end
+ alias :campaign_stats :stats
+
+ def update(campaign_id, name, value)
+ # Update just about any setting for a campaign that has not been sent.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # name (String) = The parameter name.
+ # value (Variable) = An appropriate value for the parameter.
+ #
+ # Returns:
+ # True if successful, error code if not.
+ #
+ call("campaignUpdate", campaign_id, name, value)
+ end
+
+ def unschedule(campaign_id)
+ # Unschedule a campaign that is scheduled to be sent in the future.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ #
+ # Returns:
+ # True if successful.
+ #
+ call("campaignUnschedule", campaign_id)
+ end
+
+ def unsubsribes(campaign_id, start = 0, limit = 1000)
+ # Get all unsubscribed email addresses for a given campaign.
+ #
+ # Parameters:
+ # campaign_id (String) = The ID of the campaign.
+ # start (Integer) = For large data sets, the page number to start at.
+ # limit (Integer) = For large data sets, the number of results to return. Upper limit set at 15000.
+ #
+ # Returns:
+ # An array of email addresses that unsubscribed from this campaign.
+ #
+ call("campaignUnsubscribes", campaign_id, start, limit)
+ end
+
end
-end
-
+end
\ No newline at end of file