mailjet-api-php

mailjet-api-php is a PHP library for quick and simple consuming of Mailjet API.

It supports both RESTful and Event Tracking APIs.

Usage

RESTful API - OOP wrappers

This library provides OOP wrappers to most (all) API endpoints, that are located under Mailjet/Api/Request namespace. These include:

• Api class for sending Api related calls
• User class for sending User related calls

Simple example:

<?php

// This file is generated by Composer
require_once 'vendor/autoload.php';

use Mailjet/Api/Client;
use Mailjet/Api/Request/User;

$user = new User(new Client('api_key', 'secret_key'));
$userInfo = $user->getInfo();

var_dump($userInfo);

//(
//    [username] => KnpLabs
//    [email] => [email protected]
//    [locale] => en_US
//    [currency] => USD
//    [timezone] => America/New_York
//    [firstname] => KnpLabs
//    ....
//)

RESTful API - Client

In addition to using wrappers, you can obviously also use the client directly to make API requests on lower level. To ease consumption of RESTful API there's a RequestApi helper class, which lists all available queries. Check Mailjet documentation for a detailed list of queries.

Simple example:

<?php

// This file is generated by Composer
require_once 'vendor/autoload.php';

use Mailjet/Api/Client;
use Mailjet/Api/RequestApi;

$client = new Client('api_key', 'secret_key');
$userInfo = $client->get(RequestApi::USER_INFOS);

var_dump($userInfo);

//(
//    [username] => KnpLabs
//    [email] => [email protected]
//    [locale] => en_US
//    [currency] => USD
//    [timezone] => America/New_York
//    [firstname] => KnpLabs
//    [lastname] =>
//    [company_name] => KnpLabs
//    [contact_phone] =>
//    [address_street] =>
//    [address_postal_code] =>
//    [address_city] =>
//    [address_country] =>
//    [tracking_openers] => 1
//    [tracking_clicks] => 1
//)

Sending a POST request:

<?php

// ... initialize client

$result = $client->post(RequestApi::USER_DOMAIN_ADD, array(
    'domain' => 'example.com'
));

var_dump($result);

//(
//    [status]    => 200
//    [file_name] => empty_file
//    [id]        => 123
//)

Event Tracking API

mailjet-api-php provides a clean OOP interface to interact with Event Tracking API.

<?php

use Mailjet/Event/EventFactory;

$factory = new EventFactory();

// fetch incoming data into $data array, example
//(
//    [event]          => open
//    [email]          => [email protected]
//    [mj_contact_id]  => 123
//    [mj_campaign_id] => 123
//    [customcampaign] => Hello from KnpLabs
//    [ip]             => 127.0.0.1
//    [geo]            => US
//    [agent]          => Mozilla/5.0 (X11; Ubuntu; Linux i686; rv:21.0) Gecko/20100101 Firefox/21.0
//)

$event = $factory->createEvent($data);

echo get_class($event); // \Mailjet\Event\Events\OpenEvent
echo $event->getType(); // open
echo $event->getIp();   // 127.0.0.1

Note: this library is not responsible for validation of incoming data. However, assuming the data is coming from Mailjet servers, it will work correctly.

Symfony2 integration

You don't need a special bundle to use the RESTful API with Symfony2, you can initialize the service with a simple config:

services:
    knp_mailjet.api:
        class: Mailjet\Api\Client
        arguments: [<your_mailjet_api_key>, <your_mailjet_secret_key>]

And that's it, Mailjet RESTful API is now available via:

<?php

$this->container->get('knp_mailjet.api');

And to initialize higher level OOP wrappers:

services:
    knp_mailjet.api.request.user:
        class: Mailjet\Api\Request\User
        arguments: [@knp_mailjet.api]

    # ... other wrappers definitions

<?php

$this->container->get('knp_mailjet.api.request.user')->getInfo();

However, if you need both RESTful and Event API support, then there's KnpMailjetBundle.

Installation

The first step to use mailjet-api-php is to download Composer:

$ curl -s http://getcomposer.org/installer | php

Now add mailjet-api-php with Composer:

$ php composer.phar require knplabs/mailjet-api-php:1.*

And that's it! Composer will automatically handle the rest.

Alternatively, you can manually add the dependency to composer.json file...

{
    "require": {
        "knplabs/mailjet-api-php": "1.*"
    }
}

... and then install our dependencies using:

$ php composer.phar install

Requirements

• PHP >= 5.3.8
• HTTP component of Guzzle library
• (optional) Symfony2 Debug Component

Contributing

See CONTRIBUTING.md file.

Running the Tests

To run unit tests, you'll need a set of dev dependencies you can install using Composer:

php composer.phar install --dev

Once installed, just launch the following command:

phpunit

Credits

OOP wrappers idea was originally implemented by David Guyon in his version of the client.

Sponsored by

License

mailjet-api-php is released under the MIT License. See the bundled LICENSE file for details.