[API v3] Mailjet PHP Wrapper
PHP
Latest commit 73b2b89 Feb 6, 2017 @Aridjar Aridjar committed on GitHub Merge pull request #78 from mailjet/v3.1_smart
V3.1 smart

README.md

alt text

Codacy Badge Build Status MIT License Current Version

Mailjet API Client.

Check out all the resources and all the PHP code examples on the official documentation: Maijlet Documentation

Requirements

PHP >= 5.4

Installation

composer require mailjet/mailjet-apiv3-php

Without composer:

Clone or Download this repository that already contains all the dependencies and the vendor/autoload.php file. If you encounter any issue, please post it here and not on the mirror repository.

Getting Started !

grab and save your Mailjet API credentials. It will create some variables available in your code, via the getenv function:

export MJ_APIKEY_PUBLIC='your api key'
export MJ_APIKEY_PRIVATE='your api secret'

Initialize your Mailjet Client:

<?php

use \Mailjet\Resources;

// getenv will allow us to get the MJ_APIKEY_PUBLIC/PRIVATE variables we created before
$apikey = getenv('MJ_APIKEY_PUBLIC');
$apisecret = getenv('MJ_APIKEY_PRIVATE');

// or

$apikey = 'my api key';
$apisecret = 'my api secrret';

$mj = new \Mailjet\Client($apikey, $apisecret);
?>

It's as easy as 1, 2, 3 !

Make your first call

<?php
require 'vendor/autoload.php';

use \Mailjet\Resources;

// use your saved credentials
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));

// Resources are all located in the Resources class
$response = $mj->get(Resources::$Contact);

/*
  Read the response
*/
if ($response->success())
  var_dump($response->getData());
else
  var_dump($response->getStatus());

Filtering resources

The Mailjet API provides a set of general filters that can be applied to a GET request for each resource. In addition to these general filters, each API resource has its own filters that can be used when performing the GET

<?php

$filters = ['Limit' => '150'];

$response = $mj->get(Resources::$Contact, ['filters' => $filters]);

Send transactional emails

<?php

$body = [
    'FromEmail' => "pilot@mailjet.com",
    'FromName' => "Mailjet Pilot",
    'Subject' => "Your email flight plan!",
    'Text-part' => "Dear passenger, welcome to Mailjet! May the delivery force be with you!",
    'Html-part' => "<h3>Dear passenger, welcome to Mailjet!</h3><br />May the delivery force be with you!",
    'Recipients' => [['Email' => "passenger@mailjet.com"]]
];

$response = $mj->post(Resources::$Email, ['body' => $body]);

Send marketing campaign

To send your first newsletter, you need to have at least one active sender address in the Sender domains & addresses section.

<?php

$body = [
    'Recipients' => [
        [
            'Email' => "mailjet@example.org",
            'Name' => "Mailjet"
        ]
    ]
];

$response = $mj->post(Resources::$NewsletterTest, ['id' => $id, 'body' => $body]);

?>

Event API - real time notifications

The Event API offer a real-time notification through http request on any events related to the messages you sent. The main supported events are open, click, bounce, spam, blocked, unsub and sent. This event notification works for transactional and marketing emails.

The endpoint is an URL our server will call for each event (it can lead to a lot of hits !). You can use the API to setup a new endpoint using the /eventcallbackurl resource. Alternatively, you can configure this in your account preferences, in the Event Tracking section.

<?php

$body = [
    'EventType' => "open",
    'Url' => "https://mydomain.com/event_handler"
];

$response = $mj->post(Resources::$Eventcallbackurl, ['body' => $body]);

Statistics

The Mailjet API offers resources to extracts information for every messages you send. You can also filter through the message statistics to view specific metrics for your messages.

<?php

$response = $mj->get(Resources::$Message, ['id' => $id]);

Parse API - Inbound emails

The Parse API allows you to have inbound emails parsed and their content delivered to a webhook of your choice. In order to begin receiving emails to your webhook, create a new instance of the Parse API via a POST request on the /parseroute resource.

<?php

$body = [
    'Url' => 'https://www.mydomain.com/mj_parse.php'
];

$response = $mj->post(Resources::$Parseroute, ['body' => $body]);

New !! Specificities of the version 3.1 !

This version adds a new way to construct the Client or your call. We add the possibility to add an array with for parameters on both Client creation or API call (please, note that each of these parameters are preset and are not mandatory in the creation or the call) :

  • url (api.mailjet.com)
  • version (v3)
  • call (true)
  • secured (true (true give 'https' when false give 'http'))

A basic example :

<?php 
...

// We initialise the client with variables. We only keep the secured from the main configuration.
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'),
                          getenv('MJ_APIKEY_PRIVATE'),
                          ['url' => "www.mailjet.com", 'version' => 'v3.1', 'call' => false]
                        );

// We only change the version for this call
$response = $mj->get(Resources::$Contact, [], ['version' => 'v3']);

Here is the priority list :

Funtion call > Client creation > resource (only with version) > wrapper configuration

Note : the settings pasted in the call will only be used for this call.

TODO :

  • add a functionality changing the Client configuration
  • add anoter functionality setting the client to the main configuration

Here is the list of the functionalities working with the version 3.1 :

  • RESSOURCES::$Email

Send a pull request

  • Fork the project.
  • Create a topic branch.
  • Implement your feature or bug fix.
  • Add documentation for your feature or bug fix.
  • Add specs for your feature or bug fix.
  • Commit and push your changes.
  • Submit a pull request. Please do not include changes to the gemspec, or version file.