Creating, Sending, and Analyzing a Campaign with the API

We recently provided a quick programming example on how to add subscribers and lists using the ActiveCampaign API.

The next step is to create a campaign, send it, and analyze the results. You can also do this using the API. We’ll also show you how to dynamically display a campaign’s HTML message content on any external site.

Please note: To save space, this script assumes the existence of a custom function curl(), which should perform all related functionality for PHP cURL. Also, many of the variables used are assumed to have appropriate values. The variable name should be obvious. Also, change the $url to your own.

Create a message

First, decide how ActiveCampaign will obtain the message content for your campaign:

  1. Raw HTML that you save in the software as a new message.
  2. Fetch HTML from a URL each time the campaign sends.

Raw HTML

This is the most common way of adding your HTML message to the ActiveCampaign software. Below is an example of adding a new HTML message to the software using the API:

$url = "http://account.activehosted.com/admin/api.php";

// THESE PARAMS ARE ADDED TO THE URL, NOT POSTED
$params = array(
  "api_user" => $api_user,
  "api_pass_h" => md5($api_pass),
  "api_output" => "serialize",
);

// ADD NEW MESSAGE
$params["api_action"] = "message_add";

$post = array(
  "htmlconstructor" => "editor",
  "html" => "html <b>here</b>",
  "textconstructor" => "editor",
  "text" => "text here",
  // INCLUDE MORE POST VALUES, AS LISTED HERE:
  // http://www.activecampaign.com/api/example.php?call=message_add
);

$message = curl($url, $params, $post);
// YOU NOW HAVE $message["id"]

Fetch HTML from a URL

You can also fetch HTML from a URL each time a campaign is sent. Just change the $post array slightly:

$post = array(
  "htmlconstructor" => "external",
  "htmlfetch" => "http://mysite.com/newsletter.html",
  "htmlfetchwhen" => "send",
  "textconstructor" => "external",
  "textfetch" => "http://mysite.com/newsletter.txt",
  "textfetchwhen" => "send",
  // INCLUDE MORE POST VALUES, AS LISTED HERE:
  // http://www.activecampaign.com/api/example.php?call=message_add
);

$message = curl($url, $params, $post);
// YOU NOW HAVE $message["id"]

Above we supply the URL for the HTML version of the message, as well as the text version. This HTML/text is not imported into the software, but fetched when sending a campaign. If you change the content at those URL’s, the campaign will send exactly what you have up there.

Send a campaign

Next, it’s time to send a campaign! (Please note: it’s assumed you already have subscribers and lists created. If not, please review our blog post on that topic.)

// CREATE NEW CAMPAIGN
$params["api_action"] = "campaign_create";

$post = array(
  "type" => "single",
  "name" => "Newsletter #3",
  "sdate" => "2011-06-08 12:00:00",
  "p[44]" => 44, // 44 IS THE LIST ID
  "m[" . $message["id"] . "]" => 100, // 100 IS THE PERCENTAGE OF SUBSCRIBERS TO SEND TO
  // INCLUDE MORE POST VALUES, AS LISTED HERE:
  // http://www.activecampaign.com/api/example.php?call=campaign_create
);

$campaign = curl($url, $params, $post);
// YOU NOW HAVE $campaign["id"]

In the $post array, use the message ID that was returned from the message_add call.

Analyze campaign results

Once the campaign has sent, you can view complete reports for opens, links, forwards, bounces, etc.

// OBTAIN REPORT TOTALS
$params["api_action"] = "campaign_report_open_list";
$params["campaignid"] = $campaign["id"];

$report_opens = curl($url, $params);

Above we obtain all “opens” for the campaign we just sent. This call returns a list of each individual subscriber that opened the campaign.

You can also obtain other report data, such as bounces, forwards, link clicks, etc.

Display campaign message on external site

Lastly, we can display the campaign message itself on an external site. This is useful for sharing the campaign outside of the software.

If you don’t know the message ID (but you do have the campaign ID), you can obtain it by calling campaign_report_totals:

// OBTAIN CAMPAIGN MESSAGE ID
$params["api_action"] = "campaign_report_totals";
$params["campaignid"] = $campaign["id"];

$report_totals = curl($url, $params);
// YOU NOW HAVE $report_totals["messageid"]

Then call message_view to obtain the message HTML or text (to display on any site):

// OBTAIN CAMPAIGN MESSAGE HTML OR TEXT
$params["api_action"] = "message_view";
$params["id"] = $report_totals["messageid"];

$message = curl($url, $params);
// YOU NOW HAVE $message["html"] AND $message["text"]

Displaying $message["html"] on your site will show the HTML for the message.

Let us know if you have any questions!

A trial is worth a thousand words.
Get started today, no credit card required.

 
 
  • Joao Bernardino

    What if the campaign has more than one message, For example when we do A/B testing. A campaign id has more than one message. How do we link those?