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' => 'example@foo.com',
        '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' => 'example@foo.com',
            'euid'  => '1545d'
        )
    ));
} catch (\ZfrMailChimp\Exception\Ls\AlreadySubscribedException $e) {
    $message = $e->getMessage();

    // You can do something interesting here!
} catch(\ZfrMailChimp\Exception\Ls\DoesNotExist $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 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 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

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();

lenada / zfr-mailchimp