Integrate ActiveCampaign with WHMCS

We are very excited to announce an integration with WHMCS for reseller functionality! The integration (which was developed and managed by a 3rd party) features include:

  1. Fully manage your ActiveCampaign reseller accounts directly through WHMCS.
  2. Set your own product pricing through the WHMCS control panel.
  3. cPanel users can have custom domains created for reseller accounts for true brand identity.

This integration is available now from 123Coders in the WHMCS app store. Please refer to the developer’s site for questions and support.

“New List” Webhook Available

We’ve added a webhook notification that runs whenever a new list is created for an ActiveCampaign account.

image

Since the software is mainly driven by lists, this is useful if you need to be notified whenever a new list is created. Resellers utilizing common webhooks across all of their accounts will also benefit from this because all other webhooks require at least one list relation, meaning your accounts will always have the necessary hooks set up even when new lists are created in the future.

Here is an example webhook payload that ActiveCampaign will send when a new list is created:

type: list_add
date_time: 2013-09-25 15:31:45
initiated_from: api
initiated_by: api
list[id]: 7
list[userid]: 1
list[name]: List 3 (API)
list[sender_addr1]: 123 S. Street
list[sender_addr2]:
list[sender_city]: New York
list[sender_state]: NY
list[sender_zip]: 88383
list[sender_country]: USA
list[sender_url]: http://test.com
list[sender_reminder]: You signed up on our website.
list[fulladdress]: My, Inc., 123 S. Street , New York, NY 88383, USA

With this data you could create additional webhooks that notify you of account activity for that list:

$post_data = array(
  "name" => "Test",
  "url" => "http://example.com/webhook-subscribe.php",
  "lists[7]" => "7",
  "action[subscribe]" => "subscribe",
  "init[public]" => "public",
  "init[admin]" => "admin",
  "init[api]" => "api",
  "init[system]" => "system",
);

$response = $ac->api("webhook/add", $post_data);

Another thing you could do is create custom fields for that list:

$post_data = array(
  "title" => "interest",
  "perstag" => "interest",
  "type" => "1",
  "req" => "0",
  "show_in_list" => "1",
  "p[7]" => "7",
);

$response = $ac->api("list/field_add", $post_data);

Above we create a text custom field called “interest” that is associated with the new list.

Anything that requires the new list ID can now easily be done using this webhook.

Detecting API Errors

image

Although you’ve carefully crafted your ActiveCampaign application to flow smoothly, it’s hard to know exactly when an unforeseen error will occur, which can possibly break your script and cost you time and money.

Our API attempts to provide basic information on any errors or problems that happened during a request. There’s typically two types of errors that can occur with an API request:

  1. Service level
  2. Application level

We strive for the highest uptime possible, but even we sometimes experience service disruptions that involve anything from code issues to server-level or network problems. Service level errors involve anything from network requests timing out to the service being unavailable, or even raw errors printing out. You may receive an indecipherable response, or possibly no response at all! In these cases the issue is always resolved on our end in a timely manner. Your ActiveCampaign application could attempt to detect these types of errors, but since it’s hard to predict exactly what (and how) things will be returned (if anything is returned in the first place) your only real action is to inform your users of the ActiveCampaign service disruption and to monitor updates through our available incident channels.

Application level errors are clean, graceful error messages returned from the ActiveCampaign application, and almost always indicate improper usage, such as attempting to load a contact that doesn’t exist or passing an invalid API key. Application level errors are less severe than service level errors, and will always provide a human-readable error message that can be expected in the same format. These errors usually have to be fixed by the API developer (the external application using the ActiveCampaign API), as opposed to the actual creators of the ActiveCampaign service (us).

When using the API, think of ActiveCampaign as your driver. When you make an API request, you are essentially telling ActiveCampaign to route you to your intended destination or goal (such as finding a campaign report, or adding a contact). If ActiveCampaign can route you to your destination, it’s considered a successful request. If not, it will try to tell you why (such as a roadblock that occurred during the drive).

Let’s look at an example request for a user’s details:

https://ACCOUNT.api-us1.com/admin/api.php
?api_key=fca40895042f8b0e7...dcd830e82802d85838cbc8a8b
&api_action=user_view
&api_output=json
&id=1

Assuming the above request does not experience a service level error, ActiveCampaign will attempt to look up the user with ID 1 for the associated account. If found, their data is returned along with some fixed keys that tell you a little about your request:

{
  "id": "1",
  "username": "admin",
  "first_name": "Test",
  "last_name": "Test",
  "email": "test@test.com",
  "last_login": "2013-09-12 07:13:46",
  "sourceid": "0",
  "sourceupdated": null,
  "productset": null,
  "a_now": "2013-09-12 09:39:22",
  "groups": "3",
  "result_code": 1,
  "result_message": "Success: Something is returned",
  "result_output": "json"
}

If the request was successful (meaning ActiveCampaign was able to get you to your destination), you’ll see a result_code being set to 1. The result_message will also provide a generic positive message such as "Success: Something is returned".

The HTTP response code should also be 200 in this case.

Now let’s try to load a contact using an ID that doesn’t exist:

https://ACCOUNT.api-us1.com/admin/api.php
?api_key=fca40895042f8b0e7...dcd830e82802d85838cbc8a8b
&api_action=user_view
&api_output=json
&id=999999999

If the request was not successful, result_code will be 0 and result_message will provide a description of what went wrong.

{
  "result_code": 0,
  "result_message": "Failed: Nothing is returned",
  "result_output": "json"
}

In this case the HTTP response code will be 404.

Our PHP API wrapper will also include an alternative success key (returns 1 or 0), also an error key which provides the error message if success is 0, or empty if success is 1. There will also be a http_code that returns the HTTP status code of the request (almost always 200 unless something went wrong).

{
  "result_code": 0,
  "result_message": "Failed: Nothing is returned",
  "result_output": "json",
  "success": 0,
  "error": "Failed: Nothing is returned",
  "http_code": 404
}

The important thing to take away is that both of the above requests are considered successful on the service level, but one of them failed on the application level.

Your ActiveCampaign applications can capture these errors and proceed gracefully in order to avoid disrupting the user with a broken application.

Using our PHP wrapper, your code flow could go something like this:

$response = $ac->api("user/view?id=1");

if ((int)$response->success) {
  // successful response - continue as planned.
}
else {
  // error occurred - provide the user some information.
  echo "We're sorry! Your request failed with the following error: " . $response->error;
  echo " (HTTP code " . $response->http_code . ").";
}

As always, let us know of any questions or concerns you may have!

Creating, Testing, and Scheduling Campaigns via the API

The ActiveCampaign API provides developers the ability to access functionality and data associated with their ActiveCampaign accounts, allowing possibilities like custom interfaces or white-labeled email marketing features.

One common scenario that resellers come across is being able to provide the ability to create, test, and schedule email campaigns – all via the API.

A typical flow might go something like this:

  1. Create a campaign.
  2. Preview/test the campaign.
  3. Schedule the campaign to be sent.

All of this can be done using our API, and here we’ll show you how.

We’ll be demonstrating with our PHP API wrapper to keep the code examples concise. First set up your account URL and key:

define("ACTIVECAMPAIGN_URL", "https://ACCOUNT.api-us1.com");
define("ACTIVECAMPAIGN_API_KEY", "fca40895042f...2802d85838cbc8a8b");
require_once("../activecampaign-api-php/includes/ActiveCampaign.class.php");
$ac = new ActiveCampaign(ACTIVECAMPAIGN_URL, ACTIVECAMPAIGN_API_KEY);

Let’s create the campaign. First we’ll need to add our email message:

$post_data = get_object_vars(json_decode('{
  "format": "mime",
  "subject": "TEST from API",
  "fromemail": "newsletter@test.us",
  "fromname": "Test Company",
  "htmlconstructor": "editor",
  "html": "<h1>My Test Message</h1>\n\n<p>This is a test message created via the API.</p>",
  "textconstructor": "editor",
  "text": "# My Test Message\n\nThis is a test message created via the API.",
  "p[25]": "25",
  "p[12]": "12"
}'));

$message = $ac->api("message/add", $post_data);

The result should look something like this:

stdClass Object
(
  [id] => 168
  [subject] => TEST from API
  [result_code] => 1
  [result_message] => Email Message added
  [result_output] => json
  [success] => 1
)

We’ll use the message ID from above (168) when creating the campaign:

$post_data = get_object_vars(json_decode('{
  "type": "single",
  "segmentid": "0",
  "name": "TEST from API",
  "status": "0",
  "public": "1",
  "tracklinks": "all",
  "trackreads": "1",
  "p[16]": "16",
  "m[' . $message->id . ']": "100"
}'));

$campaign = $ac->api("campaign/create", $post_data);

You’ll notice the value for “status” is 0, which means “draft.”

The API result will look like this:

stdClass Object
(
  [id] => 130
  [result_code] => 1
  [result_message] => Campaign saved
  [result_output] => json
  [success] => 1
)

We’ll need the campaign ID from above ($campaign->id) later.

If you check the admin interface you’ll see the campaign draft:

image

With the campaign in “draft” status we can now test the campaign to any email address (if the email address is an existing contact, they’ll see personalizations as well):

$test_email = $ac->api("campaign/send?email=matt@test.us&campaignid=" . $campaign->id .
 "&messageid=0&type=mime&action=test");

Once you’re ready to schedule the campaign, update the scheduled date (“sdate”) to the appropriate date/time:

$schedule = $ac->api("campaign/status?id=" . $campaign->id . "&status=1&sdate=" . 
 urlencode("2013-07-25 12:00:00"));

Make sure the “sdate” is a date in the future otherwise it will send right away.

If you need to UN-schedule the campaign in order to send more email tests, just update the status back to “draft.”

$schedule = $ac->api("campaign/status?id=" . $campaign->id . "&status=0";

Happy coding! Let us know if we can help with anything.

Working with Webhook Data

ActiveCampaign webhooks allow you to capture real-time data from your account based on activity such as new or updated contacts, campaigns sending, and more.

Screenshot of webhooks page

A good way to get started with webhooks is to see how the data appears when it hits your custom webhook URL. With PHP it’s as simple as outputting the value of the $_POST variable, which will look something like this (for the “New Subscription” webhook):

Array
(
    [type] => subscribe
    [date_time] => 2013-07-18 08:46:33
    [initiated_from] => admin
    [initiated_by] => admin
    [list] => 1
    [contact] => Array
        (
            [id] => 50984
            [email] => test1@test.com
            [first_name] => test
            [last_name] => test
            [ip] => 127.0.0.1
        )

    [subscriber] => Array
        (
            [id] => 50984
            [email] => test1@test.com
            [first_name] => test
            [last_name] => test
            [ip] => 127.0.0.1
        )

)

You can set up any public PHP script to capture this data. For example, your webhook URL could be: http://mydomain.com/webhooks.php. Your PHP script could simply log every time a “post” request hits it:

<?php

  if ($_SERVER["REQUEST_METHOD"] == "POST") {
  
    $data = print_r($_POST, 1);
    
    $fd = @fopen("/path/to/webhooks.log", "a");
    fwrite($fd, $data);
    fclose($fd);
    
  }

?>

You can even receive the webhook data behind a firewall using a tool like UltraHook or Runscope Passageway.

image

For example, your webhook URL (in ActiveCampaign) could be http://test.activecampaign.ultrahook.com (which maps to http://localhost/webhooks.php behind the scenes). UltraHook is a Ruby gem and is simple to use:

image

image

If you are not a developer and prefer to have the data captured and output for you, try a service like RequestBin. You can create public or private bins where you can visualize data coming across.

image

Once you create a bin, copy the URL as a new webhook in ActiveCampaign:

image

When a webhook fires, the data will appear in RequestBin shortly after:

image

image

Finally, if you’d like to have another service automate ActiveCampaign data for you – our Zapier, CloudWork, and itDuzzit integrations provide a way to sync data in and out of ActiveCampaign with dozens of other services.

“Subscribers” have become “Contacts”

Today we rolled out an important change to our platform. In an effort to make email marketing more understandable and closer to our clients, we decided to change the way we address your contacts. They will no longer be called “Subscribers” in the system, but “Contacts”.

A couple of things worth knowing:

  • Subscribers are from now known as Contacts
  • Opted-in subscribers will now be “confirmed contacts”
  • If a contact does not have a name we will refer to them as “Recipient” for any personalized content
  • The API has changed to reflect this update. Old API calls will continue to work as they did before.
  • Your existing Web Hooks will still work as expected.

Helping You Succeed With Our API

image

The ActiveCampaign API is a great way to interact with the software through your own interface, providing you full access to data and functionality to use in any way you can imagine.

Even though our API is well documented and we provide examples and language-specific wrappers, often times you’ll run into an issue that you can’t find a solution for and need to contact ActiveCampaign support.

We welcome all support requests so you should never feel embarrassed or silly for contacting us. In fact, a lot of times there might be an issue that we are not aware of until someone points it out. We want developers to feel comfortable using our product and API, and that includes finding answers when you need them. You can reach us through our community forum, Twitter profile, or standard support email address.

That being said, the most common things we’ll ask for when troubleshooting your API issue are as follows:

  1. The full API request URL (including all parameters)
  2. If it’s a POST request, your POST data (pretty-printed JSON if possible)
  3. The expected response/action (what do you think should happen after making this request?)
  4. The actual response received from the server, and action performed (if any)

This gives us a great idea of what you are attempting to do, and the important interface pieces that you are using. With this information we can typically narrow down the issue and provide an accurate response in a timely manner.

In general, be as detailed as possible. This ensures that 1) the support rep understands what you are attempting to do with the API, and 2) can effectively replicate the issue (in order to troubleshoot it).

In other (more rare) cases it can be much harder to isolate what the problem could be. Read on to learn why.

The challenge with API troubleshooting

The API is especially hard to troubleshoot because there is no visible interface that ActiveCampaign support can go to in order to see what the issue is. The interface is being created by you, so support can’t possibly know what is happening within your own application, script, or environment.

Consider this analogy: You’re building a large project made up of several components/materials purchased from a home improvement store, each of which have detailed instructions on how to use. You run into a problem with one component – despite the instructions it’s just not working properly within the scope of your entire project. You go back to the home improvement store and tell them the individual component is not working.

The staff at the store won’t know the entire scope of what you’re building and therefore can only test that the individual component is working unto itself. If there’s some other aspect of your project that is affecting this one component, the staff won’t know what that is.

This is similar to how an API works. An API is made up of individual instructions that, when connected to your application code, make up the functionality for an application. An API is just a set of instructions. How you execute those instructions in your application environment is entirely up to your system and skill level.

An application is also made up of different components – one of which may be the ActiveCampaign API, others could be several different company API’s. Combine all that with server processing, interface elements, client viewports and devices, and your own application logic – and you have many variables involved with how the application behaves. It’s easy to think that one component is causing a problem when it could be something else entirely.

Whereas we can’t possibly know what every application is doing, we can try to provide helpful examples and pointers to provide you with a good starting point so you can focus on other areas of your application. Combine that with a friendly, helpful support staff, and quite often the answer will reveal itself by simply having more than one person involved and listening to your situation. This is what we strive to provide, so if there’s anything we can do to improve our support or API, always let us know.

The Trouble with Imports (APC & PHP setlocale bizarreness)

As some of you may have noticed, we had a few problems with our import system last week. After several hours of investigation and a fix gratefully being applied, we wanted to share some of the details of what happened.

The Short Version

As of late last week, we noticed some problems when people were visiting the Subscriber Import page. Many times, things would work fine; sometimes, you might be shown a server error. That’s pretty confusing (and frustrating!) for anyone; the worst part was, though we could reproduce it, we couldn’t make any sense of it.

After a lot of investigation, we were able to track down the problem to some new code we added around that time. Our intention was to set the locale, useful for those with languages that may format dates a bit differently than English, but it turns out our cache system (which helps us serve pages as fast as we do) had some problems working with different locales.

You might be thinking that doesn’t make any sense. We think you’re right, and we were pretty confused; this was not the most straightforward debugging session, to say the least. But our testing confirms that code was the culprit.

If you’re worried about the locale not being set, don’t fret; we have some plans to reintroduce that feature, but in another form. From here on, your visits to the import page should be error-free.

The Long and Technical Version

As a programmer, I like bugs that make sense: the page isn’t loading, and there’s a typo? That would do it. Oh, we forgot to save this color change to the database; that’s why it’s not reflected when I refresh the page.

I don’t like bugs that make no sense, so the bug here was pretty frustrating not only for me but everyone in the office. It began happening in a third-party library for connecting to Google Contacts: one of the interfaces there (apiIO) was not defined. What an odd thing, particularly for some code we’d been using for a while; the bug nevertheless corresponded with a new feature we released, and we were pretty wary that something with that feature wasn’t interacting well with the rest of our software.

Not soon after we began looking, we had disabled APC, which is the cache system we use for PHP, and the error magically disappeared. That’s stranger, and told us right away that whatever we were looking for wasn’t going to make a lot of sense. (We were right about that in the end.) It also told us that we needed to be a bit less conventional in our thought process.

The interface in question is, of course, present in one of the code files of Google’s library. We thought perhaps the way those files are included doesn’t work well with APC, so we stopped what Google was doing (setting the system’s include path) and changed the library to include files using an absolute path. It seemed like it was working! — but then we saw server errors again. Back to the drawing board.

The apiIO interface is really the only one in the library, and we don’t tend to use that particular feature of PHP ourselves. What’s an interface but a class with empty methods, right? So we changed apiIO to actually be a class. It seemed like it was working! — but no.

Sigh. Well, APC is turned off for now, and in the meantime another error popped up in which some methods in a class our sending engine uses seemed not to exist, so we turned our attention to that (since sending is important). (It should be pointed out that this problem was only affecting one of our users — everyone else was able to send just fine.) Turns out the class has all the methods it should; if you run the PHP function to grab all of the class methods, they’re all there. But it turns out a few of them are missing from the object.

Let’s make it weirder. The methods that were missing all had a capital letter ‘I’. They should be there, but they weren’t, and by this time we were thinking this was more like magic than programming. We knew by the time the error happens that the methods are gone; we also knew, through testing, that when we start to send with this example, the methods are there. Sometime in the middle, they go away — which is weirder still.

So we did divide and conquer; pick some code that runs half-way through the error case and the beginning. Are the methods there or not? On and on we went, brute-force, until we tracked it down to — PHP’s setlocale function. Huh?

This particular user had been using our Turkish language support. Setting the locale for that turns out to have a longstanding bug in PHP, one in which our version was still susceptible. It seems that setting the locale has a somewhat illogical but nevertheless destructive impact on class methods (in particular, with the capital letter ‘I’). When we stopped setting the locale, sending was fixed.

And then we thought, hey — that error with Google’s library when APC was turned on? Didn’t that interface have a capital letter ‘I’ in it? It did! But the people getting the error weren’t using Turkish; they were, in many cases, using only English. Still, we had a theory, and it sort of made twisted sense. So we turned off setting the locale for everyone, and turned on APC, and…

It worked. The import page; everything worked. It shouldn’t have mattered, and it still doesn’t make any sense, but setting the locale made methods, classes and interfaces disappear, in particular those with a capital letter ‘I’. Thus ended one of the most bizarre debugging sessions our developers have ever had.

Tips and Tricks for Unbounce Integration, Opt-in Through API, and More

Using ActiveCampaign is easy with our free consulting and personalized help – but often some interesting tips are discovered through our support channels and user forums. Here are some recent gems.

Integrate Unbounce to multiple lists?

“It looks like I can only integrate to one list at a time? I have a second landing page that is supposed to populate to a second list.”

After suggesting to use multiple ActiveCampaign user accounts (since each user can map an Unbounce form to an ActiveCampaign list), a better idea came through:

“My other option is to do one list with a custom field for the two landing pages, and the autoresponder would send to a segment instead of the actual list.”

Thanks to Stephan for this tip!

Opt-in subscribers via API

Matt asked:

Is there a way to add a subscriber to a List via an API call (subscriber_add) and trigger the opt-in confirmation email?

Definitely! Just pass the subscription form ID through the subscriber_add API request and make sure that form has opt-in required (you can control opt-in email messages and settings for each form).

Resend a campaign via API

Courtney wondered:

I need to [stop and start a campaign via the API] as we have an on-send email that comes from an external application that need to be resent only if there are new items.

Great question! There could be various ways to achieve this, but a simple suggestion is to use the campaign_status API method to change the status on days where no new content is available. With campaign_status you can change the status to “Draft” or “Paused” in order to stop it from sending. Then when you’re ready to send it again, just update the status to 1 (“Scheduled”).

Automatically map import fields?

Debbie offered this feature suggestion:

Every month I upload an XLS that has a bunch of report information on a subscriber that I want to share with them via email. I’ve setup the fields but it is time-consuming and tricky to map each month. A feature that allows us to store a mapping list would be very helpful.

Sometimes Excel files make sense (and are cost-effective and simple) but once your subscriber details grow, you are better off using a CRM to handle the data. With our new automatic importing from external sources you don’t have worry about mapping fields and running the import manually. We handle the data syncing and field mapping from popular CRM’s, leaving you to focus on your email marketing campaigns! Check out the various CRM’s we integrate with.

Thanks to our active users!

Thanks to everyone who posts in our forums and sends us messages via our social streams – keep the questions and suggestions coming!

Introducing the ActiveCampaign Experts Corner

Experts Corner

At ActiveCampaign we take service and support very seriously. All of our hosted accounts come with free phone, email, and chat support, in addition to webinars and one on ones.

Additionally, we love developers. We actively maintain and improve our API and Zapier integrations to make working with our platform a breeze.

That said, sometimes you or your business might need someone who can go beyond even what we can do for you. Maybe you’re not a programmer but you want ActiveCampaign to tie into your company’s systems, maybe you need custom templates in mind, or maybe you want someone to help you choose a server system for our On-Site edition. With these things in mind we’re going to make it easier than ever to connect you to folks who can help do all these things and more.

Today we’ve rolled out our Experts Corner. Here you can find listings of companies that we recommend to help you with the things we cannot. We’ve hand picked a few to start off with but we’ll be adding more as time goes on. If you’re an ActiveCampaign expert and would like to be included let us know.

Cheers!