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.

Need to find out how your customer service is going or how your client is perceiving you? Get some valuable feedback from your most loyalest customers with this beautiful blue and grey free survey email template. The bright orange button will surely grab attention as the only focus for a call-to-action. Seeing that businesses can benefit from having a Google Plus page to gain some traction in their organic ranking, we’ve decided to help you out and included a Google Plus social button at the bottom of the template; get some more followers in your Circle!

As always, head over and download your free copy in our free email template gallery here.

A couple quick updates regarding social sharing:

Link only

You can now (additionally) obtain just the link for each social sharing service, instead of just the linked-icon that we provide, so you can apply the link to any text or image in your mailing.

For example, %SOCIALSHARE-FACEBOOK% returns this icon, linked-to the Facebook post page:

If you’d rather use another image, or perhaps just a text link, you can use this alternate personalization tag:

%SOCIALSHARE-FACEBOOK-LINK%

This will return just the URL, as in this example:

http://YOURACCOUNT.activehosted.com/social.php?c=33&m=33&s=76f410bb411339c68d07a4e2ccb16c7a&ref=facebook

This immediately redirects to the Facebook post page:

http://www.facebook.com/share.php?u=http%3A%2F%2Fbit.ly%2F12345

Do this for all other social sharing personalization tags as well. (Just append -LINK to the very end.)

Google Reader removed

We’ve also removed the Google Reader/Buzz share icon as “Note in Reader” no longer works, and Buzz no longer exists. In place of this we have included Google+ sharing. You’ll find the “Share on Google+” link in the “Personalize Message” window:

The individual personalization tag for Google+ is %SOCIALSHARE-GPLUS%, and of course %SOCIALSHARE-GPLUS-LINK% will work as well.

With the arrival of winter we’ve design this pretty bright blue email template to remind us how much we’ve already missed summer. With hazy blue clouds and utility poles that give off that hot summer day feel to it, we can only wish that summer isn’t too far away.

We’ve included a bonus here; this email template has a background image that is displaying for Outlook 2007 & 2010. Here’s an old post on how to add background image in Outlook. I will go into details on how we’ve accomplished this for this specific template.

How to Display Background Image in Table Cell

Include the following code into the <html> tag of your document:

xmlns:v="urn:schemas-microsoft-com:vml"

Example:

<html xmlns:v="urn:schemas-microsoft-com:vml">

For this specific template design, we’re going to want to show the logo over the background image in a table cell — unlike our previous post where we wanted the image to show in the background of the body, we’ll want to show the background only in a certain cell. This method create another problem in Outlook; Outlook will add an unwanted 5 pixel spacing underneath this table cell. To solve this little bug, we’ll have to specify a height and width using the code below. You must remember to specify the width and the height for both the <v:image> and <v:shape>.

...
<td background="images/image_9119314.gif" style="background-image::url('images/image_9119314.gif');">

	<!--[if gte mso 9]>
	<v:image xmlns:v="urn:schemas-microsoft-com:vml" id="theImage" style='behavior: url(#default#VML); display:inline-block;position:absolute; height:109px; width:600px;top:0;left:0;border:0;z-index:1;' src="images/image_9119314.gif"/>
	<v:shape xmlns:v="urn:schemas-microsoft-com:vml" id="theText" style='behavior: url(#default#VML); display:inline-block;position:absolute; height:109px; width:600px;top:-5;left:-10;border:0;z-index:2;'>
	<div>
	<![endif]-->

		<table>
		INSERT OVERLAY TEXT OR IMAGE HERE
		</table>

	<!--[if gte mso 9]>
	</div>
	</v:shape>
	<![endif]-->

</td>
...

For this specific email template, the logo (or text) that we want to display over the background image would be contained within the table (or paragraph tags) that is wrapped around using the <v:image> and <v:shape> tags. So remember, the only thing that needs to change in the above code is your height and your width.

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:

We’re back from Thanksgiving with a Free Friday blog featuring two free email templates.

With Christmas just a few weeks away and winter is already here, we’re proud to release our first winter holiday-related template for 2011. Send your customer a thank you message or simply wish them a happy holiday with a free coupon gift illustration in this beautiful template drenched in deep winter blue featuring a cozy and warm snowman.

This orange and black template consist of a video screen capture and different orange hues to show that “pop”. There are very small details making this template a must-have with detailed patterns behind the logo with sharp colors and edges ready to impress your client.

The template also feature a repeated background image that works in all major email client including Gmail, Hotmail, Yahoo, Outlook 2007 and 2010. It’s not a pretty fix by any means but it gets the job done.

Start by including this code to the <html> tag of your document:

xmlns:v="urn:schemas-microsoft-com:vml"

Example:

<html xmlns:v="urn:schemas-microsoft-com:vml">

To get a repeated background image to display in Outlook 2007 and 2010, simply include this piece of code right after the <body> tag:

<!--[if gte mso 9]>
<v:background xmlns:v="urn:schemas-microsoft-com:vml" fill="t">
<v:fill type="tile" src="http://www/url/to/your/background/image/file/for/outlook.jpg" />
</v:background>
<![endif]-->

One issue here is that if you needed a background to repeat horizontally – as with this template – Outlook 2007 does not support the CSS background-repeat. Since we’re applying a background to the body of the email, we’ve created a seperate background image that has a big enough width and height so it shows fully in Outlook.

To have a repeated background image to show for all of the other email client, simply include this code into the body section of your template, perferablly after the <body> tag.

<style type="text/css" media="screen">
background-image:url('http://www/url/to/your/background/image/file.jpg');
background-repeat:repeat-x no-repeat;
background-position:top left;
background-color:#eeae00;
</style>

Here’s what the full code should look like:

<html xmlns:v="urn:schemas-microsoft-com:vml">
<head>
...
</head>
<body>
<style type="text/css" media="screen">
background-image:url('http://www/url/to/your/background/image/file.jpg');
background-repeat:repeat-x no-repeat;
background-position:top left;
background-color:#eeae00;
</style>

<!--[if gte mso 9]>
<v:background xmlns:v="urn:schemas-microsoft-com:vml" fill="t">
<v:fill type="tile" src="http://www/url/to/your/background/image/file/for/outlook.jpg" />
</v:background>
<![endif]-->

</body>
</html>

Unfortunately during the time of this template release, we were unable to figure out a fix for the padding issues only seen in Outlook 2007 and 2010.

Regardless, we hope you enjoy these free email templates as much as we enjoy making them.

Do you know of a fix for the padding issue in Outlook or a better work around to displaying repeated background images in Outlook? Please share with our community and post your solution in the comment.

Our Shopify and Unbounce integrations have been improved to allow the ability to map more fields into ActiveCampaign. They initially allowed only name and email address to be saved (from your Shopify checkout page, or Unbounce landing page), but now you can choose to map additional fields as well.

Just visit the External Services section of ActiveCampaign, and edit either Shopify or Unbounce. Here you can set up your mappings:

This means more subscriber data coming across for smarter list segmenting and campaign targeting. We plan to include this feature for Wufoo (and future services as well).

Today we’re releasing an email template ahead of Friday since ActiveCampaign will be close for the Thanksgiving holiday. Our email template today feature a nice clean white look with a hint of blue. This template is perfectly fitted for companies offering service, great for the every day freelance designers and content publishers looking to send out regular blog updates. As always, you can download your own copy at in our email templates gallery. For your convenience, we’ve included a Photoshop file, XML for easy import into the ActiveCampaign email console and personalization tag.

Have a happy and wonderful Thanksgiving everyone!

It’s Friday… who’s hungry? We’ve cooked up this delicious email template packed with savory goodness for your creative taste buds. Included is a XML file for convenience so you can import this template design right into your campaign. Also included is a PSD Photoshop file for those wanting to make color and button changes. Personalization tags are included for Facebook and Twitter. Head over to our email templates gallery and download a copy.