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.

 
 
  • plwip
    • Matt

      Hi, the format has to be p[ LIST ID ] = STATUS. For each list you are adding the subscriber to, include a separate instance of that. The syntax p[] = STATUS may work for just one list, but it’s best to use the first format I mentioned in case there is more than one list.nnTo clarify on the “params vs. post” – params are added to the URL (when submitting via cURL), and the post variables are actual post vars.nnSorry for the confusion with that – let us know if we can help clarify anything else.

      • plwip

        Ok, I understand difference between params and post. What I don’t understand is why you put user, password and api action within post? Docs/examples states it should be in params.nnAlso where did “api_pass_h” come from? Docs mention it only for Help Desk v3.0 and nothing for Email Marketing 5.xnnLast but not least, p[LIST ID] = 0 (as unconfirmed) doesn’t work. Response says u00a0″list id = 0 does not exist” (5.2.5 Build 18)

        • Matt

          Hi, I’ve updated the blog post to clarify better between params and post. Sorry for the confusion. You should now see params separate from post. Again, params are added to the URL, and post values are posted. You can use “api_pass_h” instead of “api_pass” if you want to pass an hash instead of the plain password. It is optional. We hope to update our docs soon so they all use api_pass_h.nnIn regards to something not working, please submit a support ticket to support@activeca:disqusu00a0nmpaign.com so we can properly investigate. We may need the URL and admin password to your installation, so we can test. The current version is 5.2.5, build 24.nnThanks!

          • plwip

            Thanks for updating blog post. Now source code is less confusing :)

  • Pingback: Creating, Sending, and Analyzing a Campaign with the API()

  • Guest

    Hello,

    is it possible adding more than one subscriber with one call to the server?  I want to migrate a subscriber database to ActiveCampaing using your API and it seems ‘stupid’ having to do so many calls(one per subscriber)… I have been reading the API for a while but haven’t found anything. Is there any method to import a batch of subscribers?

    Thank you!

  • Joshua

    Could you please clarify that subscriber_view_email and other subscriber_* are replaced with contact_view_email and other contact_*?

    • Hi Joshua, yes you can use contact_ for all methods that start with subscriber_. We will eventually phase out the subscriber_ methods but not yet. Let us know of any questions.