Campaign Monitor (and MailBuild) Integration

We at FoxyCart really like Campaign Monitor. It's built for web-designers and developers, just like FoxyCart, and it's very easy to set up, use, and love.

Campaign Monitor is designed from the ground up to be branded and resold to your clients, and it has a very complete API that can be used to completely replace their web interface; check out the samples and documentation here: http://www.campaignmonitor.com/api/samples-and-wrappers/

The integration below only uses a modest subset of the capabilities of the Campaign Monitor API – we're only going to use it to add customers who order through our FoxyCart store to a Campaign Monitor mailing list. We want the customer's permission before we send them our latest newsletter, too, so we're going to add a checkbox that lets them do that.

• PHP4 or later, built with the SimpleXML extension (you've probably got it).
• A Campaign Monitor account.

This integration automatically adds your FoxyCart customers to a Campaign Monitor list of your choice. Let's get started:

1. Download the latest .zip of the foxy2cm repository on GitHub. Alternatively, you may use git, if that's how you roll. The goods are in fc-campaignmonitor.php Included for good measure are the PHP Campaign Monitor API interface, a PHP4-compatible XML parser, a RC4 decryption library, and a test harness.
2. Upload the contents of foxy2cm.zip to your server; you should have 6(!) PHP files.
3. Open fc-campaignmonitor.php in your favorite text editor.
4. Get a cup of coffee (or your favorite beverage). Don't worry, this will be quick and easy.
5. Set up or Log In to your Campaign Monitor account. If you're setting up a new account, follow their instructions and set up a new client, campaign, and subscriber list.
6. All set? Proceed to the next section.

Well, the Keys to your Campaign Monitor list, at least. You need three of them: your API key, your Client ID, and your List ID. How do you find those, and what do you do once you find them? Follow along.

First of all, you're going to edit the configuration section of fc-campaignmonitor.php; handily, it's at the top of the file:

...
///// BEGIN Configuration //////
 
$Campaign_Monitor_API_Key = "YOURAPIKEYHERE"; // Replace YOURAPIKEYHERE with your Campaign Monitor API Key.
                                             // How to find that?  Glad you asked, go here:
                                             // http://www.campaignmonitor.com/api/required/ to find this and the next few keys.
 
$Campaign_Monitor_Client_ID = "CLIENTID";    // Replace CLIENTID with the Campaign Monitor Client ID.  See the above link.
$Campaign_Monitor_List_ID = "LISTID";        // Replace LISTID with the Campaign Monitor List ID.  See the above link.
 
...
 
////// END Configuration ///////
...

1. All set up? From Campaign Monitor, click the “Account Settings” link up in the top left of the page.
   1. If you've used the Campaign Monitor API before, then you'll have a section called “API Key (for developers)” on this page. If you don't see that, click the “Generate your API key” link in the right-hand column and follow the instructions.
      1. Note well: if you set up Campaign Monitor back before they rolled out the new API, you'll have a link at the bottom of the “API Key” section that says, “generate new API key.” You need to click that link in order to use this integration, but keep in mind that doing so will break any currently-running integration that you have! If you're stuck on the old version of the API, don't panic; just look in this page's revision history for our integration that works with their older API.
   2. Copy your API key, (it's a big hexadecimal number, like “abcdef0123456789abcdef0123456789”)
   3. Paste it into above-mentioned configuration section of your fc-campaignmonitor.php replacing YOURAPIKEYHERE with your API key and leaving the enclosing quotes in place.
2. The next key is your Client ID. Campaign Monitor requires you to have at least one client, even if that client is just your company.
   1. Click the client's name from the main Campaign Monitor screen, in the “Clients you're sending for” section at the left.
   2. Click the “Client Settings” tab on the far-right end of the tab bar at the top of the screen.
   3. In the “Client Details” section, copy the “API Client ID” and paste it into the above configuration block in your fc-campaignmonitor.php, replacing CLIENTID with your Client ID.
3. The last key that you need is your List ID. You're almost done!
   1. Click the “Manage Subscribers” tab in the tab bar at the top of the page.
   2. Click the name of list that you want your FoxyCart customers added to, then click the “edit list name/type” link that's directly under the name of the list on the new page that comes up.
   3. Copy the List ID from the “API Subscriber List ID” section of this page, and paste it into the configuration section of fc-campaignmonitor.php, replacing LISTID with the List ID.
4. Got those keys filled in? Save fc-campaignmonitor.php and go onto the next section.

OK, great, you've found and retrieved your API keys from Campaign Monitor. This last section concerns the rest of the configuration section in fc-campaignmonitor.php. This section here, in fact:

..
///// BEGIN Configuration //////
 
...
 
/**
 * Use a custom field during checkout?  If true, check for the presence of $Custom_Field below.
 * If false, always subscribe the customer.  Use wisely.
 */
$Use_Custom_Field = true;
 
$Custom_Field = 'Subscribe';    // Name of the custom "Opt In" field during checkout.
$Custom_Field_Value = 'yes';    // The value of the custom field that indicates the customer's agreement.
 
$key = 'CHANGE THIS TEXT to your own datafeed keyphrase';
 
////// END Configuration ///////
...

1. Leave the lines about the Custom Field alone unless you want to change the name of the custom field or always opt your customers in to your mailing list (which, as noted above, is usually unwise).
2. Point FoxyCart to, for example, http://www.your-domain.dom/path/to/fc-campaignmonitor.php
   1. Log into your FoxyCart admin and go to Store → Advanced.
   2. Check the checkbox to turn the datafeed on, and copy the SUPER SECRET datafeed key.
   3. Enter the URL to fc-campaignmonitor.php (e.g. http://your.domain.dom/path/to/fc-campaignmonitor.php) that you uploaded as described above.
   4. Enter the SECRET data key that you copied a moment ago into fc-campaignmonitor.php, replacing “CHANGE THIS TEXT…”.
   5. Save your FoxyCart settings. Upload the changed fc-campaignmonitor.php to your server.
3. TEST! It should work, but go through a test transaction to make sure. Enter your datafeed key and the URL of your fc-campaignmonitor.php into test.xmldatafeed.php, then open http://your.domain.dom/path/to/test.xmldatafeed.php in your browser. You should get a page that contains only the word foxy in reply. If you get something else, double-check your datafeed keys in both files and, if all else fails, feel free to ask for help in our forum.
4. Once you're able to see 'foxy' when you go to 'test.xmldatafeed.php', then you

If your store is on FoxyCart 2.0 or newer, a new template configuration option will automatically insert a newsletter subscribe checkbox as part of the checkout form. To enable that, simply navigate to your store's FoxyCart administration, and on the “configuration” page, enable the “Allow users to sign up for your newsletter” option.

Within the fc-campaignmonitor.php file - you'll need to update the $Custom_Field variable to be set to newsletter_subscribe, and the $Custom_Field_Value to 1 like this:

$Custom_Field = 'newsletter_subscribe';    // Name of the custom "Opt In" field during checkout.
$Custom_Field_Value = '1';    // The value of the custom field that indicates the customer's agreement.

Now you have a datafeed receiver all set up on your server, so it's time to let your customers opt in to your mailing list. To do that, we need to add a Custom Field to your checkout template, so that your customer sees a “Subscribe” checkbox alongside their cart contents. There are a lot of cool things possible custom fields; find out more at the wiki page on Custom Fields. Today we're only going to add a single checkbox to the checkout template. Open the template up in your editor (if it's hosted on your server) or edit it directly from the FoxyCart admin interface, and add the following block of code anywhere in the template:

^^custom_begin^^
 
<h2>Newsletter</h2>
 
<fieldset id="fc_custom_fields">
	<legend>Newsletter</legend>
	<div class="fc_inner">
		<div>
			<h4>Subscribe</h4>
			<input type="checkbox" name="Subscribe" id="Subscribe" value="yes" checked="checked" />
			<label for="Subscribe">Leave this box checked to receive occasional updates about our products. We will not share your email address, and you can unsubscribe at any time.</label>
 
		</div>
	</div><!-- .fc_inner -->
</fieldset><!-- #fc_custom_fields -->
 
^^custom_end^^

You can put the code at the end of the file, or at the beginning – it doesn't matter. FoxyCart will move the <fieldset> into the checkout form when it loads your checkout page, so it can even be after the </body> and </html> tags. Replace “Newsletter” and “occasional updates about our products” with whatever's appropriate for your mailing list.

Save your changes to the checkout template in the FoxyCart admin. Test by adding a product to your cart and going to checkout – you should have a shiny new “Subscribe” checkbox, all primed and ready for your customers to use.

Download the Very Latest .zip from the foxy2cm GitHub repository.