Our Email Marketing software offers a full featured, easy to use API, with dozens of functions to choose from. Many of our clients have utilized our open API to integration our Email Marketing software with their websites, external databases, and other software applications. Perhaps the most common use of the API is adding new subscribers to the system, and updating existing subscribers.

Whenever you need to add a new subscriber to your system through our API, you must follow these steps:

1. Use subscriber_view_email first, to check and see if a subscriber with the same email address already exists.
2. If subscriber_view_email returns no response, then use subscriber_add to add a new subscriber.
3. If subscriber_view_email does return a response, then save the subscriber data that it returns, and use subscriber_edit to edit the existing subscriber while also retaining their original data (lists, fields, etc).

This blog post will explain how to check to see if a subscriber exists before adding them, and how to update a pre-existing subscriber.

Use subscriber_view_email to Fetch Existing Subscriber Details

Before either adding a new subscriber, or updating an existing subscriber, you must always check to see if that subscriber exists first, and fetch their existing subscriber details. This is extremely important! If you attempt to use the subscriber_add function to add a subscriber who already exists in the system, you will receive an error message telling you that duplicate subscribers cannot be added (unless the “allow duplicate subscriptions” setting is enabled, which is uncommon). Furthermore, if you attempt to update an existing subscriber without fetching their previous information first, you run the risk of accidentally unsubscribing them to previous lists, or losing custom field data.

To check and see if a subscriber already exists in your system, you can use the subscriber_view_email function. This API function only requires that you have the email address of the subscriber, and it will essentially search your database for any record of that email address. If the email address is found, it will return the subscriber ID, name, and all custom fields and lists that the person is subscribed to.

Below is a short example of how you might call the subscriber_view_email function using PHP:

(click to enlarge)

If the email address you are searching for does not exist in your system already, you would receive a response like this:

The result_code would be 0, and the result_message would say “Nothing is returned.” If you receive a response like this from the subscriber_view_email function, then the email address you searched for does not exist in the system, and so it is safe for you to use the subscriber_add function to add them as a new subscriber.

What if the subscriber already exists?

If a subscriber with that email address already exists in your system, the same API call from above would return an array containing all of the subscriber’s data — their subscriber ID number, name, date subscribed, the list(s) they are subscribed to, and all custom field data. This image shows a portion of the array that would be returned:

In this  example, a subscriber with the email address “test@activecampaign.com” is subscribed to one list, and the list ID number for that list is 2. This can be seen by looking at the “lists” array that is returned within the main array:

(Note: The “listslist” value, also shown in the above image, will include all list ID numbers for the lists the subscriber is subscribed to, separated by a comma.)

If you scroll down a little further in your API result, you will also see that there are two custom fields — Birthday, and City. The subscriber has a Birthday value, but does not have a value for the City custom field:

In this example, we will add this subscriber to a new list (ID number 3), and we will also add a value for the City field. However, because the subscriber already exists in the system, we cannot simply use subscriber_add — we must use subscriber_edit to update them while keeping all of their original data intact (subscriptions, fields, etc).

Updating The Subscriber

Below is a short, simplified code example that can be added under the subscriber_view_email call that was already shown above. This code example will read the array that is returned from the subscriber_view_email call, determine whether or not an existing subscriber was returned, and then determine whether or not to add a new subscriber, or update an existing subscriber.

(click to enlarge)

The above code looks at the result array that was returned from the subscriber_view_email function, and preserves the subscriber’s existing list subscription data, and existing field data. It is very important to always use subscriber_view or subscriber_view_email to look up the subscriber’s existing data before using the subscriber_edit function! Otherwise, you may accidentally erase custom field data, or accidentally unsubscribe the subscriber from their previous lists.

In this example, the subscriber was already present on the list with an ID of 2, and we needed to add them to list 3. If we did not include the foreach loop starting on line 52 — which finds all lists the subscriber was already present on and adds that subscription information to the $post array as well — then the subscriber would have been removed from list 2 when the API call was executed. Similarly, if we did not also include the subscriber’s previous custom field values in the subscriber_edit call, all of their previous custom field values would have been erased.

(Note that the subscriber_add call was not shown in this example, in order to keep the example short. To see a full example of how to use the subscriber_add function, feel free visit our API documentation section of our site.)

When combining the two code examples in this article, and calling the script, you should receive the following result from the susbcriber_edit function, indicating success:

You can perform another subscriber_view_email or subscriber_view (which uses the subscriber’s ID number instead of email address to look them up) call to verify that the list subscriptions and fields were updated properly — or you can view their subscriber details within the application’s administrative interface:

Putting It All Together

If you’d like to copy and paste the full source code used in this example, with comments included, please click here to download the full example script. (However, keep in mind that it is only a simple example — login details, subscriber information, and list and custom field ID numbers will need to be changed to suit your needs!) As always, if you have any questions or comments regarding our API, please do not hesitate to contact our support department, and we would be happy to help!

We’ve improved our subscriber_edit API method to allow for updating only a portion of subscriber details, rather than supplying the entire subscriber record for each update.

The default behavior of subscriber_edit remains the same – you must build the entire subscriber record each time you save any updates associated with that record. Here are example POST parameters that you could pass:

Array (
  'id' => 1,
  'email' => 'john@doe.com',
  'first_name' => 'John',
  'last_name' => 'Doe',
  'field' => Array (
    '2,4' => 'field value',
  ),
  'p' => Array (
    '3' => 3,
    '5' => 5,
  ),
  'status' => Array (
    '3' => 1,
    '5' => 1,
  ),
)

With potentially lots of lists and custom field values, this array becomes very large when you often only want to update a single value pertaining to the subscriber.

In these cases you can include the overwrite parameter in the API request URL. Set it to 0 to turn off automatic overwrite.

Here is an example API request URL for subscriber_edit:

http://mysite.com/admin/api.php

?api_user=admin
&api_pass_h=098f6bjdsa87sadhsj4e832627b4f6
&api_action=subscriber_edit
&api_output=serialize
&overwrite=0

If you include the overwrite parameter, it can be value 1 or 0. Leaving it out defaults to 1.

Now here is your modified POST parameters:

Array (
  'id' => 1,
  'p' => Array (
    '6' => 6,
  ),
  'status' => Array (
    '6' => 1,
  ),
)

Here we are only appending this new list (ID 6) for the subscriber record, and all other details are left alone (if overwrite=0). Please keep in mind if you leave out some parameters that have dependencies (such as p and status), you might receive an error or have incomplete data being saved.

The only required parameter is id. Here are a list of dependencies:

• p and status are dependent on each other.
• first_name requires either p or first_name_list.
• last_name required either p or last_name_list.

Let us know if you have any problems with this new functionality!

With our downloaded PHP/MySQL products we include the source code (minus our license checks) allowing you (or any third party programmer) to modify the software as needed.  Change features, add features, and more.

We do not offer custom development services (as we must focus on product development) but you or any third part programmer can modify your downloaded product.

If you are not a programmer you can find a third party programmer that can make changes for you.

Where to find a programmer

• Find PHP Developers on oDesk
• Find PHP Developers on Elance.

What to look for

When posting a job add on oDesk or Elance pay attention to the following:

• Try to find people who know about or have experience with ActiveCampaign products
• Check their past reviews to make sure they are reputable
• Only entertain bids that are customized to your project (discard all the copy/paste bids you receive)
• While the lowest price is tempting be sure to factor in quality and past reviews
• Have very clear specifications of what needs to be done, how it should work, etc… Be very precise and detailed.  This will help avoid an end result that you do not like.

When using our hosted services

With our hosted service we have features within the software to customize the look and feel along with powerful API’s for external integration.

Single sign-on (“SSO” for short) allows users to authenticate to multiple applications while providing their log-in credentials only once.

With ActiveCampaign products, specifically Help Desk Hosted, you may wish to have users log-in to an external application, and have them automatically logged-in to Help Desk at the same time, while only providing their credentials once.

The user is unaware that they’ve simultaneously logged-in to multiple applications at once. The process is much more seamless, and does not require the user to re-enter their credentials.

How it works

There are two types of single sign-on: same server and external server.

“Same server” is for applications that are all residing on the same server. External is for applications on different servers. (All Help Desk hosted users must use “external server.”)

To illustrate how this works, consider a simple log-in form:

This form could be on any site, and once the user logs in, an API call is issued to your Help Desk installation:

http://youraccount.activehosted.com/api.php

Replace youraccount with your actual Help Desk hosted account, or the entire domain with your custom URL. Include these parameters with the API call, along with their corresponding values:

With the API result, you can detect if the user was successfully logged-in by making sure $result["result_code"] is set to 1.

When using external server SSO (all Help Desk hosted users), the result will look something like this (example provided as serialized):

Array (
    ...
    [token] => 7ed5jb6d44d6sc7ea413d2a599358m1b
    [result_code] => 1
    [result_message] => User Found.
    [result_output] => serialize
)

The “token” above can then be used to create the URL where the user can access the Help Desk software:

http://youraccount.activehosted.com/admin/

… continued:

main.php?_ssot=7ed5jb6d44d6sc7ea413d2a599358m1b

When accessing this URL, the user is automatically logged-in to the Help Desk software. (Any subsequent pages they visit will not contain the “_ssot” parameter, and they should only have to log-in again if they end their session.)

When using same server SSO, the result will look something like this:

Array
(
    [id] => 1
    [absid] => 1
    [username] => admin
    [prfxs] => hd_|kb_
    [hash] => udb7130b740sf23b7fc0e8e7a8689d631
    [result_code] => 1
    [result_message] => User Logged In.
    [result_output] => serialize
)

In this case a cookie is set in the browser, so you don’t need to do anything – the user should be immediately logged in.

Please see our help doc for more information, and let us know if anything is unclear.

A while back we released a feature that allows certain ActiveCampaign products to authenticate users with an external login source. This feature is currently supported in KnowledgeBuilder 3.x and SupportTrio 2.x, and will soon be included in every ActiveCampaign product.

I wanted to share how dead simple it is to get started creating a new login source using your own authentication system. We’ve included some of the more popular applications like Joomla, PHPBB3, and vBulletin, as default external login sources, which can be enabled at any time.

But you may have your own custom authentication system that you’d like to use. In order to do this, you’ll need familiarity with editing PHP files, as well as a programmatic understanding of how to use PHP to speak to your authentication system.

To get started, open up the ac_global/loginsource/ directory contained within your KnowledgeBuilder 3.x or SupportTrio 2.x installation:

You’ll see a number of individual .php files, each corresponding to a separate login source configuration. For this example, I’ve added the last file, zencart.php, as we will be creating an external login source for Zen Cart.

Set up .php file

Once you create the new .php file in this directory, edit the contents of the file with this:

<?php

$loginident = "zencart";
$loginvars = "host,dbname,user,pass";

?>

Here we specify the name of our new external login source (the $loginident variable), as well as the settings you’d like to specify when setting up this login source (the $loginvars variable).

The $loginident variable will correspond with the name you see listed under the available login sources within the application:

The $loginvars variable will correspond with the available fields that allow you to input specific information pertaining to this login source:

Once you have included those two variables in the new .php file, you should be able to access the login source directly within the application:

Enable and further configure .php file

Once you’ve saved your new login source settings, using the above application pages, you are ready to configure the .php file to speak to your authentication system.

The easiest way to set up the rest of the .php file is to copy an existing source. For example, if you open vbulletin.php, you’ll see the necessary functions that need to reside within the class:

class vBulletinLoginSource extends AC_LoginSource {
....
}

Modify names to match your new login source. For example, vBulletinLoginSource would become zencartLoginSource.

Keep the five core functions in place:

Modify these functions to extract and authenticate a given username/password combination. For more information on what each of these functions should return, please view our detailed help documentation article.

We can also set this up for you, if you provide us the database structure that houses your external user credentials, as well as any specific PHP authentication/validation functions.

Testing out your new login source

If you feel confident that you’ve modified the .php file correctly, the only thing left is to test it out!

Make sure you’ve enabled your new login source, set User Type to Public or Admin, and promote it to be the first login source the system tries to use for authentication:

Then, log out of the application, and try logging in as a user from your external system. If everything is working, you should be able to log straight in to the application as normal!

I often encounter situations where someone is dedicating their time to server specs yet overlooking some of the most basic optimization options available.  One of these basic optimization options include looking into your MySQL configuration and actually setting it to properly use the resources available on your server.

All ActiveCampaign products utilize a MySQL database.  The database is a critical part of the application and your MySQL configuration can result in your software being lightning fast or can force limited speed upon your applications.

Types of tables

Before you start to optimize MySQL you will need to know the basics.  There are two types of tables we use for our applications.  MyISAM and InnoDB.  While the differences are important – we will focus on configuration for this article.  There are different configuration options for both types of tables.  Thus the configuration you set your MySQL to may depend on the product(s) you are using.  For example, if you are only using 1-2-All you would want to optimize MySQL for InnoDB and you do not need to use as many resources for MyISAM.

Here is a list of table types for a couple of our products:

Email Marketing – Mostly InnoDB – Some MyISAM

Survey Software -  MyISAM

Knowledge Management – Mostly MyISAM – Some InnoDB

Live Chat – Mostly InnoDB – Some MyISAM

Help Desk – Mostly MyISAM – Some InnoDB

What to edit

For the basic MySQL configuration options you will want to edit the MySQL configuration file.  This file is called my.cnf or my.ini.

On a linux box you will usually find the file at: /etc/my.cnf

On a windows box you will usually find the file in your MySQL folder and the file name will be my.ini

Specific Optimization Tips

For MyISAM tables:

bulk_insert_buffer_size=32M
join_buffer_size=4M
key_buffer_size=128M
max_allowed_packet=32M
query_cache_limit=4M
read_buffer_size=1M
read_rnd_buffer_size=2M
sort_buffer_size=8M
table_cache=128
tmp_table_size=32M

These are modest values. They can be doubled or more based on the amount of RAM on your server.

For InnoDB tables:

innodb_buffer_pool_size=1G
innodb_flush_log_at_trx_commit=0

The buffer size should be 25-50% of your server’s RAM, if not more. Intensive programs benefit a lot from extra RAM.

Dig deeper

The information provided here is only scratching the surface of what you can do with MySQL configuration options.  If you have a host or system administrator they should be able to assist with such configuration changes.  For additional reading you may want to view the MySQL Performance Blog

As we are developing the new versions of both Email Marketing and Help Desk we have put a great amount of detail into usability.  The term usability is often used to simply describe the user interface.  But, the term encompasses a much larger area of software development.

A specific case in our recent development is cron management.  A number of our applications require you to setup a cron job.  In some cases you may need to setup 3 or 4 cronjobs depending on the features you are using.This is something that can be a pain for our users.  Once you setup the application you should not have to do more work when you start using a feature or purchase an add-on.  Thus we are designing our new cron management feature.  Our new cron management feature serves 2 primary purposes:

1. Ability to have a single cron – yet have different timed events.  This means that while you will only have one cron that you have to setup, our software can choose to execute different actions at different time intervals.
2. Improve the process of expanding your application and upgrading.  With this new feature in place you will not need to manually add any crons or events if you wish to use extra features, new add-ons, etc..

Those 2 purposes are the primary objectives of this feature and a great example of improving usability.   This feature will debut in Email Marketing 5 and Help Desk 3.

There are some exciting changes occurring at ActiveCampaign. We have a number of new updates in the works, KnowledgeBuilder 3.0 is about to be released into beta testing, and we are making some changes in the way you are able to customize all ActiveCampaign products.

The ability to customize ActiveCampaign products is of great concern to us. Customizing sections of the software can be crucial for the product to fit a specific use or direction. Throughout the years we have increased options such as easy branding settings, smarty templates, central language files, a selection of unencoded files, and more. And now….

All future major updates of ActiveCampaign products will be 99% unencoded.

You will be able to modify each and every part of our product. The less than 1% of files that will be encoded only takes care of installing, upgrading, and general licensing. The need for Zend or Ioncube support will remain – but it will not hinder your customization efforts.

We hope this will assist our clients who need custom solutions and are excited to start releasing the major updates of all products with the new 99% unencoded format.

P.S. The first product to be released 99% unencoded will be KnowledgeBuilder 3.0

Update: 1 Reason Not To Install Zend Optimizer

Since this article was published in May of 2008, ActiveCampaign has discontinued use of Zend Optimizer and Ioncube in favor of our own solutions to enhance the speed and security of our applications. Consequently, there is no longer any additional software that you need to install in order to use our products, and you now have full access to the source code of all of our software.

We believe our software can help your business to succeed. We believe this so much that we want  to give you the opportunity to try it out for free for 30 days and make your own decision:

• Click here for a free trial of Email Marketing
• Click here for a free trial of Survey Software
• Click here for a free trial of Help Desk
• Click here for a free trial of Knowledge Management
• Click here for a free trial of Live Chat

Original Instructions for Installing Zend Optimizer on Your Web Server

One of the ways that we increase the overall speed and security of our web-based software is by pre-compiling the PHP code. The tools that we use to do this are called Zend Optimizer and Ioncube. You actually only need one or the other in order to encode PHP scripts, and I’m not aware of any performance benefit that either one enjoys over the other. The only reason that we use both of these products is to provide maximum compatibility with all the different types of web hosts and servers that are out there. That’s why, when you visit the downloads page in our online help desk, you’re always asked which version of the software you’d like to download: Zend or Ioncube.

Most people who don’t produce or use a lot of web-based software have never heard of either of these products and get a little flustered when confronted with the question of which they should download. If you’re using a shared web hosting account or have an in-house server admin running your web server, then you have a simple one-step solution: pick up the phone, call the admin, and ask which one you can use

If you’re running your own server, it’s still very simple. The first thing to do is to find out if your server can already run Ioncube scripts, since if it can there are no additional steps for you. The way to find this out is to:

• download our test script
• unzip and upload it to your web directory
• and then open it up in a web browser

You’ll see something like this:

As you can see, my own local test server is not able to run Ioncube-encoded scripts without additional setup, because I’m using the latest version of PHP, which has broken dynamic loading. That’s no big deal, because I went ahead and installed the free Zend Optimizer with just a couple of clicks, and now I’ll show you how to do the same.

Download Zend Optimizer

If you find this part challenging, you probably shouldn’t be trying to run your own web server! 

What you need to do is to download the Zend Optimizer package onto your web server. You can get it from http://www.zend.com/en/products/guard/downloads, where you’ll need to select the appropriate package for your server. So first select the radio button labeled “Zend Optimizer” (not the one labeled “Zend Guard,”) and then you’ll find that the dropdown box becomes populated with a list of server types that Zend Optimizer is available for. The chances are very good that the type of server you are using is supported by Zend Optimizer. Remember, folks, you’re installing this on your web server, not on your own local computer (unless your web site is served from your local machine), so you want to be doing all this from the server, and to select the option that corresponds to the operating system running on the web server.

Before you are allowed to download, you’ll have to register for an account on zend.com on the next page. Once you’ve downloaded the software, all that is left is to install it on the server. The instructions for doing this will vary depending on the type of server that you use. If it is a Windows IIS server, just double-click on the installer .exe file and follow the instructions that appear on the screen. On any other type of system, including Mac OS X and any Linux or Unix variant, you’ll find that the installation package is compressed, so you first need to extract it.

On Linux or Unix servers

• Open up a terminal window or get yourself out to the command line. You can decompress the package by entering the following at the command line prompt:
  • gunzip -c <package name> | tar xf -
• Then, from inside the installer package directory that is created when the package is unzipped, type:
  • ./install.
• Now you’ll see a nice pretty graphical installation wizard that will walk you through setting up Zend Optimizer on your server.

On servers running Mac OS X

Installation on a server running OS X is a little more complicated that you might like it to be, but is still very doable. The most complicated part is basically just that you have to use the command line, which many OS X users are not very familiar with. However, you can find a very good tutorial for going through this process here [link removed since the article disappeared!).

Now put it to good use!

Once you’ve got Zend Optimizer installed on your server, you should be able to run Zend-encoded PHP scripts right away. So now just grab a copy of the Zend version of whichever ActiveCampaign software product you’ve purchased, and follow the installation instructions in the docs/install.txt file (you can also find the instructions in our knowledge base.)

If you run into any problems with the Zend Optimizer installation or if you get an error message saying that Zend Optimizer is not installed on your server, check the Zend website for troubleshooting tips.

I’m experimenting a bit with Firefox 3, since the stable release should be out soon. There are still some issues: the bookmark manager, in particular, seems to get confused when I move bookmarks around, moving them to the wrong spot; even cloning separators rather than moving them. Stress-testing some AJAX didn’t work out so well, crashing overnight.

But one bright spot is its memory usage. It’s much better than Firefox 2, and despite some of the present quirks in the 5th beta, I’m pretty happy with the program overall. The Web Developer add-on has been updated for the latest beta, and Firebug (on its own site) has a beta version that’s compatible with Firefox 3, too. (Firebug is indispensable, really, particularly when debugging AJAX.)

Now all that’s left is for my RSS reader to be updated. Well, that, and of course the crashing should stop. The crashing should always stop.