knplabs/mailjet-api-php

Mailjet PHP API client

Installs: 1 761

Dependents: 1

Stars: 9

Watchers: 20

Forks: 7

Open Issues: 1

Language: PHP

v1.1.1 2013-09-27 06:19 UTC

README

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

It supports both RESTful and Event Tracking APIs.

Build Status SensioLabsInsight Scrutinizer Quality Score Latest Stable Version Composer Downloads HHVM Status

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] => hello@Knplabs.com
//    [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] => hello@Knplabs.com
//    [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]          => hello@Knplabs.com
//    [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

KnpLabs Team

License

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