ZfrMailChimp, a MailChimp PHP Library

Note : this library does not contain tests, mainly because I'm not sure about how to write tests for an API wrapper. Don't hesitate to help on this ;-).

Introduction

This is an unofficial MailChimp PHP client for interacting with the v2 REST MailChimp API. If you are looking for a wrapper around previous MailChimp API versions (like 1.3), please refer to something else.

What is done

The following methods are supported by the client (not everything has been carefully tested though):

• Campaign related methods (complete)
• Ecomm related methods (complete)
• Vip related methods (complete)
• Folder related methods (complete)
• Users related methods (complete)
• Report related methods (only main methods)
• Templates related methods (complete)
• List related methods (nearly complete)
• Gallery related methods (complete)
• Helper related methods (partially complete)

Dependencies

• Guzzle library: >= 3.5

Integration with frameworks

To make this library even more easier to use, here are various frameworks integrations:

• ZfrMailChimpModule: a Zend Framework 2 module
• ZfrMailChimpBundle: a Symfony 2 bundle

Want to do an integration for another framework? Open an issue, and I'll open a repository for you!

Installation

We recommend you to use Composer to install ZfrMailChimp:

php composer.phar require zfr/zfr-mailchimp:2.*

Tutorial

Firstly, you need to instantiate the MailChimp client:

$client = new MailChimpClient('my-api-key');

The correct endpoint will be automatically chosen based on your API key.

You can then have access to all the methods available (see the list below):

// Get activity about a list
$activity = $client->getListActivity(array(
    'id' => 'list-id'
));

// Add a new folder
$client->addFolder(array(
    'name' => 'my-folder-name',
    'type' => 'template'
));

How to use it ?

You will notice that the method names below does not always have a 1-to-1 mapping with the API names. For instance, most method that imply retrieving something are prefixed by "get".

However, there is an exact mapping for parameters. Therefore, you just need to refer to the official documentation for a given method (links are given below). Here is an example with the subscribe method:

$client->subscribe(array(
    'id' => 'list-id',
    'email' => array(
        'email' => '[email protected]',
        'euid'  => '1545d'
    )
));

Exceptions handling

ZfrMailChimp tries its best to extract meaningful exceptions from MailChimp errors. All exceptions implement the ZfrMailChimp\Exception\ExceptionInterface interface, so you can use this to do a catch all block. You can find an exhaustive list of all exceptions in the ZfrMailChimp\Exception folder.

List exceptions are under the Ls namespace, because list is a reserved keyword in PHP.

Usage example:

try {
    $client->subscribe(array(
        'id' => 'list-id',
        'email' => array(
            'email' => '[email protected]',
            'euid'  => '1545d'
        )
    ));
} catch (\ZfrMailChimp\Exception\Ls\AlreadySubscribedException $e) {
    $message = $e->getMessage();

    // You can do something interesting here!
} catch(\ZfrMailChimp\Exception\Ls\DoesNotExistException $e) {
    // Do something else useful!
}
catch (\ZfrMailChimp\Exception\ExceptionInterface $e) {
    // Any other exception that may occur
}

Complete reference

Here are the supported methods today:

CAMPAIGN RELATED METHODS:

• array createCampaign(array $args = array()) doc
• array deleteCampaign(array $args = array()) doc
• array getCampaignContent(array $args = array()) doc
• array getCampaigns(array $args = array()) doc
• array getTemplateContent(array $args = array()) doc
• array pauseCampaign(array $args = array()) doc
• array replicateCampaign(array $args = array()) doc
• array resumeCampaign(array $args = array()) doc
• array scheduleCampaign(array $args = array()) doc
• array scheduleBatchCampaign(array $args = array()) doc
• array sendCampaign(array $args = array()) doc
• array sendTestCampaign(array $args = array()) doc
• array testSegmentation(array $args = array()) doc
• array unscheduleCampaign(array $args = array()) doc
• array updateCampaign(array $args = array()) doc

LIST RELATED METHODS:

• array addInterestGroup(array $args = array()) doc
• array addInterestGrouping(array $args = array()) doc
• array addListMergeVar(array $args = array()) doc
• array addListSegment(array $args = array()) doc
• array addListWebhook(array $args = array()) doc
• array addStaticListSegment(array $args = array()) doc
• array addStaticSegmentMembers(array $args = array()) doc
• array batchSubscribe(array $args = array()) doc
• array batchUnsubscribe(array $args = array()) doc
• array deleteInterestGroup(array $args = array()) doc
• array deleteInterestGrouping(array $args = array()) doc
• array deleteListMergeVar(array $args = array()) doc
• array deleteListSegment(array $args = array()) doc
• array deleteListWebhook(array $args = array()) doc
• array deleteStaticSegmentMembers(array $args = array()) doc
• array getAbuseReports(array $args = array()) doc
• array getInterestGroupings(array $args = array()) doc
• array getListActivity(array $args = array()) doc
• array getListClients(array $args = array()) doc
• array getListGrowthHistory(array $args = array()) doc
• array getListMergeVars(array $args = array()) doc
• array getLists(array $args = array()) doc
• array getListLocations(array $args = array()) doc
• array getListMembers(array $args = array()) doc
• array getListMembersActivity(array $args = array()) doc
• array getListMembersInfo(array $args = array()) doc
• array getListSegments(array $args = array()) doc
• array getListStaticSegments(array $args = array()) doc
• array getListWebhooks(array $args = array()) doc
• array resetListMergeVar(array $args = array()) doc
• array resetStaticSegment(array $args = array()) doc
• array setListMergeVar(array $args = array()) doc
• array subscribe(array $args = array()) doc
• array testListSegment(array $args = array()) doc
• array unsubscribe(array $args = array()) doc
• array updateInterestGroup(array $args = array()) doc
• array updateInterestGrouping(array $args = array()) doc
• array updateListMember(array $args = array()) doc
• array updateListSegment(array $args = array()) doc

ECOMM RELATED METHODS:

• array addOrder(array $args = array()) doc
• array deleteOrder(array $args = array()) doc
• array getOrders(array $args = array()) doc

FOLDER RELATED METHODS:

• array addFolder(array $args = array()) doc
• array deleteFolder(array $args = array()) doc
• array getFolders(array $args = array()) doc
• array updateFolders(array $args = array()) doc

TEMPLATE RELATED METHODS:

• array addTemplate(array $args = array()) doc
• array deleteTemplate(array $args = array()) doc
• array getTemplateInfo(array $args = array()) doc
• array getTemplates(array $args = array()) doc
• array undeleteTemplate(array $args = array()) doc
• array updateTemplate(array $args = array()) doc

REPORT RELATED METHODS:

• array getCampaignAbuseReport(array $args = array()) doc
• array getCampaignAdviceReport(array $args = array()) doc
• array getCampaignBounceMessage(array $args = array()) doc
• array getCampaignBounceMessages(array $args = array()) doc
• array getCampaignSummaryReport(array $args = array()) doc
• array getCampaignGoogleAnalyticsReport(array $args = array()) doc

USERS RELATED METHODS:

• array inviteUser(array $args = array()) doc
• array getInvitations(array $args = array()) doc
• array getLogins(array $args = array()) doc
• array getProfile(array $args = array()) doc
• array reinviteUser(array $args = array()) doc
• array revokeLogin(array $args = array()) doc
• array revokeUserInvitation(array $args = array()) doc

VIP RELATED METHODS:

• array addVipMembers(array $args = array()) doc
• array deleteVipMembers(array $args = array()) doc
• array getVipMembers(array $args = array()) doc
• array getVipActivity(array $args = array()) doc

GALLERY RELATED METHODS:

• array getGalleryImages(array $args = array()) doc

HELPER RELATED METHODS:

• array getAccountDetails(array $args = array()) doc
• array ping(array $args = array()) doc

Advanced usage

Attaching Guzzle plugins

UPDATE: Async plugin Guzzle 3 has been known to be very strange, and often not work as expected. Actually, it has even been removed in Guzzle 5. I'd suggest you to trying manually the Async plugin, but I recommand you NOT to use it.

Because ZfrMailChimp is built on top of Guzzle, you can take advantage of all the nice features of it. For instance, let's say you want to send requests asynchronously, you can simply attach the built-in Async plugin:

use ZfrMailChimp\Client\MailChimpClient;
use Guzzle\Plugin\Async\AsyncPlugin;

$client = new MailChimpClient('my-secret-key');
$client->addSubscriber(new AsyncPlugin());
$response = $client->get()->send();