Adding New Subscribers and Lists with the API

Adding subscribers to your lists could be considered the most important step in email marketing. After all, if you can’t get them on your list, you can’t send to them!

There are numerous ways to add subscribers to your lists. First, the public section of the software provides a simple form to input an email address, first and last name, and choose what lists to subscribe to:

The admin section also provides a way to add new subscribers, either individually through a web form, or by importing from a file, copy/paste, or external source:

If these are not enough ways to add new subscribers, you can also use our custom API!

I will walk you through how to add new subscribers using the API, and what to watch out for. The examples will be in PHP, but you can use any programming language that is able to post data via http.

Basic process:

  1. Call subscriber_view or subscriber_view_email for the email address provided.
  2. If subscriber does not exist, use subscriber_add, otherwise subscriber_edit.

Below is a very minimal example using PHP. This is not intended to be copy/pasted line for line. It is just a basic idea to get you started.

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.

$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",
);

// CHECK IF SUBSCRIBER EXISTS
$params["api_action"] = "subscriber_view_email";
$params["email"] = $email;
$exists = curl($url, $params);

if ($exists)
{
  // SUBSCRIBER IS FOUND IN THE SYSTEM - EDIT THEM

  $params["api_action"] = "subscriber_edit";

  // ARRAY OF VALUES TO BE POSTED
  $post = array(
    "email" => $exists["email"],
  );

  foreach ($exists["lists"] as $list)
  {
    // RETAIN THEIR EXISTING LISTS
    $post["p[" . $list["listid"] . "]"] = $list["listid"];

    // RETAIN THEIR EXISTING STATUSES
    $post["status[" . $list["listid"] . "]"] = $list["status"];
  }

  // ADD ANY NEW LISTS?
  $post["p[44]"] = 44; // 44 IS THE LIST ID
  $post["status[44]"] = 1; // 44 IS THE LIST ID, 1 = ACTIVE STATUS
  $post["first_name_list[44]"] = "Mike"; // (OPTIONAL) CHANGE FIRST NAME FOR ONLY THIS NEW LIST
  $post["last_name_list[44]"] = "Smith"; // (OPTIONAL) CHANGE LAST NAME FOR ONLY THIS NEW LIST

  // INCLUDE MORE POST VALUES, AS LISTED HERE:
  // http://www.activecampaign.com/api/example.php?call=subscriber_edit

  $edit = curl($url, $params, $post);
}
else
{
  // SUBSCRIBER IS NOT FOUND - ADD THEM

  $params["api_action"] = "subscriber_add";

  // ARRAY OF VALUES TO BE POSTED
  $post = array(
    "email" => $email,
    "first_name" => $first_name,
    "last_name" => $last_name,
  );

  // ADD TO LIST
  $post["p[44]"] = 44; // 44 IS THE LIST ID
  $post["status[44]"] = 1; // 44 IS THE LIST ID, 1 = ACTIVE STATUS
  $post["first_name_list[44]"] = "Mike"; // (OPTIONAL) CHANGE FIRST NAME FOR ONLY THIS NEW LIST
  $post["last_name_list[44]"] = "Smith"; // (OPTIONAL) CHANGE LAST NAME FOR ONLY THIS NEW LIST

  // INCLUDE MORE POST VALUES, AS LISTED HERE:
  // http://www.activecampaign.com/api/example.php?call=subscriber_add

  $add = curl($url, $params, $post);
}

The above assumes you already have the list ID from ActiveCampaign. If not, you can check for the list ID as well:

// SEARCH FOR LIST NAMED "List 1"
$params["api_action"] = "list_list";
$params["filters[name]"] = "List 1";
$exists = curl($url, $params);

if ($exists)
{
  // LIST(S) CONTAINING "List 1" FOUND

  foreach ($exists as $list)
  {
    // USE FIRST LIST FOUND
    $list_id = $list["id"];
    break;
  }
}
else
{
  // LIST(S) CONTAINING "List 1" NOT FOUND

  // ADD LIST TO SYSTEM
  $params["api_action"] = "list_add";
  $post["name"] = "List 1";

  // INCLUDE MORE POST VALUES, AS LISTED HERE:
  // http://www.activecampaign.com/api/example.php?call=list_add

  $add = curl($url, $params, $post);

  $list_id = $add["id"];
}

Please let us know if you have any questions!

A trial is worth a thousand words.

Get started today, no credit card required.