“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!

Webhooks Now Available

We are excited to announce support for webhooks which allow you to capture real-time data/requests coming from ActiveCampaign to use in other applications.

Overview

Webhooks differ from our standard API in that they are event-driven, meaning they automatically run behind the scenes whenever a particular event happens in the system (such as a campaign sending, or a subscriber’s details being updated), whereas our standard API requires that you initiate the requests to receive data.

Webhooks allow a much more fluid exchange of data between applications because they reduce the need for applications to poll for new data on a routine basis, which can be a waste of system resources. With webhooks, your applications can listen for new requests to come across, and only perform actions when a request arrives.

Here is an overview of all available webhook types for ActiveCampaign:

  • A new subscription occurs
  • An unsubscription occurs
  • A subscriber updates their details
  • A campaign starts sending
  • A campaign is opened
  • A subscriber clicks a link from a campaign
  • A subscriber forwards a campaign
  • A subscriber shares a campaign to Facebook or Twitter
  • A new bounce occurs after sending a campaign

When any of the above events happen, you can post the corresponding data to any URL. You can set up multiple URL’s (per event) and even specify how the event was initialized (by a subscriber, by an admin user, by the API, or by a system process).

Screenshot of Webhooks page in ActiveCampaign

Please see our Webhooks information page for details on each event/type and what data fields are included.

Real world use-cases

Here are some real-world examples of what you can do with ActiveCampaign webhooks:

  1. Keep subscriber records in sync with an external database or application.
  2. Capture campaign reactions (opens, link clicks, forwards, shares) to push real-time stats to another system or application.
  3. Maintain an external unsubscribe or bounce list.
  4. Know when campaigns start sending so you can track usage.

Managing webhooks

You can add, edit, and delete webhooks by going to the “Integration” tab, then clicking the “Webhooks” link on the right side:

Screenshot of where to add webhooks in ActiveCampaign

You can also manage webhooks using our API (example).

Capturing webhooks in your code

Below is an example of data being pushed to a URL after a subscriber is added, and how you can read the data using PHP:

<?php

// this is a webhook page to capture new subscriptions

if ($_SERVER["REQUEST_METHOD"] == "POST") {

  $webhook_data = $_POST;
  
  // basic validation check
  if (!isset($webhook_data["subscriber"]["id"])) exit();

  $subscriber_id = $webhook_data["subscriber"]["id"];
  $subscriber_email = $webhook_data["subscriber"]["email"];
  // ... etc

  /* 
  $webhook_data looks like:

  Array
  (
    [type] => subscribe
    [date_time] => 2013-01-02 09:28:42
    [initiated_from] => admin
    [initiated_by] => admin
    [list] => 12
    [subscriber] => Array
      (
        [id] => 12
        [email] => test@test.com
        [first_name] => Test
        [last_name] => Test
        [ip] => 127.0.0.1
        [fields] => Array
          (
            [7] => test value
            [16] => 2013-01-03
            [15] => value 1
          )
      )
  )
  */
} 

?>

Other important information

Here is some other important information regarding ActiveCampaign webhooks:

  1. Webhooks are List-based, meaning they will only fire when an event occurs for the list associated with the webhook.
  2. We hit your webhook URL(s) within a minute of the event occurring.
  3. Only data that is available during the request will be included. For example, unsubscriptions may not include the reason right away because that happens after the unsubscription does.

Let us know of any questions, and how you plan to use ActiveCampaign webhooks!

Advanced Subscription Form Integration

Subscription forms are key components for growing your subscriber lists through your web presence, so it’s important to have easy ways to embed (and customize) them on your websites and within other applications.

All subscription forms you create within the software can be quickly embedded onto your website by copying and pasting the HTML (and CSS) code. You can also embed a subscription form onto your Facebook Page in a few easy steps.

Screenshot of ActiveCampaign subscription form integration

We also have several integrations (with third-party software) that work with subscription sign-ups (either by providing forms, or capturing form data), including:

  • WordPress
  • Wufoo
  • Magento
  • Joomla
  • Unbounce

Advanced integration

If you are an advanced user looking for more flexibility, you can embed (and process) subscription forms using our API, which provides you complete control over the subscription form appearance and behavior.

This post will provide some examples using our PHP API library of embedding a subscription form onto your site, and controlling how it’s submitted (standard browser reload or Ajax), how it’s styled (include styles used when setting up the form, or remove all CSS), and what URL it posts data to. This allows you more flexibility on how your subscription form behaves on your site.

Requirements

  1. Our PHP API library
  2. jQuery (if using the Ajax option)
  3. Familiarity working with PHP code

Setup

First, obtain our sample script which will provide the code needed to interact with subscription forms through our API.

At the top of that file, input your ActiveCampaign URL and API Key. Example below:

define("ACTIVECAMPAIGN_URL", "http://localhost/onsite");
define("ACTIVECAMPAIGN_API_KEY", "a879fb51e...6f28123facc1d398");

Make sure the ActiveCampaign.class.php file include is referencing the correct relative path:

require_once("../../activecampaign-api-php/includes/ActiveCampaign.class.php");

Next, set up your subscription form embed parameters:

$form_embed_params = array(
  "id" => 1026,
  "action" => "",
  "ajax" => 1,
  "css" => 1,
);

Here is a breakdown of each:

  • id: The ID of your subscription form.
  • action: The URL that your subscription form will post data to (leave out this parameter completely if you want to post it to the default location, or set to empty string to post to the same page the script is running).
  • ajax: 0 or 1. Whether or not the form submits via standard page reload, or Ajax (requires jQuery).
  • css: 0 or 1. Whether or not to include (or remove) the default CSS that comes with each subscription form.

Finally, decide whether to perform a sync or standard add/edit:

// set to 1 to sync
$sync = 0;

A sync does not require a subscriber ID, and will automatically add or edit, depending if they exist already. Learn more.

Key code samples

Our sample script will handle everything for you (once you input the parameters and settings), but here are some more detailed examples of what’s actually happening in the script:

You can easily embed a subscription form anywhere on your site by using this example PHP code:

$form_html = $ac->api("form/embed?id=1026");
echo $form_html;

Change 1026 to your own subscription form ID.

To process the form request (if posted to the same page, where the action parameter is set to empty string):

$form_process = $ac->api("form/process");

Set “sync” to true (by default it’s false):

$form_process = $ac->api("form/process?sync=1");

To control how the form is submitted (standard page reload or Ajax), set the ajax parameter:

$form_html = $ac->api("form/embed?id=1026&ajax=1");

To remove the default CSS included with the form (sometimes it conflicts with your own site’s styles):

$form_html = $ac->api("form/embed?id=1026&css=0");

And to set your own post URL (so you can direct it to any page after submission):

$form_html = $ac->api("form/embed?id=1026&action=" . urlencode("http://mysite.com/process"));

Our sample script outputs the result message (or error) directly above the subscription form, but you can move this anywhere you want.

Screenshot of ActiveCampaign subscription form result

Please try out our sample script and let us know if you are having any trouble, or anything we can do to improve this!