You are here

MCAPI.class.php in Mailchimp 5

File

MCAPI.class.php
View source
<?php

class MCAPI {
  var $version = "1.1";
  var $errorMessage;
  var $errorCode;

  /**
   * Cache the information on the API location on the server
   */
  var $apiUrl;

  /**
   * Default to a 300 second timeout on server calls
   */
  var $timeout = 300;

  /**
   * Default to a 8K chunk size
   */
  var $chunkSize = 8192;

  /**
   * Cache the user api_key so we only have to log in once per client instantiation
   */
  var $api_key;

  /**
   * Connect to the MailChimp API for a given list. All MCAPI calls require login before functioning
   *
   * @param string $username Your MailChimp login user name - always required
   * @param string $password Your MailChimp login password - always required
   */
  function MCAPI($username, $password) {

    //do more "caching" of the uuid for those people that keep instantiating this...
    $this->apiUrl = parse_url("http://api.mailchimp.com/" . $this->version . "/?output=php");
    if (isset($GLOBALS["mc_api_key"]) && $GLOBALS["mc_api_key"] != "") {
      $this->api_key = $GLOBALS["mc_api_key"];
    }
    else {
      $this->api_key = $this
        ->callServer("login", array(
        "username" => $username,
        "password" => $password,
      ));
      $GLOBALS["mc_api_key"] = $this->api_key;
    }
  }

  /**
   * Unschedule a campaign that is scheduled to be sent in the future
   *
   * @section Campaign  Related
   * @example xml-rpc_campaignUnschedule.php
   *
   * @param string $cid the id of the campaign to unschedule
   * @return boolean true on success
   */
  function campaignUnschedule($cid) {
    $params = array();
    $params["cid"] = $cid;
    return $this
      ->callServer("campaignUnschedule", $params);
  }

  /**
   * Schedule a campaign to be sent in the future
   *
   * @section Campaign  Related
   * @example xml-rpc_campaignSchedule.php
   *
   * @param string $cid the id of the campaign to schedule
   * @param string $schedule_time 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 <strong>GMT</strong>
   * @param string $schedule_time_b optional -the time to schedule Group B of an A/B Split "schedule" campaign - in YYYY-MM-DD HH:II:SS format in <strong>GMT</strong>
   * @return boolean true on success
   */
  function campaignSchedule($cid, $schedule_time, $schedule_time_b = NULL) {
    $params = array();
    $params["cid"] = $cid;
    $params["schedule_time"] = $schedule_time;
    $params["schedule_time_b"] = $schedule_time_b;
    return $this
      ->callServer("campaignSchedule", $params);
  }

  /**
   * Resume sending a RSS campaign
   *
   * @section Campaign  Related
   *
   * @param string $cid the id of the campaign to pause
   * @return boolean true on success
   */
  function campaignResume($cid) {
    $params = array();
    $params["cid"] = $cid;
    return $this
      ->callServer("campaignResume", $params);
  }

  /**
   * Pause a RSS campaign from sending
   *
   * @section Campaign  Related
   *
   * @param string $cid the id of the campaign to pause
   * @return boolean true on success
   */
  function campaignPause($cid) {
    $params = array();
    $params["cid"] = $cid;
    return $this
      ->callServer("campaignPause", $params);
  }

  /**
   * Send a given campaign immediately
   *
   * @section Campaign  Related
   *
   * @param string $cid the id of the campaign to resume
   * @return boolean true on success
   */
  function campaignSendNow($cid) {
    $params = array();
    $params["cid"] = $cid;
    return $this
      ->callServer("campaignSendNow", $params);
  }

  /**
   * Send a test of this campaign to the provided email address
   *
   * @section Campaign  Related
   * @example xml-rpc_campaignSendTest.php
   *
   * @param string $cid the id of the campaign to test
   * @param array $test_emails an array of email address to receive the test message
   * @param string $send_type optional by default (null) both formats are sent - "html" or "text" send just that format
   * @return boolean true on success
   */
  function campaignSendTest($cid, $test_emails = array(), $send_type = NULL) {
    $params = array();
    $params["cid"] = $cid;
    $params["test_emails"] = $test_emails;
    $params["send_type"] = $send_type;
    return $this
      ->callServer("campaignSendTest", $params);
  }

  /**
   * Retrieve all templates defined for your user account
   *
   * @section Campaign  Related
   * @example xml-rpc_campaignTemplates.php
   *
   * @return array An array of structs, one for each template (see Returned Fields for details)
   * @returnf integer id Id of the template
   * @returnf string name Name of the template
   * @returnf string layout Layout of the template - "basic", "left_column", "right_column", or "postcard"
   * @returnf array sections associative array of editable sections in the template that can accept custom HTML when sending a campaign
   */
  function campaignTemplates() {
    $params = array();
    return $this
      ->callServer("campaignTemplates", $params);
  }

  /**
  * Allows one to test their segmentation rules before creating a campaign using them
  *
  * @section Campaign  Related
  * @example xml-rpc_campaignSegmentTest.php
  *
  * @param string $list_id the list to test segmentation on - get lists using lists()
  * @param array $options with 2 keys:
          string "match" controls whether to use AND or OR when applying your options - expects "<strong>any</strong>" (for OR) or "<strong>all</strong>" (for AND)
          array "conditions" - up to 10 different criteria to apply while segmenting. Each criteria row should contain 3 keys - "<strong>field</strong>", "<strong>op</strong>", or "<strong>value</strong>" based on these definitions:

         Field = "<strong>date</strong>" : Select based on various dates we track
             Valid Op(eration): <strong>eq</strong> (is) / <strong>gt</strong> (after) / <strong>lt</strong> (before)
             Valid Values:
             string last_campaign_sent  uses the date of the last campaign sent
             string campaign_id - uses the send date of the campaign that carriers the Id submitted - see campaigns()
             string YYYY-MM-DD - ny date in the form of YYYY-MM-DD - <i>note:</i> anything that appears to start with YYYY will be treated as a date

         Field = "<strong>interests</strong>":
             Valid Op(erations): <strong>one</strong> / <strong>none</strong> / <strong>all</strong>
             Valid Values: a comma delimited of interest groups for the list - see listInterestGroups()

         Field = "<strong>aim</strong>"
             Valid Op(erations): <strong>open</strong> / <strong>noopen</strong> / <strong>click</strong> / <strong>noclick</strong>
             Valid Values: "<strong>any</strong>" or a valid AIM-enabled Campaign that has been sent

         Default Field = A Merge Var. Use <strong>Merge0-Merge15</strong> or the <strong>Custom Tag</strong> you've setup for your merge field - see listMergeVars()
             Valid Op(erations):
              <strong>eq</strong> (=)/<strong>ne</strong>(!=)/<strong>gt</strong>(>)/<strong>lt</strong>(<)/<strong>like</strong>(like '%blah%')/<strong>nlike</strong>(not like '%blah%')/<strong>starts</strong>(like 'blah%')/<strong>ends</strong>(like '%blah')
             Valid Values: any string
  * @return integer total The total number of subscribers matching your segmentation options
  */
  function campaignSegmentTest($list_id, $options) {
    $params = array();
    $params["list_id"] = $list_id;
    $params["options"] = $options;
    return $this
      ->callServer("campaignSegmentTest", $params);
  }

  /**
  * Create a new draft campaign to send
  *
  * @section Campaign  Related
  * @example mcapi_ .php
  * @example xml-rpc_campaignCreate.php
  * @example xml-rpc_campaignCreateABSplit.php
  * @example xml-rpc_campaignCreateRss.php
  *
  * @param string $type the Campaign Type to create - one of "regular", "plaintext", "absplit", "rss", "trans"
  * @param array $opts a hash of the standard options for this campaign :
         string list_id the list to send this campaign to- get lists using lists()
         string subject the subject line for your campaign message
         string from_email the From: email address for your campaign message
         string from_name the From: name for your campaign message (not an email address)
         integer template_id optional - use this template to generate the HTML content of the campaign
         array tracking optional - set which recipient actions will be tracked, as a struct of boolean values with the following keys: "opens", "html_clicks", and "text_clicks".  By default, opens and HTML clicks will be tracked.
         string title optional - an internal name to use for this campaign.  By default, the campaign subject will be used.
         boolean authenticate optional - set to true to enable SenderID, DomainKeys, and DKIM authentication, defaults to false.
         array analytics optional - if provided, use a struct with "service type" as a key and the "service tag" as a value. For Google, this should be "google"=>"your_google_analytics_key_here". Note that only "google" is currently supported - a Google Analytics tags will be added to all links in the campaign with this string attached. Others may be added in the future
         boolean inline_css optional Whether or not css should be automatically inlined when this campaign is sent, defaults to false.
         boolean generate_text optional Whether of not to auto-generate your Text content from the HTML content. Note that this will be ignored if the Text part of the content passed is not empty, defaults to false.

      * @param array $content the content for this campaign - use a struct with the following keys:
             "html" for pasted HTML content
             "text" for the plain-text version
             "url" to have us pull in content from a URL (will replace any "html" content you pass in - can be used with "generate_text" option as well).

             If you chose a template instead of pasting in your HTML content, then use "html_" followed by the template sections as keys - for example, use a key of "html_MAIN" to fill in the "MAIN" section of a template. Supported template sections include: "html_HEADER", "html_MAIN", "html_SIDECOLUMN", and "html_FOOTER"
      * @param array $segment_opts optional - if you wish to do Segmentation with this campaign this array should contain: see campaignSegmentTest(). You should test your options against campaignSegmentTest() as campaignCreate() will not allow you to set a segment that includes no members. Also, "trans" campaigns <strong>do not</strong> support segmentation.
      * @param array $type_opts optional -
         For RSS Campaigns this, array should contain:
             string url the URL to pull RSS content from - it will be verified and must exist

         For A/B Split campaigns, this array should contain:
             string split_test The values to segment based on. Currently, one of: "subject", "from_name", "schedule". NOTE, for "schedule", you will need to call campaignSchedule() separately!
             string pick_winner How the winner will be picked, one of: "opens" (by the open_rate), "clicks" (by the click rate), "manual" (you pick manually)
             integer wait_units optional the default time unit to wait before auto-selecting a winner - use "3600" for hours, "86400" for days. Defaults to 86400.
             integer wait_time optional the number of units to wait before auto-selecting a winner - defaults to 1, so if not set, a winner will be selected after 1 Day.
             integer split_size optional this is a percentage of what size the Campaign's List plus any segmentation options results in. "schedule" type forces 50%, all others default to 10%
             string from_name_a optional sort of, required when split_test is "from_name"
             string from_name_b optional sort of, required when split_test is "from_name"
             string from_email_a optional sort of, required when split_test is "from_name"
             string from_email_b optional sort of, required when split_test is "from_name"
             string subject_a optional sort of, required when split_test is "subject"
             string subject_b optional sort of, required when split_test is "subject"
  *
  * @return string the ID for the created campaign
  */
  function campaignCreate($type, $options, $content, $segment_opts = NULL, $type_opts = NULL) {
    $params = array();
    $params["type"] = $type;
    $params["options"] = $options;
    $params["content"] = $content;
    $params["segment_opts"] = $segment_opts;
    $params["type_opts"] = $type_opts;
    return $this
      ->callServer("campaignCreate", $params);
  }

  /** Update just about any setting for a campaign that has <i>not</i> been sent. See campaignCreate() for details
   *
   *  Caveats:<br/><ul>
   *        <li>If you set list_id, all segmentation options will be deleted and must be re-added.</li>
   *        <li>If you set template_id, you need to follow that up by setting it's 'content'</li>
   *        <li>If you set segment_opts, you should have tested your options against campaignSegmentTest() as campaignUpdate() will not allow you to set a segment that includes no members.</li></ul>
   * @section Campaign  Related
   * @example xml-rpc_campaignUpdate.php
   * @example xml-rpc_campaignUpdateAB.php
   *
   * @param string $cid the Campaign Id to update
   * @param string $name the parameter name ( see campaignCreate() )
   * @param mixed  $value an appropriate value for the parameter ( see campaignCreate() )
   * @return boolean true if the update succeeds, otherwise an error will be thrown
   */
  function campaignUpdate($cid, $name, $value) {
    $params = array();
    $params["cid"] = $cid;
    $params["name"] = $name;
    $params["value"] = $value;
    return $this
      ->callServer("campaignUpdate", $params);
  }

  /**
   * Get the list of campaigns and their details matching the specified filters
   *
   * @section Campaign  Related
   * @example xml-rpc_campaigns.php
   *
   * @param string $filter_id optional - only show campaigns from this list id - get lists using lists()
   * @param integer $filter_folder optional - only show campaigns from this folder id - get folders using campaignFolders()
   * @param string $filter_fromname optional - only show campaigns that have this "From Name"
   * @param string $filter_fromemail optional - only show campaigns that have this "Reply-to Email"
   * @param string $filter_title optional - only show campaigns that have this title
   * @param string $filter_subject optional - only show campaigns that have this subject
   * @param string $filter_sendtimestart optional - only show campaigns that have been sent since this date/time - format is YYYY-MM-DD HH:mm:ss (24hr)
   * @param string $filter_sendtimeend optional - only show campaigns that have been sent before this date/time - format is YYYY-MM-DD HH:mm:ss (24hr)
   * @param boolean $filter_exact optional - flag for whether to filter on exact values when filtering, or search within content for filter values
   * @param integer $start optional - control paging of campaigns, start results at this campaign #, defaults to 1st page of data  (page 0)
   * @param integer $limit optional - control paging of campaigns, number of campaigns to return with each call, defaults to 25 (max=5000)
   * @return array list of campaigns and their associated information (see Returned Fields for description)
   * @returnf string id Campaign Id (used for all other campaign functions)
   * @returnf string title Title of the campaign
   * @returnf string type The type of campaign this is (regular, plaintext, absplit, rss, etc.)
   * @returnf date create_time Creation time for the campaign
   * @returnf date send_time Send time for the campaign
   * @returnf integer emails_sent Number of emails email was sent to
   * @returnf string status Status of the given campaign (sent,scheduled,etc.)
   * @returnf string from_name From name of the given campaign
   * @returnf string from_email Reply-to email of the given campaign
   * @returnf string subject Subject of the given campaign
   * @returnf string to_email Custom "To:" email string using merge variables
   * @returnf string archive_url Archive link for the given campaign
   * @returnf boolean inline_css Whether or not the campaigns content auto-css-lined
   */
  function campaigns($filter_id = NULL, $filter_folder = NULL, $filter_fromname = NULL, $filter_fromemail = NULL, $filter_title = NULL, $filter_subject = NULL, $filter_sendtimestart = NULL, $filter_sendtimeend = NULL, $filter_exact = true, $start = 0, $limit = 25) {
    $params = array();
    $params["filter_id"] = $filter_id;
    $params["filter_folder"] = $filter_folder;
    $params["filter_fromname"] = $filter_fromname;
    $params["filter_fromemail"] = $filter_fromemail;
    $params["filter_title"] = $filter_title;
    $params["filter_subject"] = $filter_subject;
    $params["filter_sendtimestart"] = $filter_sendtimestart;
    $params["filter_sendtimeend"] = $filter_sendtimeend;
    $params["filter_exact"] = $filter_exact;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaigns", $params);
  }

  /**
   * List all the folders for a user account
   *
   * @section Campaign  Related
   * @example xml-rpc_campaignFolders.php
   *
   * @return array Array of folder structs (see Returned Fields for details)
   * @returnf integer folder_id Folder Id for the given folder, this can be used in the campaigns() function to filter on.
   * @returnf string name Name of the given folder
   */
  function campaignFolders() {
    $params = array();
    return $this
      ->callServer("campaignFolders", $params);
  }

  /**
   * Given a list and a campaign, get all the relevant campaign statistics (opens, bounces, clicks, etc.)
   *
   * @section Campaign  Stats
   * @example xml-rpc_campaignStats.php
   *
   * @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
   * @return array struct of the statistics for this campaign
   * @returnf integer syntax_errors Number of email addresses in campaign that had syntactical errors.
   * @returnf integer hard_bounces Number of email addresses in campaign that hard bounced.
   * @returnf integer soft_bounces Number of email addresses in campaign that soft bounced.
   * @returnf integer unsubscribes Number of email addresses in campaign that unsubscribed.
   * @returnf integer abuse_reports Number of email addresses in campaign that reported campaign for abuse.
   * @returnf integer forwards Number of times email was forwarded to a friend.
   * @returnf integer forwards_opens Number of times a forwarded email was opened.
   * @returnf integer opens Number of times the campaign was opened.
   * @returnf date last_open Date of the last time the email was opened.
   * @returnf integer unique_opens Number of people who opened the campaign.
   * @returnf integer clicks Number of times a link in the campaign was clicked.
   * @returnf integer unique_clicks Number of unique recipient/click pairs for the campaign.
   * @returnf date last_click Date of the last time a link in the email was clicked.
   * @returnf integer users_who_clicked Number of unique recipients who clicked on a link in the campaign.
   * @returnf integer emails_sent Number of email addresses campaign was sent to.
   */
  function campaignStats($cid) {
    $params = array();
    $params["cid"] = $cid;
    return $this
      ->callServer("campaignStats", $params);
  }

  /**
   * Get an array of the urls being tracked, and their click counts for a given campaign
   *
   * @section Campaign  Stats
   *
   * @param string $cid the campaign id to pull stats for (can be gathered using campaigns())
   * @return struct list of urls and their associated statistics
   * @returnf integer clicks Number of times the specific link was clicked
   * @returnf integer unique Number of unique people who clicked on the specific link
   */
  function campaignClickStats($cid) {
    $params = array();
    $params["cid"] = $cid;
    return $this
      ->callServer("campaignClickStats", $params);
  }

  /**
   * Get all email addresses with Hard Bounces for a given campaign
   *
   * @section Campaign  Stats
   *
   * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
   * @param integer    $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
   * @param integer    $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
   * @return array Arrays of email addresses with Hard Bounces
   */
  function campaignHardBounces($cid, $start = 0, $limit = 1000) {
    $params = array();
    $params["cid"] = $cid;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaignHardBounces", $params);
  }

  /**
   * Get all email addresses with Soft Bounces for a given campaign
   *
   * @section Campaign  Stats
   *
   * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
   * @param integer    $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
   * @param integer    $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
   * @return array Arrays of email addresses with Soft Bounces
   */
  function campaignSoftBounces($cid, $start = 0, $limit = 1000) {
    $params = array();
    $params["cid"] = $cid;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaignSoftBounces", $params);
  }

  /**
   * Get all unsubscribed email addresses for a given campaign
   *
   * @section Campaign  Stats
   *
   * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
   * @param integer    $start optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
   * @param integer    $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
   * @return array list of email addresses that unsubscribed from this campaign
   */
  function campaignUnsubscribes($cid, $start = 0, $limit = 1000) {
    $params = array();
    $params["cid"] = $cid;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaignUnsubscribes", $params);
  }

  /**
   * Get all email addresses that complained about a given campaign
   *
   * @section Campaign  Stats
   *
   * @param string $cid the campaign id to pull bounces for (can be gathered using campaigns())
   * @param integer    $start optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
   * @param integer    $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
   * @return array list of email addresses that complained (filed abuse reports) about this campaign
   */
  function campaignAbuseReports($cid, $start = 0, $limit = 1000) {
    $params = array();
    $params["cid"] = $cid;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaignAbuseReports", $params);
  }

  /**
   * Get the content (both html and text) for a campaign, exactly as it would appear in the campaign archive
   *
   * @section Campaign  Related
   *
   * @param string $cid the campaign id to get content for (can be gathered using campaigns())
   * @return struct Struct containing all content for the campaign (see Returned Fields for details
   * @returnf string html The HTML content used for the campgain with merge tags intact
   * @returnf string text The Text content used for the campgain with merge tags intact
   */
  function campaignContent($cid) {
    $params = array();
    $params["cid"] = $cid;
    return $this
      ->callServer("campaignContent", $params);
  }

  /**
   * Retrieve the list of email addresses that opened a given campaign with how many times they opened
   *
   * @section Campaign AIM
   *
   * @param string $cid the campaign id to get opens for (can be gathered using campaigns())
   * @param integer    $start optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
   * @param integer    $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
   * @return array Array of structs containing email addresses and open counts
   * @returnf string email Email address that opened the campaign
   * @returnf integer open_count Total number of times the campaign was opened by this email address
   */
  function campaignOpenedAIM($cid, $start = 0, $limit = 1000) {
    $params = array();
    $params["cid"] = $cid;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaignOpenedAIM", $params);
  }

  /**
   * Retrieve the list of email addresses that did not open a given campaign
   *
   * @section Campaign AIM
   *
   * @param string $cid the campaign id to get no opens for (can be gathered using campaigns())
   * @param integer    $start optional for large data sets, the page number to start at - defaults to 1st page of data  (page 0)
   * @param integer    $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
   * @return array list of email addresses that did not open a campaign
   */
  function campaignNotOpenedAIM($cid, $start = 0, $limit = 1000) {
    $params = array();
    $params["cid"] = $cid;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaignNotOpenedAIM", $params);
  }

  /**
   * Return the list of email addresses that clicked on a given url, and how many times they clicked
   *
   * @section Campaign AIM
   *
   * @param string $cid the campaign id to get click stats for (can be gathered using campaigns())
   * @param string $url the URL of the link that was clicked on
   * @param integer    $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
   * @param integer    $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
   * @return array Array of structs containing email addresses and click counts
   * @returnf string email Email address that opened the campaign
   * @returnf integer clicks Total number of times the URL was clicked on by this email address
   */
  function campaignClickDetailAIM($cid, $url, $start = 0, $limit = 1000) {
    $params = array();
    $params["cid"] = $cid;
    $params["url"] = $url;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaignClickDetailAIM", $params);
  }

  /**
   * Given a campaign and email address, return the entire click and open history with timestamps, ordered by time
   *
   * @section Campaign AIM
   *
   * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
   * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
   * @param integer $limit optional for large data sets, the number of results to return - defaults to 1000, upper limit set at 15000
   * @return array Array of structs containing each email and the actions (opens and clicks) that the email took, with timestamps
   * @returnf string action The action taken (open or click)
   * @returnf date timestamp Time the action occurred
   * @returnf string url For clicks, the URL that was clicked
   */
  function campaignAllEmailStatsAIM($cid, $email_address) {
    $params = array();
    $params["cid"] = $cid;
    $params["email_address"] = $email_address;
    return $this
      ->callServer("campaignAllEmailStatsAIM", $params);
  }

  /**
   * Given a campaign and email address, return the entire click and open history with timestamps, ordered by time
   *
   * @section Campaign AIM
   *
   * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
   * @param string $email_address the email address to get activity history for
   * @return array Array of structs containing actions (opens and clicks) that the email took, with timestamps
   * @returnf string action The action taken (open or click)
   * @returnf date timestamp Time the action occurred
   * @returnf string url For clicks, the URL that was clicked
   */
  function campaignEmailStatsAIMAll($cid, $start = 0, $limit = 100) {
    $params = array();
    $params["cid"] = $cid;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("campaignEmailStatsAIMAll", $params);
  }

  /**
   * BETA: Attach Ecommerce Order Information to a Campaign. Note, this is expected to be used by ecommerce package plugins that we provide.
   *
   * @section Campaign
   *
   * @param string $cid the campaign id to get stats for (can be gathered using campaigns())
   * @param array $order an array of information pertaining to the order that has completed
   * @param array $plugin_info plugin versioning
   * @return bool true if the data is saved, otherwise an error is thrown.
   */
  function campaignEcommAddOrder($order) {
    $params = array();
    $params["order"] = $order;
    return $this
      ->callServer("campaignEcommAddOrder", $params);
  }

  /**
   * Retrieve all of the lists defined for your user account
   *
   * @section List Related
   * @example xml-rpc_lists.php
   *
   * @return array list of your Lists and their associated information (see Returned Fields for description)
   * @returnf string id The list id for this list. This will be used for all other list management functions.
   * @returnf string name The name of the list.
   * @returnf date date_created The date that this list was created.
   * @returnf integer member_count The number of active members in the given list.
   */
  function lists() {
    $params = array();
    return $this
      ->callServer("lists", $params);
  }

  /**
   * Get the list of merge tags for a given list, including their name, tag, and required setting
   *
   * @section List Related
   * @example xml-rpc_listMergeVars.php
   *
   * @param string $id the list id to connect to
   * @return array list of merge tags for the list
   * @returnf string name Name of the merge field
   * @returnf char req Denotes whether the field is required (Y) or not (N)
   * @returnf string tag The merge tag that's used for forms and listSubscribe() and listUpdateMember()
   */
  function listMergeVars($id) {
    $params = array();
    $params["id"] = $id;
    return $this
      ->callServer("listMergeVars", $params);
  }

  /**
   * Add a new merge tag to a given list
   *
   * @section List Related
   * @example xml-rpc_listMergeVarAdd.php
   *
   * @param string $id the list id to connect to
   * @param string $tag The merge tag to add, e.g. FNAME
   * @param string $name The long description of the tag being added, used for user displays
   * @param boolean $req optional Whether or not to require this field to be filled in, defaults to false
   * @return bool true if the request succeeds, otherwise an error will be thrown
   */
  function listMergeVarAdd($id, $tag, $name, $req = false) {
    $params = array();
    $params["id"] = $id;
    $params["tag"] = $tag;
    $params["name"] = $name;
    $params["req"] = $req;
    return $this
      ->callServer("listMergeVarAdd", $params);
  }

  /**
   * Delete a merge tag from a given list and all it's members. Note that on large lists this method
   * may seem a bit slower than calls you typical make.
   *
   * @section List Related
   * @example xml-rpc_listMergeVarDel.php
   *
   * @param string $id the list id to connect to
   * @param string $tag The merge tag to delete
   * @return bool true if the request succeeds, otherwise an error will be thrown
   */
  function listMergeVarDel($id, $tag) {
    $params = array();
    $params["id"] = $id;
    $params["tag"] = $tag;
    return $this
      ->callServer("listMergeVarDel", $params);
  }

  /**
   * Get the list of interest groups for a given list, including the label and form information
   *
   * @section List Related
   * @example xml-rpc_listInterestGroups.php
   *
   * @param string $id the list id to connect to
   * @return struct list of interest groups for the list
   * @returnf string name Name for the Interest groups
   * @returnf string form_field Gives the type of interest group: checkbox,radio,select
   * @returnf array groups Array of the group names
   */
  function listInterestGroups($id) {
    $params = array();
    $params["id"] = $id;
    return $this
      ->callServer("listInterestGroups", $params);
  }

  /** Add a single Interest Group
   *
   * @section List Related
   * @example xml-rpc_listInterestGroupAdd.php
   *
   * @param string $id the list id to connect to
   * @param string $group_name the interest group to add
   * @return bool true if the request succeeds, otherwise an error will be thrown
   */
  function listInterestGroupAdd($id, $group_name) {
    $params = array();
    $params["id"] = $id;
    $params["group_name"] = $group_name;
    return $this
      ->callServer("listInterestGroupAdd", $params);
  }

  /** Delete a single Interest Group
   *
   * @section List Related
   * @example xml-rpc_listInterestGroupDel.php
   *
   * @param string $id the list id to connect to
   * @param string $group_name the interest group to delete
   * @return bool true if the request succeeds, otherwise an error will be thrown
   */
  function listInterestGroupDel($id, $group_name) {
    $params = array();
    $params["id"] = $id;
    $params["group_name"] = $group_name;
    return $this
      ->callServer("listInterestGroupDel", $params);
  }

  /**
  * Subscribe the provided email to a list
  *
  * @section List Related
  *
  * @example mcapi_listSubscribe.php
  * @example xml-rpc_listSubscribe.php
  *
  * @param string $id the list id to connect to
  * @param string $email_address the email address to subscribe
  * @param array $merge_vars array of merges for the email (FNAME, LNAME, etc.) (see examples below for handling "blank" arrays). Note that a merge field can only hold up to 255 characters. Also, there are 2 "special" keys:
                     string INTERESTS Set Interest Groups by passing a field named "INTERESTS" that contains a comma delimited list of Interest Groups to add.
                     string OPTINIP Set the Opt-in IP fields. <i>Abusing this may cause your account to be suspended.</i>
  * @param string $email_type optional - email type preference for the email (html or text, defaults to html)
  * @param boolean $double_optin optional - flag to control whether a double opt-in confirmation message is sent, defaults to true. <i>Abusing this may cause your account to be suspended.</i>
  * @return boolean true on success, false on failure. When using MCAPI.class.php, the value can be tested and error messages pulled from the MCAPI object (see below)
  */
  function listSubscribe($id, $email_address, $merge_vars, $email_type = 'html', $double_optin = true) {
    $params = array();
    $params["id"] = $id;
    $params["email_address"] = $email_address;
    $params["merge_vars"] = $merge_vars;
    $params["email_type"] = $email_type;
    $params["double_optin"] = $double_optin;
    return $this
      ->callServer("listSubscribe", $params);
  }

  /**
   * Unsubscribe the given email address from the list
   *
   * @section List Related
   * @example mcapi_listUnsubscribe.php
   * @example xml-rpc_listUnsubscribe.php
   *
   * @param string $id the list id to connect to
   * @param string $email_address the email address to unsubscribe
   * @param boolean $delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
   * @param boolean $send_goodbye flag to send the goodbye email to the email address, defaults to true
   * @param boolean $send_notify flag to send the unsubscribe notification email to the address defined in the list email notification settings, defaults to true
   * @return boolean true on success, false on failure. When using MCAPI.class.php, the value can be tested and error messages pulled from the MCAPI object (see below)
   */
  function listUnsubscribe($id, $email_address, $delete_member = false, $send_goodbye = true, $send_notify = true) {
    $params = array();
    $params["id"] = $id;
    $params["email_address"] = $email_address;
    $params["delete_member"] = $delete_member;
    $params["send_goodbye"] = $send_goodbye;
    $params["send_notify"] = $send_notify;
    return $this
      ->callServer("listUnsubscribe", $params);
  }

  /**
   * Edit the email address, merge fields, and interest groups for a list member
   *
   * @section List Related
   * @example mcapi_listUpdateMember.php
   *
   * @param string $id the list id to connect to
   * @param string $email_address the current email address of the member to update
   * @param array $merge_vars array of new field values to update the member with.  Use "EMAIL" to update the email address and "INTERESTS" to update the interest groups
   * @param string $email_type change the email type preference for the member ("html" or "text").  Leave blank to keep the existing preference (optional)
   * @param boolean $replace_interests flag to determine whether we replace the interest groups with the updated groups provided, or we add the provided groups to the member's interest groups (optional, defaults to true)
   * @return boolean true on success, false on failure. When using MCAPI.class.php, the value can be tested and error messages pulled from the MCAPI object
   */
  function listUpdateMember($id, $email_address, $merge_vars, $email_type = '', $replace_interests = true) {
    $params = array();
    $params["id"] = $id;
    $params["email_address"] = $email_address;
    $params["merge_vars"] = $merge_vars;
    $params["email_type"] = $email_type;
    $params["replace_interests"] = $replace_interests;
    return $this
      ->callServer("listUpdateMember", $params);
  }

  /**
   * Subscribe a batch of email addresses to a list at once
   *
   * @section List Related
   * @example xml-rpc_listBatchSubscribe.php
   *
   * @param string $id the list id to connect to
   * @param array $batch an array of structs for each address to import with two special keys: "EMAIL" for the email address, and "EMAIL_TYPE" for the email type option (html or text)
   * @param boolean $double_optin flag to control whether to send an opt-in confirmation email - defaults to true
   * @param boolean $update_existing flag to control whether to update members that are already subscribed to the list or to return an error, defaults to false (return error)
   * @param boolean $replace_interests flag to determine whether we replace the interest groups with the updated groups provided, or we add the provided groups to the member's interest groups (optional, defaults to true)
   * @return struct Array of result counts and any errors that occurred
   * @returnf integer success_count Number of email addresses that were succesfully added/updated
   * @returnf integer error_count Number of email addresses that failed during addition/updating
   * @returnf array errors Array of error structs. Each error struct will contain "code", "message", and the full struct that failed
   */
  function listBatchSubscribe($id, $batch, $double_optin = true, $update_existing = false, $replace_interests = true) {
    $params = array();
    $params["id"] = $id;
    $params["batch"] = $batch;
    $params["double_optin"] = $double_optin;
    $params["update_existing"] = $update_existing;
    $params["replace_interests"] = $replace_interests;
    return $this
      ->callServer("listBatchSubscribe", $params);
  }

  /**
   * Unsubscribe a batch of email addresses to a list
   *
   * @section List Related
   * @example mcapi_listBatchUnsubscribe.php
   *
   * @param string $id the list id to connect to
   * @param array $emails array of email addresses to unsubscribe
   * @param boolean $delete_member flag to completely delete the member from your list instead of just unsubscribing, default to false
   * @param boolean $send_goodbye flag to send the goodbye email to the email addresses, defaults to true
   * @param boolean $send_notify flag to send the unsubscribe notification email to the address defined in the list email notification settings, defaults to false
   * @return struct Array of result counts and any errors that occurred
   * @returnf integer success_count Number of email addresses that were succesfully added/updated
   * @returnf integer error_count Number of email addresses that failed during addition/updating
   * @returnf array errors Array of error structs. Each error struct will contain "code", "message", and "email"
   */
  function listBatchUnsubscribe($id, $emails, $delete_member = false, $send_goodbye = true, $send_notify = false) {
    $params = array();
    $params["id"] = $id;
    $params["emails"] = $emails;
    $params["delete_member"] = $delete_member;
    $params["send_goodbye"] = $send_goodbye;
    $params["send_notify"] = $send_notify;
    return $this
      ->callServer("listBatchUnsubscribe", $params);
  }

  /**
   * Get all of the list members for a list that are of a particular status
   *
   * @section List Related
   * @example mcapi_listMembers.php
   *
   * @param string $id the list id to connect to
   * @param string $status the status to get members for - one of(subscribed, unsubscribed, or cleaned), defaults to subscribed
   * @param integer $start optional for large data sets, the page number to start at - defaults to 1st page of data (page 0)
   * @param integer $limit optional for large data sets, the number of results to return - defaults to 100, upper limit set at 15000
   * @return array Array of list member structs (see Returned Fields for details)
   * @returnf string email Member email address
   * @returnf date timestamp timestamp of their associated status(date subscribed, unsubscribed, or cleaned)
   */
  function listMembers($id, $status = 'subscribed', $start = 0, $limit = 100) {
    $params = array();
    $params["id"] = $id;
    $params["status"] = $status;
    $params["start"] = $start;
    $params["limit"] = $limit;
    return $this
      ->callServer("listMembers", $params);
  }

  /**
   * Get all the information for a particular member of a list
   *
   * @section List Related
   * @example mcapi_listMemberInfo.php
   * @example xml-rpc_listMemberInfo.php
   *
   * @param string $id the list id to connect to
   * @param string $email_address the member email address to get information for
   * @return array array of list member info (see Returned Fields for details)
   * @returnf string email The email address associated with this record
   * @returnf string email_type The type of emails this customer asked to get: html or text
   * @returnf array merges An associative array of all the merge tags and the data for those tags for this email address
   * @returnf string status The subscription status for this email address, either subscribed, unsubscribed or cleaned
   * @returnf string ip_opt IP Address this address opted in from.
   * @returnf string ip_signup IP Address this address signed up from.
   * @returnf date timestamp The time this email address was added to the list
   */
  function listMemberInfo($id, $email_address) {
    $params = array();
    $params["id"] = $id;
    $params["email_address"] = $email_address;
    return $this
      ->callServer("listMemberInfo", $params);
  }

  /**
   * Retrieve your User Unique Id and your Affiliate link to display/use for <a href="/monkeyrewards/" target="_blank">Monkey Rewards</a>. While
   * we don't use the User Id for any API functions, it can be useful if building up URL strings for things such as the profile editor and sub/unsub links.
   * @section Helper
   *
   * @return array containing your Affilliate Id and full link.
   * @returnf string user_id Your User Unique Id.
   * @returnf string url Your Monkey Rewards link for our Affiliate program
   */
  function getAffiliateInfo() {
    $params = array();
    return $this
      ->callServer("getAffiliateInfo", $params);
  }

  /**
   * Have HTML content auto-converted to a text-only format. You can send: plain HTML, an array of Template content, an existing Campaign Id, or an existing Template Id. Note that this will <b>not</b> save anything to or update any of your lists, campaigns, or templates.
   *
   * @section Helper
   * @example xml-rpc_generateText.php
   *
   * @param string $type The type of content to parse. Must be one of: "html", "template", "url", "cid" (Campaign Id), or "tid" (Template Id)
   * @param mixed $content The content to use. For "html" expects  a single string value, "template" expects an array like you send to campaignCreate, "url" expects a valid & public URL to pull from, "cid" expects a valid Campaign Id, and "tid" expects a valid Template Id on your account.
   * @return string the content pass in converted to text.
   */
  function generateText($type, $content) {
    $params = array();
    $params["type"] = $type;
    $params["content"] = $content;
    return $this
      ->callServer("generateText", $params);
  }

  /**
   * Send your HTML content to have the CSS inlined and optionally remove the original styles.
   *
   * @section Helper
   * @example xml-rpc_inlineCss.php
   *
   * @param string $html Your HTML content
   * @param bool $strip_css optional Whether you want the CSS &lt;style&gt; tags stripped from the returned document. Defaults to false.
   * @return string Your HTML content with all CSS inlined, just like if we sent it.
   */
  function inlineCss($html, $strip_css = false) {
    $params = array();
    $params["html"] = $html;
    $params["strip_css"] = $strip_css;
    return $this
      ->callServer("inlineCss", $params);
  }

  /**
   * Retrieve a list of all MailChimp API Keys for this User
   *
   * @section Security Related
   * @example xml-rpc_apikeyAdd.php
   *
   * @param string $username Your MailChimp user name
   * @param string $password Your MailChimp password
   * @param boolean $expired optional - whether or not to include expired keys, defaults to false
   * @return array an array of API keys including:
   * @returnf string apikey The api key that can be used
   * @returnf string created_at The date the key was created
   * @returnf string expired_at The date the key was expired
   */
  function apikeys($username, $password, $expired = false) {
    $params = array();
    $params["username"] = $username;
    $params["password"] = $password;
    $params["expired"] = $expired;
    return $this
      ->callServer("apikeys", $params);
  }

  /**
   * Add an API Key to your account. We will generate a new key for you and return it.
   *
   * @section Security Related
   * @example xml-rpc_apikeyAdd.php
   *
   * @param string $username Your MailChimp user name
   * @param string $password Your MailChimp password
   * @return string a new API Key that can be immediately used.
   */
  function apikeyAdd($username, $password) {
    $params = array();
    $params["username"] = $username;
    $params["password"] = $password;
    return $this
      ->callServer("apikeyAdd", $params);
  }

  /**
   * Expire a Specific API Key. Note that if you expire all of your keys, a new, valid one will be created and returned
   * next time you call login(). If you are trying to shut off access to your account for an old developer, change your
   * MailChimp password, then expire all of the keys they had access to. Note that this takes effect immediately, so make
   * sure you replace the keys in any working application before expiring them! Consider yourself warned...
   *
   * @section Security Related
   * @example xml-rpc_apikeyExpire.php
   *
   * @param string $username Your MailChimp user name
   * @param string $password Your MailChimp password
   * @return boolean true if it worked, otherwise an error is thrown.
   */
  function apikeyExpire($username, $password) {
    $params = array();
    $params["username"] = $username;
    $params["password"] = $password;
    return $this
      ->callServer("apikeyExpire", $params);
  }

  /**
   * "Ping" the MailChimp API - a simple method you can call that will return a constant value as long as everything is good. Note
   * than unlike most all of our methods, we don't throw an Exception if we are having issues. You will simply receive a different
   * string back that will explain our view on what is going on.
   *
   * @section Helper
   * @example xml-rpc_ping.php
   *
   * @return string returns "Everything's Chimpy!" if everything is chimpy, otherwise returns an error message
   */
  function ping() {
    $params = array();
    return $this
      ->callServer("ping", $params);
  }

  /**
   * Internal function - proxy method for certain XML-RPC calls | DO NOT CALL
   * @param mixed Method to call, with any parameters to pass along
   * @return mixed the result of the call
   */
  function callMethod() {
    $params = array();
    return $this
      ->callServer("callMethod", $params);
  }

  /**
   * Actually connect to the server and call the requested methods, parsing the result
   * You should never have to call this function manually
   */
  function callServer($method, $params) {

    //Always include the user id if we're not loggin in
    if ($method != "login") {
      $params["apikey"] = $this->api_key;
    }
    $post_vars = $this
      ->httpBuildQuery($params);
    $payload = "POST " . $this->apiUrl["path"] . "?" . $this->apiUrl["query"] . "&method=" . $method . " HTTP/1.0\r\n";
    $payload .= "Host: " . $this->apiUrl["host"] . "\r\n";
    $payload .= "User-Agent: MCAPI/" . $this->version . "\r\n";
    $payload .= "Content-type: application/x-www-form-urlencoded\r\n";
    $payload .= "Content-length: " . strlen($post_vars) . "\r\n";
    $payload .= "Connection: close \r\n\r\n";
    $payload .= $post_vars;
    ob_start();
    $sock = fsockopen($this->apiUrl["host"], 80, $errno, $errstr, $this->timeout);
    if (!$sock) {
      $this->errorMessage = "Could not connect (ERR {$errno}: {$errstr})";
      $this->errorCode = "-99";
      ob_end_clean();
      return false;
    }
    $response = "";
    fwrite($sock, $payload);
    while (!feof($sock)) {
      $response .= fread($sock, $this->chunkSize);
    }
    fclose($sock);
    ob_end_clean();
    list($throw, $response) = explode("\r\n\r\n", $response, 2);
    if (ini_get("magic_quotes_runtime")) {
      $response = stripslashes($response);
    }
    $serial = unserialize($response);
    if ($response && $serial === false) {
      $response = array(
        "error" => "Bad Response.  Got This: " . $response,
        "code" => "-99",
      );
    }
    else {
      $response = $serial;
    }
    if (is_array($response) && isset($response["error"])) {
      $this->errorMessage = $response["error"];
      $this->errorCode = $response["code"];
      return false;
    }
    return $response;
  }

  /**
   * Re-implement http_build_query for systems that do not already have it
   */
  function httpBuildQuery($params, $key = null) {
    $ret = array();
    foreach ((array) $params as $name => $val) {
      $name = urlencode($name);
      if ($key !== null) {
        $name = $key . "[" . $name . "]";
      }
      if (is_array($val) || is_object($val)) {
        $ret[] = $this
          ->httpBuildQuery($val, $name);
      }
      elseif ($val !== null) {
        $ret[] = $name . "=" . urlencode($val);
      }
    }
    return implode("&", $ret);
  }

}

Classes

Namesort descending Description
MCAPI