Skip to content
A feature rich object-oriented PHP library for interacting with MailChimp's API v3 πŸ’ŒπŸ΅
PHP
Branch: master
Clone or download
Jhut89 Merge pull request #68 from Jhut89/3.1.3
add switch for closing connections
Latest commit 0ca9cb7 Aug 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates Jul 3, 2018
src add switch for closing connections Aug 16, 2019
tests Add custom curl opt test Apr 25, 2019
.gitignore add composer.lock to vc Jul 3, 2018
.travis.yml add new .travis.yml for linter Jul 21, 2018
CODE_OF_CONDUCT.md
LICENSE Create LICENSE Nov 3, 2017
PULL_REQUEST_TEMPLATE.md readme updates, phpunit update, code beutified Jun 24, 2018
README.md add verified domains endpoint with test Mar 27, 2019
_config.yml Set theme jekyll-theme-hacker Jul 4, 2018
composer.json
composer.lock add ext-json to composer.json Apr 26, 2019

README.md

Table Of Contents

MAILCHIMP API 3.0 PHP

GitHub license Build Status Latest Stable Version Total Downloads Slack Workspace Trello Board

This is a PHP library for interacting with version 3.0 of MailChimp's API

This library assumes a basic understanding of the MailChimp application and its associated functions.

Installation

For Composer run:

composer require jhut89/mailchimp3php

Alternatively you may add a require line to your projects composer.json for the package jhut89/mailchimp3php.

Then run composer update and add the composer autoloader to your project with:

require "vendor/autoload.php";

You can then use a use statement to pull in the Mailchimp class:

use MailchimpAPI\Mailchimp;

Instantiation

$mailchimp = new Mailchimp('123abc123abc123abc123abc-us0');

To instantiate you will need a new instance of the Mailchimp class with your MailChimp account's API key as its only argument.

Oauth

If you are using Oauth to obtain an access token, this library can handle the "handshake" for you.

You must first send the user to your applications authorize_uri. You can get this url by calling the Mailchimp::getAuthUrl() statically:

$client_id =   '12345676543';
$redirect_url =  'https://www.some-domain.com/callback_file.php';

Mailchimp::getAuthUrl($client_id, $redirect_url);

From there the user will input their username and password to approve your application and will be redirected to the redirect_uri you set along with a code.

With that code you can now request an access token from mailchimp. For this you will need to call the Mailchimp::oauthExchange() method statically like this:

$code = 'abc123abc123abc123abc123';
$client_id =   '12345676543';
$client_secret =  '789xyz789xyz789xyz789xyz';
$redirect_url =  'https://www.some-domain.com/callback_file.php';

Mailchimp::oauthExchange($code, $client_id, $client_secret, $redirect_url);

If the handshake is successful, then this method will return a string containing your API key like this: 123abc123abc123abc123abc123abc-us0. This API key can now be used to instantiate your Mailchimp class as we have above.

Constructing a Request

Once you have instantiated the Mailchimp class you can start constructing requests. Constructing requests is done by 'chaining' methods to the $mailchimp instance. In most cases this 'chain' will end with the HTTP verb for your request.

GET

An Example of how to retrieve a list collection:

$mailchimp
    ->lists()
    ->get();

Retrieving an instance can be accomplished by giving a unique identifier for the instance you want as an argument to the appropriate method. For example if I wanted to retrieve a list instance from the above example I would simply pass a list_id, as the only argument for the lists() method. Like this:

$mailchimp
    ->lists('1a2b3c4d')
    ->get();

Methods available for each position in the chain depend on what the prior method returns. For example if I wanted to retrieve subscribers from a list in my account I would:

$mailchimp
    ->lists('1a2b3c4d')
    ->members()
    ->get();

Notice that I provided a list_id to the lists() method, as there would be no way to retrieve a list of subscribers from a lists collection. The above request however will only return 10 subscriber instances from the members collection. This is because MailChimp's API uses pagination (documented HERE) that defaults to count=10 and offset=0. This library allows you to alter query string parameters by passing them as an argument to the GET() method. We do this by providing an array of key-value pairs where the keys are the query parameter you wish to provide/alter and its value is the parameter's value. As an example if I wanted to retrieve the second 100 subscribers from my list I could:

$mailchimp
    ->lists('1a2b3c4d')
    ->members()
    ->get([
        "count" => "100", 
        "offset" => "100"
    ]);

This would be equivalent to making a get request against:

Https://us0.api.mailchimp.com/3.0/lists/1a2b3c4d/members?count=100&offset=100

Going a little further we can retrieve a single list member by giving the members_hash (md5 hash of lower-case address) to the members() method. Like this:

$mailchimp
    ->lists('1a2b3c4d')
    ->members('8bdbf060209f35b52087992a3cbdf4d7')
    ->get();

Alternatively, in place of providing an md5 hash as the identifier to the members() function you can provide a contact's email address as a string and this library will do the hashing for you. Like this:

$mailchimp
    ->lists('1a2b3c4d')
    ->members('example@domain.com')
    ->get();

You can read about GET requests in depth here: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Get-Requests

POST

While being able to retrieve data from your account is great we also need to be able to post new data. This can be done by calling the POST() method at the end of a chain. As an example subscribing an address to a list would look like this:

$post_params = [
    'email_address'=>'example@domain.com', 
    'status'=>'subscribed'
];

$mailchimp
    ->lists('1a2b3c4d')
    ->members()
    ->post($post_params);

In this case I would not provide members() with an identifier as I want to post to its collection. Also notice that the post data is an array of key-value pairs representing what parameters I want to pass to the MailChimp API. Be sure that you provide all required fields for the endpoint you are posting to. Check MailChimp's documentation for what parameters are required. Non-required parameters can just be added to the post data, and MailChimp will ignore any that are unusable. To illustrate here is an example of adding a subscriber to a list with some non-required parameters:

$merge_values = [
    "FNAME" => "John",
    "LNAME" => "Doe"
];

$post_params = [
    "email_address" => "example@domain.com", 
    "status" => "subscribed", 
    "email_type" => "html", 
    "merge_fields" => $merge_values
]

$mailchimp
    ->lists('1a2b3c4d')
    ->members()
    ->post($post_params);

You can read about POST requests in depth here: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Post-Requests

PATCH & PUT

This library handles PUT and PATCH request similar to that of POST requests. Meaning that PUT() & PATCH() both accept an array of key-value pairs that represent the data you wish altered/provided to MailChimp. As an example if I was patching the subscriber that we subscribed above, to have a new first name, that would look like this.

$mailchimp
    ->lists('1a2b3c4d')
    ->members('a1167f5be2df7113beb69c95ebcdb2fd')
    ->patch([
        "merge_fields" => ["FNAME" => "Jane"]
    ]);

You can read about PATCH & PUT requests in depth here: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Patch-&-Put-Requests

DELETE

Deleting a record from MailChimp is performed with the DELETE() method and is constructed similar to GET requests. If I wanted to delete the above subscriber I would:

$mailchimp
    ->lists('1a2b3c4d')
    ->members('a1167f5be2df7113beb69c95ebcdb2fd')
    ->delete();

You can read about DELETE requests in depth here: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Delete-Requests

Handling A Response

Methods named for http verbs such as get() ,post(), patch(), put(), or delete() kick off an over the wire request to MailChimp's A.P.I. Given a successful request these methods return an instance of a MailchimpResponse. I suggest you become familiar with this class as there are a number of modifiers and getters for different pieces of a response.

There are a number of getters we can use to interact with pieces our MailchimpResponse instance. Some of the more commonly used ones are:

$response->deserialize(); // returns a deserialized (to php object) resource returned by API
$response->getHttpCode(); // returns an integer representation of the HTTP response code
$response->getHeaders(); // returns response headers as an array of key => value pairs
$response->getBody(); // return the raw text body of the response

As an example, if I posses an API key but want the contact email associated with its account:

$mailchimp = new Mailchimp('123abc123abc123abc123abc-us0');
$account = $mailchimp
    ->account()
    ->get()
    
$contact_email = $account
    ->deserialize()
    ->email
    
print $contact_email; // outputs something like "example@domain.com"

You can read about how to work with responses in depth here: https://github.com/Jhut89/Mailchimp-API-3.0-PHP/wiki/Handling-A-Response

Method Chart (*excluding verbs)

  mailchimp()                       
  |                                 
  |----account()                    
  |                                 
  |----apps()                       
  |                                 
  |----automations()                
  |    |                            
  |    |----removedSubscribers()    
  |    |----emails()                
  |         |                       
  |         |---queue()*             
  |         |---pauseAll()*         
  |         |---startAll()*        
  |                                 
  |----batches()                    
  |                                 
  |----batchWebhooks()              
  |                                 
  |----campaignFolders()            
  |                                 
  |----campaigns()                  
  |    |                            
  |    |----cancel()*                
  |    |----pause()*                 
  |    |----replicate()*             
  |    |----resume()*                
  |    |----scedule()*              
  |    |----send()*                  
  |    |----test()*                  
  |    |----unschedule()*            
  |    |----checklist()             
  |    |----feedback()              
  |    |----content()
  |
  |----connectedSites()
  |    |
  |    |----verifyScriptInstallation()*               
  |                                 
  |----conversations()              
  |    |                            
  |    |----messages()              
  |                                 
  |----ecommStores()                
  |    |                            
  |    |----customers()             
  |    |----products()              
  |    |    |                       
  |    |    |----variants()         
  |    |    |----images()           
  |    |     
  |    |----promoRules()
  |    |    |
  |    |    |----promoCodes()
  |    |                   
  |    |----orders()                
  |    |    |                       
  |    |    |----lines()            
  |    |                            
  |    |----carts()                 
  |         |                       
  |         |----lines()
  |
  |----facebookAds()            
  |                                 
  |----fileManagerFiles()           
  |                                 
  |----fileManagerFolders()
  |
  |----googleAds()
  |
  |----landingPages()
  |    |
  |    |----publish()*
  |    |----unpublish()*
  |    |----content()         
  |                                 
  |----lists()                      
  |    |                            
  |    |----batchSubscribe()*             
  |    |----webhooks()              
  |    |----signupForms()           
  |    |----mergeFields()           
  |    |----growthHistory()         
  |    |----clients()               
  |    |----activity()              
  |    |----abuseReports()          
  |    |----segments()              
  |    |    |                       
  |    |    |----batch()*            
  |    |    |----members()          
  |    |                            
  |    |----members()               
  |    |    |                       
  |    |    |---notes()             
  |    |    |---goals()             
  |    |    |---activity()
  |    |    |---tags()          
  |    |                            
  |    |----interestCategories()    
  |         |                       
  |         |----interests()        
  |    
  |----ping()
  |                             
  |----reports()                    
  |    |                            
  |    |----unsubscribes()          
  |    |----subReports()            
  |    |----sentTo()                
  |    |----locations()             
  |    |----emailActivity() 
  |    |----googleAnalytics()
  |    |----openDetails()        
  |    |----eepurl()                
  |    |----domainPerformance()     
  |    |----advice()                
  |    |----abuse()                 
  |    |----clickReports()          
  |         |                       
  |         |----members()          
  |                                 
  |----searchCampaigns()            
  |                                 
  |----searchMembers()              
  |                                 
  |----templateFolders()            
  |                                 
  |----templates()                  
  |    |                            
  |    |----defaultContent()        
  |                             
  |----verifiedDomains()
       |
       |----verify()                            

*Please see MailChimp's API Documentation for what verbs are appropriate where.

** Methods marked with a * make a network request

**Please watch for updates, and feel free to Fork or Pull Request. Check out the Wiki for a little more info on contributing.

You can’t perform that action at this time.