behance/kong

This package is abandoned and no longer maintained. No replacement package was suggested.

The MailChimp and Mandrill wrapper to rule them all.

1.0.0 2016-11-01 17:09 UTC

Requires

• php: >=5.6.0
• guzzle/guzzle: 3.8.*

Requires (Dev)

• phpdocumentor/phpdocumentor: 2.*
• phpunit/phpunit: 5.*

MIT

• Mark Dunphy

• mailchimp
• email

README

#Kong The MailChimp API wrapper to rule them all.

#Documentation

Kong lets you easily interact with both MailChimp and Mandrill API endpoints from your application. There's a few options for you to get started:

###Getting a MailChimp/Mandrill object #####Using Kong

// Instantiate a Kong object and then grab a MailChimp or Mandrill object from it.
$kong = new Kong();

$mailchimp = $kong->getMailChimp( $mailchimp_api_key );
$mandrill = $kong->getMandrill( $mandrill_api_key );

#####Using MailChimp/Mandrill Directly

$mailchimp = new \Behance\Kong\MailChimp( $mailchimp_api_key );
$mandrill = new \Behance\Kong\Mandrill( $mandrill_api_key );

###Using MailChimp

#####Getting a List

$list_id = 'abcd1234';

// The second parameter tells it to make the MailChimp API call to hydrate the object with data about the list.
// This is the default behavior.
$list = $mailchimp->getList( $list_id, true ); // Returns an instance of \Behance\Kong\Model\MailChimp\MailingList

// You can access properties directly on the list object.

echo $list->id; // 'abcd1234'
echo $list->web_id; // 6789
echo $list->name; // 'Super Awesome Campaign'

var_dump( $list->toArray() );

// [
//   'id'                  => '237f949cef',
//   'web_id'              => 260033,
//   'name'                => 'Super Awesome Campaign',
//   'date_created'        => '2014-06-04 19:58:45',
//   'email_type_option'   => false,
//   'use_awesomebar'      => true,
//   'default_from_name'   => 'Default From Name',
//   'default_from_email'  => '[e-mail]',
//   'default_subject'     => '',
//   'default_language'    => 'en',
//   'list_rating'         => 3.5,
//   'subscribe_url_short' => 'http://shorter.url.com',
//   'subscribe_url_long'  => 'http://this.is.a.subscribe.url.com',
//   'beamer_address'      => '[e-mail]',
//   'visibility'          => 'pub',
//   'stats'               => [
//     'member_count'                 => 166412,
//     'unsubscribe_count'            => 29282,
//     'cleaned_count'                => 85,
//     'member_count_since_send'      => 0,
//     'unsubscribe_count_since_send' => 380,
//     'cleaned_count_since_send'     => 85,
//     'campaign_count'               => 1,
//     'grouping_count'               => 0,
//     'group_count'                  => 0,
//     'merge_var_count'              => 2,
//     'avg_sub_rate'                 => 0,
//     'avg_unsub_rate'               => 36550,
//     'target_sub_rate'              => 36656,
//     'open_rate'                    => 27,
//     'click_rate'                   => 2,
//     'date_last_campaign'           => '2014-06-05 14:24:34',
//   ],
//   'modules' => [],
// ]

// If you just want to operate on a list without pulling down the list data, you can pass false as the second parameter.
// This is good for when you just want to subscribe or unsubscribe somebody from the list and don't necessarily
// care about the list data specifically.
$list = $mailchimp->getList( $list_id, false );
var_dump( $list->toArray() );

// [
//   'id' => '237f949cef',
// ]

#####Subscribe/Unsubscribe a User

$email = '[e-mail]';
$merge_vars = [
  'fname' => 'Mark',
  'lname' => 'Dunphy',
  'city' => 'New York City',
];

// Subscribe accepts an optional associative array of merge vars as the second parameter. You'll
// need to configure these merge vars in MailChimp beforehand.
$list->subscribe( $email, $merge_vars );

// The unsubscribe method takes an email address as it's first parameter. It takes others that you should
// be aware of. Check them out in the API documentation
$list->unsubscribe( $email );

#####Batch Subscribe/Unsubscribe Read the MailChimp documentation here for more information on structuring data.

$users = [
  [
      'email' => [ 'email' => '[e-mail]' ],
      'merge_vars' => [
        'fname' => 'Mark',
        'lname' => 'Dunphy',
        'city' => 'New York City',
      ]
  ],
  [
      'email' => [ 'email' => '[e-mail]' ],
      'merge_vars' => [
        'fname' => 'Bill',
        'lname' => 'Nye',
        'city' => 'New York City',
      ]
  ],
];

// You can subscribe up to 10,000 users in one operation, but it will be rather slow. If you attempt to
// subscribe MORE than that in one operation, a \Behance\Kong\Exception\MaximumExceededException will be thrown.
$list->batchSubscribe( $users );

$users = [
  [ 'email' => [ 'email' => '[e-mail]' ] ],
  [ 'email' => [ 'email' => '[e-mail]' ] ],
];

// There are more parameters with default values to this method. Reference the Kong API documentation.
$list->batchUnsubscribe( $users );

###Using Mandrill

####Messages

The Mandrill client currently supports a limited number of operations on the Messages API.

#####Getting a Message Object

$mandrill = ( new Kong )->getMandrill( 'some_api_key' );
$message = $mandrill->message();

#####Sending HTML Messages

$html = '<h1>Hello world</h1>';
$message->setHtml( $html );
$message->setSubject( 'A really enticing subject' );
$message->addRecipient( '[e-mail]', 'Mark Dunphy' );
$message->send();

#####Sending Mandrill Templated Messages

$merge_vars = [ 'var1' => 'something!', 'var2' => 'something else!' ];
$message->setGlobalMergeVars( $merge_vars );
$message->setTemplate( 'template-on-mandrill' );
$message->setSubject( 'A really enticing subject' );
$message->addRecipient( '[e-mail]', 'Mark Dunphy' );
$message->send();

#####Set up Google Analytics

$message->setAnalyticsCampaign( 'my-campaign' );
$message->setAnalyticsDomains( [ 'yourwebsite.net', 'somethingelse.com' ] );

#####Set Mandrill Tags

$message->setTags( [ 'welcome-email', 'user-engagement' ] );

#####Send Asynchronously (via Mandrill async option)

// This is disabled by default
$message->setAsync( true );