hampel / mailchimp-subscribe
Wrapper for the list subscription and management methods of the MailChimp API v3 using Guzzle
Requires
- php: >=5.5.0
- guzzlehttp/guzzle: ~6.0
- hampel/json: ~2.0
Requires (Dev)
- mockery/mockery: ^0.9
- phpunit/phpunit: ~4.0
This package is auto-updated.
Last update: 2024-10-19 10:15:00 UTC
README
A MailChimp API wrapper using Guzzle v6 which implements a simple list subscription interface using the MailChimp v3 API.
By Simon Hampel.
Installation
The recommended way of installing MailChimp Subscribe is through Composer:
:::json
{
"require": {
"hampel/mailchimp-subscribe": "~1.0"
}
}
Configuration
To use the MailChimp subscriber, you'll need to generate an API key using the MailChimp admin interface.
Log in to MailChimp and then go to Account
by clicking on your username/avatar at the top and selecting Account from
the menu.
Next, go to the Extras
area and click on API Keys
.
Click on the Create a Key
button and give your new key a meaningful label so you know which one it is.
You'll also need to find the list ID of the mailing list you want to subscribe people to.
Click on Lists
at the top and then click on your list name.
Click on the Settings
submenu and select the List name and campaign defaults
option.
Over on the right will be your List ID - make a note of this.
Usage
Initialisation
To start with, you'll need to create a MailChimp object which does the actual communication.
The quick way is to use the factory:
:::php
<?php
use MailChimp\MailChimp;
$apikey = 'YOUR API KEY HERE';
$mc = MailChimp::make($apikey);
Alternatively, if you need more control, you can use the long-hand method:
:::php
<?php
use GuzzleHttp\Client;
use MailChimp\MailChimp;
$apikey = 'YOU API KEY HERE';
$config = MailChimp::getConfig($apikey);
$guzzle = new Client($config);
$mc = new MailChimp($guzzle, $apikey);
You'll also want to create a mailing list object to then work with the list:
:::php
<?php
use MailChimp\MailingList;
$listid = 'YOU LIST ID HERE';
$list = new MailingList($mc, $listid);
We're now ready to work with our list.
Get Member
You can retrieve the details of a member by calling the getMember
method of the MailingList class:
:::php
<?php
var_dump($list->getMember('user@example.com'));
The getMember function returns false
if the email address was not found in the list.
Get Member Status
Retrieve the current status of a list member by calling the getMemberStatus
method:
:::php
<?php
var_dump($list->getMemberStatus('user@example.com'));
Possible return values are: subscribed, unsubscribed, cleaned, pending - or false if the member was not found.
Check if Member Exists
You can check if a user is a member of a list with the isMember
method, which returns a boolean result:
:::php
<?php
if ($list->isMember('user@example.com'))
{
echo "user is a member of our list";
}
else
{
echo "user is not yet a member of our list";
}
Subscribe a Member
Subscribe a new email address to your list using the subscribe
method:
:::php
<?php
var_dump($list->subscribe('user@example.com'));
To have MailChimp send a confirmation to the user before adding them to your list (double opt-in), set the second
parameter to true
: $list->subscribe('user@example.com', true)
You may also send an associative array of merge fields (name-value pairs) as a third parameter:
:::php
<?php
var_dump($list->subscribe('user@example.com', false, ['FNAME' => 'Joe', 'LNAME' => 'Bloggs']));
Details about the subscribed user will be returned.
Unsubscribe a Member
To remove a user from the mailing list, use the unsubscribe
method:
:::php
<?php
var_dump($list->unsubscribe('user@example.com'));
Clean a Member
To clean an address from the mailing list, use the clean
method:
:::php
<?php
var_dump($list->clean('user@example.com'));
Cleaned addresses are addresses that have bounced too many times or are now considered invalid.