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 recently released a streamlined partnership program for our hosted service. Resellers can now take advantage of an easy-to-use interface for managing their individual hosted accounts, which includes adding and removing accounts, branding each account, and updating your billing profile and available credits.

The reseller panel gives you complete control over the email marketing experience for each of your clients:

Head on over to our help section to learn more about reselling hosted accounts and re-branding the software.

Don’t forget to fill out our partner application to get started! Let us know if you have any questions.

For our typical Friday template release we’re offering a unique template design perfectly coded for businesses offering e-commerce, blogging, travel, education and services. This unique newsletter template shows off a worn-out, grungy design with bold beautiful yellow and brown colors that really stands out over the softer beige in the background. Download your copy by clicking on the template image below:

When we discussed single sign-on, we mentioned how you can have another application log you into Help Desk. From the perspective of the user logging-in, this happens in the background. They do not see the log-in screen for your ActiveCampaign product:

Rather, they log-in to an entirely different application, and upon successful authentication, they are simultaneously logged-in to your ActiveCampaign product. When they visit the ActiveCampaign product, they are not required to log-in, which provides a more seamless experience.

Login sources could be considered the opposite – instead of logging into another application, you log directly into the ActiveCampaign product with credentials from that other application.

The difference is the log-in screen presented to the user. With SSO, it’s the external application log-in screen. With login sources, it’s the ActiveCampaign product log-in screen.

They are both achieving the same result, but where you log-in is the difference.

This illustration may help visualize this concept:

Above, you’ll see that as your ActiveCampaign product sits in the middle, you either authenticate to ActiveCampaign from single sign-on, or from ActiveCampaign to a login source.

Either way, your users gain access to your ActiveCampaign product in a manner more conducive to your business needs or system flow.

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.

A new look

We have been in the middle of a lot of changes lately.  Both relating to our products and overall company direction.  Thus it was perfect timing to start rolling out our new branding.  Just yesterday we started to roll out the new site design and company branding.  This will continue (updating certain services/branding) for some time.  We expect to be fully switched over within the next couple weeks.

Add-ons are now bundled for free

Effective immediatley we are now including all add-ons for free and doing away with requiring you to buy the add-ons.

This includes:

• Spam Filter Checker (Now FREE)
• Subscriber Date Based Emails (Now FREE)
• RSS Triggered Emails (Now FREE)

All you need is a valid support/upgrade contract and to upgrade to the latest version.

Explore our APIs

Our APIs are quite powerful.  So we are now showing off that power & flexibility with our new API sections.

• Email Marketing API
• Help Desk API

You can now browse our available API calls, view information about each call, see what you should send to the API, what will be returned by the API, view code examples of real-life usage, and discuss each API call.

New unlimited email sending plans

We now offer unlimited email sending to all of our plans up to 50,000 subscribers.  Previously we limited email sending on all plans over 25,000 subscribers to be able to send 5 times their subscriber limit.

New support sections

In the past we had a central support center for all of our solutions.  We have decided to contain support information per product to make it easier for you to find solutions to your questions.

We now have a email marketing, help desk software, and survey software support section.

In addition to the new support sections we have released a whole new system to contact our support team.  It is heavily integrated with our site and uses our Help Desk API quite a bit.

Click here to view the new support sections

Manage your products and services

You can now manage all of your products & services from a single location.  Download software, renew support/upgrade contracts, view your billing history, etc..

Click here to checkout the new product/service management page

With Help Desk, it’s useful to allow users to search for content throughout the KnowledgeBase prior to submitting a ticket. This saves support staff from providing answers to repeat questions, and allowing them to focus on actual issues that need attention.

Often your KnowledgeBase will contain article attachments that have informative content contained within. For example, you may post a KnowledgeBase article that has a Microsoft Word attachment with detailed instructions on how to do something. If a user searches your Help Desk for such information, they normally would not find it amongst standard KnowledgeBase articles, since the content is contained within the attachment file itself.

With Help Desk, article file content is also searched, so articles that have attached documents will appear in search results.

The example below shows two articles returned when searching for the phrase “Microsoft Word,” which is contained within the actual file attachments, as opposed to just the KnowledgeBase article content:

Both articles have a file from a different version of Word attached:

Help Desk reads the file content when it is uploaded to the article, so it can be searched for later.

Here is a complete list of file types that Help Desk will attempt to search within:

Note: Some files can’t be read systematically, but we do our best to obtain the actual file content.

Our Help Desk hosted users benefit from minimal technical configuration – once you sign up, you are ready to use all features of the software. For example, setting up email parsing (email-to-ticket creation) is a step that downloaded users must configure before email ticket submissions work.

If you’re a hosted user, you don’t have to worry about this – you can immediately start having emails sent to email@youraccount.activehosted.com (change “youraccount” to your actual account name), which will be converted to new Help Desk tickets.

For downloaded users, I’ll shed some light on how easy it is to set up email piping on your server.

Overview

With Help Desk there are two ways to retrieve incoming emails, and convert them to tickets:

1. POP account polling
2. Piping

POP account polling involves our software routinely scanning a POP inbox for new emails. In this manner, any emails sent to the designated address will arrive to the POP inbox just like you’d expect. Then, instead of a human checking that inbox for new emails, the Help Desk software performs this check and automatically creates new tickets for any emails it finds.

This process works well, but relies on a middle-man (the actual email inbox), and is not 100% real-time (the POP account scan typically runs every 15 minutes).

While we do support and recommend POP account polling, a better way is to use email piping.

Email piping is a method of sending emails to a script instead of an inbox. As soon as the mail server receives the email, it is forwarded to a script that reads and processes the email. This concept removes the middle-man (email inbox), and any subsequent processing happens almost immediately.

When using email piping with Help Desk, tickets are created as soon as emails are received, rather than having to wait until the next time the POP account is scanned.

Setting up email piping

Email piping is configured on your web server. If you are using a web hosting company like Host Gator, you can find email piping under a section titled, “Email Forwarders.”

With Host Gator, it’s as simple as forwarding incoming email to a script, as illustrated in this screenshot:

Now, any email sent to support@yoursite.com will be forwarded to Help Desk and converted to a ticket!

Other resources

If you do not have access to an easy-to-use web panel such as Host Gator, you can still configure email piping directly on your server. Our help documentation is a good place to start.

Our previous tip for TinyMCE mentioned accessing the browser’s right-click menu instead of the native TinyMCE right-click menu.

Another useful tip is being able to perform single-line returns. By default, TinyMCE performs a double-line (paragraph) return when you hit the “Enter” key:

When writing general paragraph text, it makes sense to always start a new paragraph with a double-line return. But sometimes it’s useful to use a single-line return, especially when referencing code or anything else where you need precise placement of text.

In these cases, you can hit Shift + Enter to perform a single-line return:

Hope this helps!

Our Email Marketing and Help Desk products both utilize the HTML WYSIWYG editor, TinyMCE.

This robust text editor allows for easy HTML design and manipulation, but can often create stress for new users. The editor sometimes behaves in certain ways that contradict the user’s intention.

One particular aspect of the editor that confuses users is the native right-click contextual menu (accessed when right-clicking anywhere inside the editor):

This menu overrides the browser’s right-click contextual menu, and often stands in the way of the options available when right-clicking anywhere else on the page:

To access the browser’s right-click menu while in TinyMCE, just hold down Control while right-clicking:

Now you can easily paste text into the editor, as well as utilize the browser’s spell-checker feature.

Stay tuned for more TinyMCE tips!