mailjet/mailjet-apiv3-php

PHP wrapper for the Mailjet API

Tuesday, July 10, 2018
by Mailjet
Repository
19 Watchers
103 Stars
405,511 Installations

PHP
30 Dependents
2 Suggesters
48 Forks
12 Open issues
32 Versions
14 % Grown

The README.md

alt text , _(*1)

Official Mailjet PHP Wrapper

, _(*2)

Overview

This repository contains the official PHP wrapper for the Mailjet API., _(*3)

Check out all the resources and PHP code examples in the Offical Documentation., _(*4)

Compatibility
Installation
Authentication
Make your first call
Client / Call configuration specifics
List of resources
Request examples
SMS API
- Token authentication
- Example Request
Contribute

Compatibility

This library requires PHP v8.1 or higher., _(*5)

Installation

Use the below code to install the wrapper:, _(*6)

composer require mailjet/mailjet-apiv3-php, _(*7)

If you are not using Composer, clone or download this repository that already contains all the dependencies and the vendor/autoload.php file. If you encounter an issue, please post it here and not on the mirror repository., _(*8)

Authentication

The Mailjet Email API uses your API and Secret keys for authentication. Grab and save your Mailjet API credentials., _(*9)

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

Note: For the SMS API the authorization is based on a Bearer token. See information about it in the SMS API section of the readme., _(*10)

Initialize your Mailjet Client:, _(*11)

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');

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

// or, without using environment variables:

$apikey = 'your API key';
$apisecret = 'your API secret';

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

Make your first call

Here's an example on how to send an email:, _(*12)

 'v3.1']);

// Define your request body

$body = [
    'Messages' => [
        [
            'From' => [
                'Email' => "$SENDER_EMAIL",
                'Name' => "Me"
            ],
            'To' => [
                [
                    'Email' => "$RECIPIENT_EMAIL",
                    'Name' => "You"
                ]
            ],
            'Subject' => "My first Mailjet Email!",
            'TextPart' => "Greetings from Mailjet!",
            'HTMLPart' => "Dear passenger 1, welcome to Mailjet!
            
May the delivery force be with you!"
        ]
    ]
];

// All resources are located in the Resources class

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

// Read the response

$response->success() && var_dump($response->getData());
?>

Client / Call Configuration Specifics

To instantiate the library you can use the following constructor:, _(*13)

new \Mailjet\Client($MJ_APIKEY_PUBLIC, $MJ_APIKEY_PRIVATE,$CALL,$OPTIONS);, _(*14)

$MJ_APIKEY_PUBLIC : public Mailjet API key
$MJ_APIKEY_PRIVATE : private Mailjet API key
$CALL : boolean to enable the API call to Mailjet API server (should be true to run the API call)
$OPTIONS : associative PHP array describing the connection options (see Options bellow for full list)

Options

API Versioning

The Mailjet API is spread among three distinct versions:, _(*15)

v3 - The Email API
v3.1 - Email Send API v3.1, which is the latest version of our Send API
v4 - SMS API

Since most Email API endpoints are located under v3, it is set as the default one and does not need to be specified when making your request. For the others you need to specify the version using version. For example, if using Send API v3.1:, _(*16)

$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'),true,['version' => 'v3.1']);

For additional information refer to our API Reference., _(*17)

Base URL

The default base domain name for the Mailjet API is api.mailjet.com. You can modify this base URL by setting a value for url in your call:, _(*18)

$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'),
                          getenv('MJ_APIKEY_PRIVATE'), true,
                          ['url' => "api.us.mailjet.com"]
                        );

If your account has been moved to Mailjet's US architecture, the URL value you need to set is api.us.mailjet.com., _(*19)

Disable API call

By default the API call parameter is always enabled. However, you may want to disable it during testing to prevent unnecessary calls to the Mailjet API. This is done by setting the third parameter to false:, _(*20)

$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'), false);

List of resources

You can find the list of all available resources for this library in /src/Mailjet/Resources.php. The file lists the names of the PHP resources and the corresponding names in the API reference., _(*21)

Request Examples

POST Request

Use the post method of the Mailjet CLient (i.e. $mj->post($resource, $params)), _(*22)

$params will be a PHP associative array with the following keys :, _(*23)

body: associative PHP array defining the object to create. The properties correspond to the property of the JSON Payload)
id : ID you want to apply a POST request to (used in case of action on a resource)

Simple POST request

<?php
/*
Create a new contact:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$body = [
    'Email' => "email@example.com"
];
$response = $mj->post(Resources::$Contact, ['body' => $body]);
$response->success() && var_dump($response->getData());?>

Using actions

<?php
/*
Manage the subscription status of a contact to multiple lists
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$body = [
    'ContactsLists' => [
        [
            'ListID' => "$ListID_1",
            'Action' => "addnoforce"
        ],
        [
            'ListID' => "$ListID_2",
            'Action' => "addforce"
        ]
    ]
];
$response = $mj->post(Resources::$ContactManagecontactslists, ['id' => $id, 'body' => $body]);
$response->success() && var_dump($response->getData());
?>

GET Request

Use the get method of the Mailjet CLient (i.e. $mj->get($ressource, $params)), _(*24)

$param will be a PHP associative array with the following keys :, _(*25)

id : Unique ID of the element you want to get (optional)
filters: associative array listing the query parameters you want to apply to your get (optional)

Retrieve all objects

<?php
/*
Retrieve all contacts:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$response = $mj->get(Resources::$Contact);
$response->success() && var_dump($response->getData());
?>

Use filtering

<?php
/*
Retrieve all contacts that are not in the campaign exclusion list :
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$filters = [
  'IsExcludedFromCampaigns' => 'false'
];
$response = $mj->get(Resources::$Contact, ['filters' => $filters]);
$response->success() && var_dump($response->getData());
?>

Use paging and sorting

<?php
/*
Retrieve a specific contact ID :
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$filters = [
    'Limit'=>40,  // default is 10, max is 1000
    'Offset'=>20,
    'Sort'=>'ArrivedAt DESC',
    'Contact'=>$contact->ID,
    'showSubject'=>true
];
$response = $mj->get(Resources::$Message, ['filters'=>$filters]);
$response->success() && var_dump($response->getData());
?>

Retrieve a single object

<?php
/*
Retrieve a specific contact ID :
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$response = $mj->get(Resources::$Contact, ['id' => $id]);
$response->success() && var_dump($response->getData());
?>

PUT Request

Use the put method of the Mailjet CLient (i.e. $mj->put($ressource, $params)), _(*26)

$param will be a PHP associative array with the following keys :, _(*27)

id : Unique ID of the element you want to modify
body: associative array representing the object property to update

A PUT request in the Mailjet API will work as a PATCH request - the update will affect only the specified properties. The other properties of an existing resource will neither be modified, nor deleted. It also means that all non-mandatory properties can be omitted from your payload., _(*28)

Here's an example of a PUT request:, _(*29)

<?php
/*
Update the contact properties for a contact:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$body = [
    'first_name' => "John",
    'last_name' => "Smith"
];
$response = $mj->put(Resources::$ContactData, ['id' => $id, 'body' => $body]);
$response->success() && var_dump($response->getData());
?>

DELETE Request

Use the delete method of the Mailjet CLient (i.e. $mj->delete($ressource, $params)), _(*30)

Upon a successful DELETE request the response will not include a response body, but only a 204 No Content response code., _(*31)

Here's an example of a DELETE request:, _(*32)

<?php
/*
Delete an email template:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(getenv('MJ_APIKEY_PUBLIC'), getenv('MJ_APIKEY_PRIVATE'));
$response = $mj->delete(Resources::$Template, ['id' => $id]);
$response->success() && var_dump($response->getData());
?>

<?php
/*
Delete a contact from contact list:
*/
require 'vendor/autoload.php';
use \Mailjet\Resources;
$mj = new \Mailjet\Client(
  getenv('MJ_APIKEY_PUBLIC'),
  getenv('MJ_APIKEY_PRIVATE'),
  true,
  ['version' => 'v4']
);
$response = $mj->delete(Resources::$Contacts, ['ID' => xxxx]);
$response->success() && var_dump($response->getData());
?>

Response

The get, post, put and delete method will return a Response object with the following available methods:, _(*33)

success() : returns a boolean indicating if the API call was successful
getStatus() : http status code (ie: 200,400 ...)
getData() : content of the property data of the JSON response payload if exist or the full JSON payload returned by the API call. This will be PHP associative array.
getCount() : number of elements returned in the response
getReasonPhrase() : http response message phrases ("OK", "Bad Request" ...)

API resources helpers

All API resources are listed in the Resources object. It will make it easy to find the resources and actions aliases., _(*34)

$response = $mj->delete(Resources::$Template, ['id' => $id]);
$response = $mj->put(Resources::$ContactData, ['id' => $id, 'body' => $body]);
$response = $mj->post(Resources::$ContactManagecontactslists, ['id' => $id, 'body' => $body]);

SMS API

Token Authentication

Authentication for the SMS API endpoints is done using a bearer token. The bearer token is generated in the SMS section of your Mailjet account., _(*35)

To create a new instance of the Mailjet client with token authentication, the token should be provided as the first parameter, and the second must be NULL:, _(*36)

$mj = new \Mailjet\Client(getenv('MJ_APITOKEN'),
                          NULL, true,
                          ['url' => "api.mailjet.com", 'version' => 'v4', 'call' => false]
                        );

Example Request

Here's an example SMS API request:, _(*37)

//Send an SMS
$mj = new \Mailjet\Client(getenv('MJ_APITOKEN'),
                          NULL, true,
                          ['url' => "api.mailjet.com", 'version' => 'v4', 'call' => false]
                        );
$body = [
    'Text' => "Have a nice SMS flight with Mailjet !",
    'To' => "+336000000000",
    'From' => "MJ Pilot",
];
$response = $mj->post(Resources::$SmsSend, ['body' => $body]);
$response->success() && var_dump($response->getData());

Send request with supporting emojis in the subject

require 'vendor/autoload.php';

use \Mailjet\Resources;

$mj = new \Mailjet\Client(
    'xxx',
    'xxx',
    true,
);

try {
    $subject = \Mailjet\Utility\StringUtility::utfStringNotation("This is subject with emoji  🤑" );

    $body = [
        'Locale' => "en_US",
        'Sender' => "sender@gmail.com",
        'SenderEmail' => "sender@gmail.com",
        'Subject' => $subject,
        'TemplateID' => 12345,
        'ContactsListID' => 12345,
        'Title' => "Emoji Test" . time(),

    ];
    $response = $mj->post(
        Resources::$Campaigndraft,
        [
            'body' => $body,
        ]
    );
    print_r($response->getData());
} catch (Throwable $throwable) {
    print_r($throwable->getMessage());
}

Contribute

Mailjet loves developers. You can be part of this project!, _(*38)

This wrapper is a great introduction to the open source world, check out the code!, _(*39)

Feel free to ask anything, and contribute:, _(*40)

Fork the project.
Create a new branch.
Implement your feature or bug fix.
Add documentation to it.
Commit, push, open a pull request and voila.

If you have suggestions on how to improve the guides, please submit an issue in our Official API Documentation repo., _(*41)

The Versions

10/07 2018

dev-master

9999999-dev https://github.com/mailjet/mailjet-apiv3-php/

PHP wrapper for the Mailjet API

library mailjet-apiv3-php

PHP wrapper for the Mailjet API

mailjet/mailjet-apiv3-php

The README.md

Official Mailjet PHP Wrapper

Overview

Table of contents

Compatibility

Installation

Authentication

Make your first call

Dear passenger 1, welcome to Mailjet!

Client / Call Configuration Specifics

Options

API Versioning

Base URL

Disable API call

List of resources

Request Examples

POST Request

Simple POST request

Using actions

GET Request

Retrieve all objects

Use filtering

Use paging and sorting

Retrieve a single object

PUT Request

DELETE Request

Response

API resources helpers

SMS API

Token Authentication

Example Request

Send request with supporting emojis in the subject

Contribute

The Versions

dev-master

The Requires

The Development Requires

by Mailjet

dev-feature/add-v4-and-sms

The Requires

The Development Requires

by Mailjet

v1.3.0

The Requires

The Development Requires

by Mailjet

dev-add_request_timeout

The Requires

The Development Requires

by Mailjet

v1.2.0

The Requires

The Development Requires

by Mailjet

dev-v3.1_smart

The Requires

The Development Requires

by Mailjet

dev-v1.1.9-dev

The Requires

The Development Requires

by Mailjet

v1.1.9

The Requires

The Development Requires

by Mailjet

v1.1.8

The Requires

The Development Requires

by Mailjet

dev-data-fix

The Requires

The Development Requires

by Mailjet

v1.1.7

The Requires

The Development Requires