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