Mailgun's Official SDK for PHP
PHP
Latest commit 1613843 Dec 10, 2016 @DavidGarciaCat DavidGarciaCat committed with pirogoeth Routes API (#249)
* Add initial (empty) Routes PHP Unit Test file

We still need to provide the automated tests

* Add initial Routes file

* Describe API Methods

* Inherit method from TestCase - adding @inheritdoc annotation

* Add new DTOs to map API responses to known objects

* Add new Response to manage the Routes list

* Implement method to retrieve a list of Routes

* Add new Response to manage a single Route resource

* Implement method to retrieve a single Route

* Set ShowResponse as final

* Add new Response to manage the Create process

* Implement method to create a new Route

* Fix missing annotation

* Add new Response to manage the Delete Route process

* Implement method to delete a Route based on the ID

* Add new Response to manage the Update Route process

This response is based on Domain API docs due there are no examples on
Routes API docs. We may need to update the response.

* Implement method to update a Route based on the ID

* Require a $limit value greater than 0

* Require a $skip value greater than or equal to 0

* Set UpdateResponse as final

* Add new (empty) public methods to test the Routes API

* Provide method to get the Routes API from Mailgun Client

* Add missed annotation

* Update ShowResponse to return an instance of ApiResponse instead of the DTO

* Update annotation

* Fix annotation

* Update array $actions to provide an empty array by default

* Update parameters to make sure the last arg always is a DateTime (or null)

* Use empty()

* Remove DTO suffix

* Move DTOs to the parent folder/namespace

* Fix annotations

README.md

Mailgun PHP client

This is the Mailgun PHP SDK. This SDK contains methods for easily interacting with the Mailgun API. Below are examples to get you started. For additional examples, please see our official documentation at http://documentation.mailgun.com

Latest Version Build Status StyleCI Code Coverage Quality Score Total Downloads Join the chat at https://gitter.im/mailgun/mailgun-php

This is the documentation for dev-master. You find documentation for the latest stable release here.

Installation

To install the SDK, you will need to be using Composer in your project. If you aren't using Composer yet, it's really simple! Here's how to install composer:

curl -sS https://getcomposer.org/installer | php

The Mailgun api client is not hard coupled to Guzzle or any other library that sends HTTP messages. It uses an abstraction called HTTPlug. This will give you the flexibilty to choose what PSR-7 implementation and HTTP client to use.

If you just want to get started quickly you should run the following command:

php composer.phar require mailgun/mailgun-php php-http/curl-client guzzlehttp/psr7

For shared hosts without SSH access, check out our Shared Host Instructions.

Why requiring so many packages?

Mailgun has a dependency on the virtual package php-http/client-implementation which requires to you install an adapter, but we do not care which one. That is an implementation detail in your application. We also need a PSR-7 implementation and a message factory.

You do not have to use the php-http/curl-client if you do not want to. You may use the php-http/guzzle6-adapter. Read more about the virtual packages, why this is a good idea and about the flexibility it brings at the HTTPlug docs.

Usage

You should always use Composer's autoloader in your application to automatically load the your dependencies. All examples below assumes you've already included this in your file:

require 'vendor/autoload.php';
use Mailgun\Mailgun;

Here's how to send a message using the SDK:

# First, instantiate the SDK with your API credentials and define your domain. 
$mg = new Mailgun("key-example");
$domain = "example.com";

# Now, compose and send your message.
$mg->sendMessage($domain, array('from'    => 'bob@example.com', 
                                'to'      => 'sally@example.com', 
                                'subject' => 'The PHP SDK is awesome!', 
                                'text'    => 'It is so simple to send a message.'));

Or obtain the last 25 log items:

# First, instantiate the SDK with your API credentials and define your domain. 
$mg = new Mailgun("key-example");
$domain = "example.com";

# Now, issue a GET against the Logs endpoint.
$mg->get("$domain/log", array('limit' => 25, 
                              'skip'  => 0));

Response

The results of a API call is, by default, a domain object. This will make it easy to understand the response without reading the documentation. One can just read the doc blocks on the response classes. This provide an excellet IDE integration.

$mg = new Mailgun("key-example");
$dns = $mg->domains()->show('example.com')->getInboundDNSRecords();

foreach ($dns as $record) {
  echo $record->getType();
}

If you rather be working with array then object you can inject the ArrayDeserializer to the Mailgun class.

use Mailgun\Deserializer\ArrayDeserializer;

$mg = new Mailgun("key-example", null, null, new ArrayDeserializer());
$data = $mg->domains()->show('example.com');

foreach ($data['receiving_dns_records'] as $record) {
  echo isset($record['record_type']) ? $record['record_type'] : null;
}

You could also use the PSR7Deserializer to get a PSR7 Response returned from the API calls.

Debugging

Debugging the PHP SDK can be really helpful when things aren't working quite right. To debug the SDK, here are some suggestions:

Set the endpoint to Mailgun's Postbin. A Postbin is a web service that allows you to post data, which is then displayed through a browser. This allows you to quickly determine what is actually being transmitted to Mailgun's API.

Step 1 - Create a new Postbin.
Go to http://bin.mailgun.net. The Postbin will generate a special URL. Save that URL.

Step 2 - Instantiate the Mailgun client using Postbin.

Tip: The bin id will be the URL part after bin.mailgun.net. It will be random generated letters and numbers. For example, the bin id in this URL, http://bin.mailgun.net/aecf68de, is "aecf68de".

# First, instantiate the SDK with your API credentials and define your domain. 
$mg = new Mailgun('key-example', null, 'bin.mailgun.net');
$mg->setApiVersion('aecf68de');
$mg->setSslEnabled(false);
$domain = 'example.com';

# Now, compose and send your message.
$mg->sendMessage($domain, array('from'    => 'bob@example.com', 
                                'to'      => 'sally@example.com', 
                                'subject' => 'The PHP SDK is awesome!', 
                                'text'    => 'It is so simple to send a message.'));

Additional Info

For usage examples on each API endpoint, head over to our official documentation pages.

This SDK includes a Message Builder, Batch Message and Opt-In Handler component.

Message Builder allows you to quickly create the array of parameters, required to send a message, by calling a methods for each parameter. Batch Message is an extension of Message Builder, and allows you to easily send a batch message job within a few seconds. The complexity of batch messaging is eliminated!

Framework integration

If you are using a framework you might consider these composer packages to make the framework integration easier.

Contribute

We are currently building a new object oriented API client. Feel free to contribute in any way. As an example you may:

  • Trying out dev-master the code
  • Create issues if you find problems
  • Reply to other people's issues
  • Review PRs
  • Write PR. You find our current milestone here

Running the test code

If you want to run the tests you should run the following commands:

git clone git@github.com:mailgun/mailgun-php.git
cd mailgun-php
composer update
composer test

Support and Feedback

Be sure to visit the Mailgun official documentation website for additional information about our API.

If you find a bug, please submit the issue in Github directly. Mailgun-PHP Issues

As always, if you need additional assistance, drop us a note through your Control Panel at https://mailgun.com/cp/support.