Explicit creation and deletion of a temporary file

Method `::configure` replaced by a constructor

.editorconfig

@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+indent_size = 4
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true

.gitattributes

@@ -0,0 +1,15 @@
+.editorconfig     export-ignore
+.gitattributes    export-ignore
+/.github/         export-ignore
+.gitignore        export-ignore
+/.php_cs          export-ignore
+/.scrutinizer.yml export-ignore
+/.styleci.yml     export-ignore
+/.travis.yml      export-ignore
+/behat.yml.dist   export-ignore
+/features/        export-ignore
+/phpspec.ci.yml   export-ignore
+/phpspec.yml.dist export-ignore
+/phpunit.xml.dist export-ignore
+/spec/            export-ignore
+/tests/           export-ignore

.github/main.workflow

@@ -0,0 +1,16 @@
+workflow "Main" {
+  on = "push"
+  resolves = ["Roave BC Check", "PHPStan"]
+}
+
+action "Roave BC Check" {
+  uses = "docker://nyholm/roave-bc-check-ga"
+  secrets = ["GITHUB_TOKEN"]
+  args = ""
+}
+
+action "PHPStan" {
+  uses = "docker://oskarstark/phpstan-ga"
+  secrets = ["GITHUB_TOKEN"]
+  args = "analyse"
+}

.gitignore

@@ -1,10 +1,7 @@
-.DS_Store
+build
 vendor
 composer.phar
-smoketest.php
-rackspace_logo.jpg
-mailgun_icon.png
-build
 composer.lock
-nbproject/*
-.idea
+phpunit.phar
+phpunit.xml
+modd.conf

.php_cs

@@ -0,0 +1,32 @@
+<?php
+
+$header = <<<TXT
+Copyright (C) 2013 Mailgun
+
+This software may be modified and distributed under the terms
+of the MIT license. See the LICENSE file for details.
+TXT;
+
+$finder = PhpCsFixer\Finder::create()
+    ->in('src')
+    ->in('tests');
+
+return PhpCsFixer\Config::create()
+    ->setRiskyAllowed(true)
+    ->setRules([
+        '@PSR2' => true,
+        '@Symfony' => true,
+        'strict_param' => true,
+        'array_syntax' => ['syntax' => 'short'],
+        'declare_strict_types' => true,
+        'no_empty_phpdoc' => true,
+        'no_superfluous_phpdoc_tags' => true,
+        'header_comment' => [
+            'commentType' => 'comment',
+            'header' => $header,
+            'location' => 'after_declare_strict',
+            'separate' => 'both',
+        ],
+    ])
+    ->setFinder($finder)
+;

.scrutinizer.yml

@@ -0,0 +1,10 @@
+filter:
+    paths: [src/*]
+checks:
+    php:
+        code_rating: true
+        duplication: true
+tools:
+    external_code_coverage:
+        timeout: 1200    # Timeout in seconds.
+    php_cpd: false

.styleci.yml

@@ -0,0 +1,12 @@
+preset: symfony
+
+finder:
+    path:
+        - "src"
+        - "tests"
+
+enabled:
+    - short_array_syntax
+
+disabled:
+    - phpdoc_annotation_without_dot # This is still buggy: https://github.com/symfony/symfony/pull/19198

.travis.yml

@@ -1,17 +1,52 @@
 language: php
- 
+
+sudo: false
+
+cache:
+    directories:
+        - $HOME/.composer/cache/files
+
 php:
-  - 5.4
-  - 5.5
-  - 5.6
-  - 7.0
-  - hhvm
+  - 7.1
+  - 7.2
+  - 7.3
+
+branches:
+  except:
+    - /^analysis-.*$/
+    - /^patch-.*$/
+
+env:
+  - TEST_COMMAND="composer test"
+
+matrix:
+    fast_finish: true
+    include:
+        - php: 7.1
+          env: COMPOSER_FLAGS="--prefer-stable --prefer-lowest" PREFER_COVERAGE=true
+        - name: Backward compatibility test (Disabled)
+          php: 7.3
+          env: DEPENDENCIES="roave/backward-compatibility-check"
+          script: ./vendor/bin/roave-backward-compatibility-check || true
+        - name: PHPStan
+          php: 7.2
+          env: DEPENDENCIES="phpstan/phpstan"
+          script:
+            - ./vendor/bin/phpstan --version
+            - ./vendor/bin/phpstan analyse
 
 before_install:
-  - travis_retry composer self-update
+  - if [[ "$PREFER_COVERAGE" = true ]] && [[ "$TRAVIS_PULL_REQUEST" = false ]]; then TEST_COMMAND="composer test-coverage" COVERAGE=true; fi
+  - if ! [ -z "$DEPENDENCIES" ]; then composer require --no-update ${DEPENDENCIES}; fi;
 
 install:
-  - travis_retry composer install
+    - composer update ${COMPOSER_FLAGS} --prefer-dist --no-interaction
 
 script:
-  - phpunit
+  - composer validate --strict --no-check-lock
+  - echo $TEST_COMMAND
+  - $TEST_COMMAND
+
+after_success:
+    - if [[ "$COVERAGE" = true ]]; then wget https://scrutinizer-ci.com/ocular.phar; fi
+    - if [[ "$COVERAGE" = true ]]; then php ocular.phar code-coverage:upload --format=php-clover build/coverage.xml; fi

CHANGELOG.md

@@ -1,3 +1,254 @@
+# Change Log
+
+The change log describes what is "Added", "Removed", "Changed" or "Fixed" between each release.
+
+## 3.0.0
+
+### Added
+
+- Support for PSR-4
+- All classes `Mailgun\Model` are final or abstract. 
+
+### Changed
+
+- Dropped PHP5 support
+- Removed deprecated code
+- Moved `RequestBuilder` and `HttpClientConfigurator` to `Mailgun\HttpClient` namespace
+- Updated signature of `Mailgun::__construct()`
+
+### Removed
+
+- Dependency on `php-http/message`. 
+
+### [Unreleased]
+
+- API v4 Email Validation; please use US Servers with your public key instead
+(please check the Issues [617](https://github.com/mailgun/mailgun-php/issues/617)
+and [619](https://github.com/mailgun/mailgun-php/issues/619) for further details)
+
+## 2.8.1
+
+### Fixed
+
+- Added missing method to use all Mailing List and Ip features.
+
+## 2.8.0
+
+### Added
+
+- Add support for IPs endpoints
+- Add spport for Mailing Lists
+- Add `complaints` to Stats / Total Response
+- Add more tests for our models
+
+### Changed
+
+- Change the PHP Exception message for Bad Request errors to help to find the issue
+
+### Fixed
+
+- Fix an issue validating the max path length
+
+## 2.7.0
+
+### Added
+
+- Allow to set the Mailgun server when instantiating the Mailgun's client: `$mailgun = Mailgun::create('key', 'server');`
+- Add new PHPUnit tests for our models
+- Add new PHPUnit tests for our API
+- Added `Mailgun\Api\Attachment`
+- Fluent interface for `MessageBuilder` and `BatchMessage`
+- Support for HTTPlug 2.0
+
+### Changed
+
+- Second argument to `Mailgun\Message\MessageBuilder::addBccRecipient()` is now optional. 
+- We try to close open resources
+
+### Fixed
+
+- Fixed the type error when creating tags. 
+
+## 2.6.0
+
+### Added
+
+- Ported MessageBuilder and BatchMessage #472
+
+### Changed
+
+- Cast campaign IDs to string #460
+- Suggest packages used on Dev #440
+
+## 2.5.0
+
+### Added
+
+- Support for 413 HTTP status codes, when we send too large payloads to the API
+
+## 2.4.1
+
+### Added
+
+- Add new `Suppressions::getTotalCount()` method
+
+### Changed
+
+- Apply fixes from StyleCI
+- Updated `README.md` file
+
+### Fixed
+
+- Fix `Tags` on `Unsubscribe`
+- Fix typo on `Mailgun\Exception\HttpServerException`
+
+## 2.4.0
+
+### Added
+
+- Add cached property for DNS record
+- Add domain verification
+- `HttpClientException::getResponseCode()`
+- Added `AbstractDomainResponse` that `VerifyResponse` and `CreateResponse` extends. 
+
+### Fixed
+
+- Possible empty content of `WebhookIndexResponse`.
+- Typo in `TotalResponse` that caused the content to be empty. 
+
+### Changed
+
+- Allow some parameters to `Domain::create` to be optional. 
+
+## 2.3.4
+
+### Fixed
+
+- Typo in DnsRecord::isValid. This make sure the correct result of the function is returned.
+
+## 2.3.3
+
+### Changed
+
+- Using stable version of `php-http/multipart-stream-builder`
+- Improved tests
+
+## 2.3.2
+
+### Fixed
+
+- When parsing an address in `MessageBuilder` we surround the recipient name with double quotes instead of single quotes.   
+
+## 2.3.1
+
+### Fixed
+
+- Make sure to reset the `MultipartStreamBuilder` after a stream is built.
+
+## 2.3.0
+
+### Added
+
+- Support for sending messages with Mime. `$mailgun->messages()->sendMime()`
+
+## 2.2.0
+
+This version contains a new way of using the API. Each endpoint return a domain object and the
+endpoints are grouped like the API documentation. 
+
+### Added
+
+- Api classes in Mailgun\Api\*
+- Api models/responses in Mailgun\Model\*
+- Added Hydrators to hydrate PSR-7 responses to arrays or domain objects. 
+- All exceptions extend `Mailgun\Exception`.
+- New exceptions in `Mailgun\Exception` namespace.
+- Added `HttpClientConfigurator` to configure the HTTP client. 
+- Added HttpClient plugins `History` and `ReplaceUriPlugin`
+- Assertions with Webmozart\Assert 
+- `Mailgun\Mailgun::getLastResponse()`
+- `Mailgun\Connection\RestClient::getAttachment($url)`
+- Clear license information
+
+### Fixed
+
+- Fix disordered POST parameters. We do not use array syntax. 
+- Code styles
+
+### Deprecated
+
+The following classes will be removed in version 3.0.
+
+- `Mailgun\Connection\Exceptions\GenericHTTPError`
+- `Mailgun\Connection\Exceptions\InvalidCredentials`
+- `Mailgun\Connection\Exceptions\MissingEndpoint`
+- `Mailgun\Connection\Exceptions\MissingRequiredParameters`
+- `Mailgun\Connection\Exceptions\NoDomainsConfigured`
+- `Mailgun\Connection\RestClient`
+- `Mailgun\Constants\Api`
+- `Mailgun\Constants\ExceptionMessages`
+- `Mailgun\Mailgun::$resetClient`
+- `Mailgun\Mailgun::sendMessage()`
+- `Mailgun\Mailgun::verifyWebhookSignature()`
+- `Mailgun\Mailgun::post()`
+- `Mailgun\Mailgun::get()`
+- `Mailgun\Mailgun::delete()`
+- `Mailgun\Mailgun::put()`
+- `Mailgun\Mailgun::setApiVersion()`
+- `Mailgun\Mailgun::setSslEnabled()`
+- `Mailgun\Mailgun::MessageBuilder()`
+- `Mailgun\Mailgun::OptInHandler()`
+- `Mailgun\Mailgun::BatchMessage()`
+
+## 2.1.2
+
+- Bug fixes with multiple recipients, inline images and attachments.
+- Added more tests
+- Using PSR-2 code style
+
+## 2.1.1
+
+- Require php-http/message (#142)
+- Declare BatchMessage::endpointUrl (#112)
+
+## 2.1.0
+
+- Strict comparison of hash (#117)
+- No dependency on Guzzle/PSR7 (#139)
+- Build URL string form an array (#138)
+- Docblock update (#134)
+- Minor fixes (#90, #121, #98)
+
+## 2.0
+
+- Migrated to PHP-HTTP (#94)
+- Dropped support for PHP 5.4.
+
+## 1.8.0
+
+- Updated to Guzzle5 (#79)
+- Updated default API version from v2 to v3 (#75)
+- Show response message on 400, 401 and 404. (#72)
+- PHP DocBlocks, Constants Changes, and Minor Refactors (#66)
+- Added PHP 7.0 support for Travis-CI, removed PHP 5.3 support (#79)
+
+## 1.7.2
+
+- Added webhook signature verification - (#50)
+- Test PHP 5.6 and HHVM - (#51)
+- Improved error handling - (#48)
+- Fixed attachment handling in Message Builder - (#56)
+- Allow any data type in custom data - (#57)
+- Return non-JSON response data - (#60)
+- Removed legacy closing braces - (#64)
+
+## 1.7.1
+
+- Improved security of OptInHandler - (#31)
+- Fixed typo for including an Exception - (#41)
+- Fixed Mocks, removed unnecessary code, applied styling - (#44 & #42)
+- Less restrictive Guzzle requirement - (#45)
+
 ## 1.7 (2014-1-30)
 
 Bugfixes:

LICENSE

@@ -0,0 +1,17 @@
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -1,157 +1,143 @@
-Mailgun-PHP
-===========
+# 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
+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 Stable Version](https://poser.pugx.org/mailgun/mailgun-php/v/stable.png)](https://packagist.org/packages/mailgun/mailgun-php)
-[![Build Status](https://travis-ci.org/mailgun/mailgun-php.png)](https://travis-ci.org/mailgun/mailgun-php)
+[![Latest Version](https://img.shields.io/github/release/mailgun/mailgun-php.svg?style=flat-square)](https://github.com/mailgun/mailgun-php/releases)
+[![Build Status](https://img.shields.io/travis/mailgun/mailgun-php/master.svg?style=flat-square)](https://travis-ci.org/mailgun/mailgun-php)
+[![Code Coverage](https://img.shields.io/scrutinizer/coverage/g/mailgun/mailgun-php.svg?style=flat-square)](https://scrutinizer-ci.com/g/mailgun/mailgun-php)
+[![Quality Score](https://img.shields.io/scrutinizer/g/mailgun/mailgun-php.svg?style=flat-square)](https://scrutinizer-ci.com/g/mailgun/mailgun-php)
+[![Total Downloads](https://img.shields.io/packagist/dt/mailgun/mailgun-php.svg?style=flat-square)](https://packagist.org/packages/mailgun/mailgun-php)
+[![Join the chat at https://gitter.im/mailgun/mailgun-php](https://badges.gitter.im/mailgun/mailgun-php.svg)](https://gitter.im/mailgun/mailgun-php?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+## Installation
 
-Installation
-------------
 To install the SDK, you will need to be using [Composer](http://getcomposer.org/) 
 in your project. 
 If you aren't using Composer yet, it's really simple! Here's how to install 
-composer and the Mailgun SDK.
+composer:
 
-```PHP
-# Install Composer
+```bash
 curl -sS https://getcomposer.org/installer | php
+```
 
-# Add Mailgun as a dependency
-php composer.phar require mailgun/mailgun-php:~1.7.2
-``` 
+The Mailgun API Client is not hard coupled to Guzzle, Buzz or any other library that sends
+HTTP messages. Instead, it uses the [PSR-18](https://www.php-fig.org/psr/psr-18/) client abstraction.
+This will give you the flexibility to choose what
+[PSR-7 implementation and HTTP client](https://packagist.org/providers/php-http/client-implementation)
+you want to use. 
 
-**For shared hosts without SSH access, check out our [Shared Host Instructions](SharedHostInstall.md).**
+If you just want to get started quickly you should run the following command: 
 
-**Rather just download the files? [Library Download](https://9f67cbbd1116d8afb399-7760483f5d1e5f28c2d253278a2a5045.ssl.cf2.rackcdn.com/mailgun-php-1.7.2.zip).**
+```bash
+composer require mailgun/mailgun-php kriswallsmith/buzz nyholm/psr7
+```
 
-Next, require Composer's autoloader, in your application, to automatically 
-load the Mailgun SDK in your project:
-```PHP
+## Usage
+
+You should always use Composer autoloader in your application to automatically load
+your dependencies. All the examples below assume you've already included this in your
+file:
+
+```php
 require 'vendor/autoload.php';
 use Mailgun\Mailgun;
 ```
 
-Usage
------
 Here's how to send a message using the SDK:
 
 ```php
-# First, instantiate the SDK with your API credentials and define your domain. 
-$mg = new Mailgun("key-example");
-$domain = "example.com";
+// First, instantiate the SDK with your API credentials
+$mg = Mailgun::create('key-example'); // For US servers
+$mg = Mailgun::create('key-example', 'https://api.eu.mailgun.net'); // For EU servers
 
-# 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.'));
+// Now, compose and send your message.
+// $mg->messages()->send($domain, $params);
+$mg->messages()->send('example.com', [
+  '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: 
+Attention: `$domain` must match to the domain you have configured on [app.mailgun.com](https://app.mailgun.com/app/domains).
+
+### All usage examples
+
+You will find more detailed documentation at [/doc](doc/index.md) and on 
+[https://documentation.mailgun.com](https://documentation.mailgun.com/api_reference.html).
+
+### Response
+
+The result of an 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 provides an excellent IDE integration.
+ 
 ```php
-# First, instantiate the SDK with your API credentials and define your domain. 
-$mg = new Mailgun("key-example");
-$domain = "example.com";
+$mg = Mailgun::create('key-example');
+$dns = $mg->domains()->show('example.com')->getInboundDNSRecords();
 
-# Now, issue a GET against the Logs endpoint.
-$mg->get("$domain/log", array('limit' => 25, 
-                              'skip'  => 0));
-```
-
-Response
---------
-
-The results, provided by the endpoint, are returned as an object, which you 
-can traverse like an array. 
-
-Example: 
-
-```php
-$mg = new Mailgun("key-example");
-$domain = "example.com";
-
-$result = $mg->get("$domain/log", array('limit' => 25, 
-                                        'skip'  => 0));
-
-$httpResponseCode = $result->http_response_code;
-$httpResponseBody = $result->http_response_body;
-
-# Iterate through the results and echo the message IDs.
-$logItems = $result->http_response_body->items;
-foreach($logItems as $logItem){
-    echo $logItem->message_id . "\n";
+foreach ($dns as $record) {
+  echo $record->getType();
 }
 ```
 
-Example Contents:  
-**$httpResponseCode** will contain an integer. You can find how we use HTTP response 
-codes in our documentation: 
-http://documentation.mailgun.com/api-intro.html?highlight=401#errors
+If you'd rather work with an array than an object you can inject the `ArrayHydrator`
+to the Mailgun class. 
 
-**$httpResponseBody** will contain an object of the API response. In the above 
-example, a var_dump($result) would contain the following: 
+```php
+use Mailgun\Hydrator\ArrayHydrator;
 
-```
-object(stdClass)#26 (2) {
-["http_response_body"]=>
-  object(stdClass)#26 (2) {
-    ["total_count"]=>
-    int(12)
-    ["items"]=>
-    array(1) {
-      [0]=>
-      object(stdClass)#31 (5) {
-        ["hap"]=>
-        string(9) "delivered"
-        ["created_at"]=>
-        string(29) "Tue, 20 Aug 2013 20:24:34 GMT"
-        ["message"]=>
-        string(66) "Delivered: me@samples.mailgun.org → travis@mailgunhq.com 'Hello'"
-        ["type"]=>
-        string(4) "info"
-        ["message_id"]=>
-        string(46) "20130820202406.24739.21973@samples.mailgun.org"
-      }
-    }
-  }
+$configurator = new HttpClientConfigurator();
+$configurator->setApiKey('key-example');
+
+$mg = new Mailgun($configurator, new ArrayHydrator());
+$data = $mg->domains()->show('example.com');
+
+foreach ($data['receiving_dns_records'] as $record) {
+  echo isset($record['record_type']) ? $record['record_type'] : null;
 }
 ```
 
-Debugging
----------
+You can also use the `NoopHydrator` to get a PSR7 Response returned from 
+the API calls. 
 
-Debugging the PHP SDK can be really helpful when things aren't working quite right. 
+**Warning: When using `NoopHydrator` there will be no exceptions on a non-200 response.**
+
+### Debugging
+
+Debugging the PHP SDK can be 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. 
+Set the endpoint to Mailgun's Postbin. A Postbin is a web service that allows you to
+post data, which then you can display it through a browser. Using Postbin is an easy way
+to quickly determine what data you're transmitting 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".*
+*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`.*
 
 ```php
-# First, instantiate the SDK with your API credentials and define your domain. 
-$mg = new Mailgun('key-example', 'bin.mailgun.net', 'aecf68de', $ssl = False);
-$domain = 'example.com';
+$configurator = new HttpClientConfigurator();
+$configurator->setEndpoint('http://bin.mailgun.net/aecf68de');
+$configurator->setDebug(true);
+$mg = new Mailgun($configurator);
 
 # 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.'));
+$mg->messages()->send('example.com', [
+  '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
----------------
+### Additional Info
 
 For usage examples on each API endpoint, head over to our official documentation 
 pages. 
@@ -165,16 +151,45 @@ 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! 
 
-Support and Feedback
---------------------
+## Framework integration
+
+If you are using a framework you might consider these composer packages to make the framework integration easier. 
+
+* [tehplague/swiftmailer-mailgun-bundle](https://github.com/tehplague/swiftmailer-mailgun-bundle) for Symfony
+* [Bogardo/Mailgun](https://github.com/Bogardo/Mailgun) for Laravel
+* [katanyoo/yii2-mailgun-mailer](https://github.com/katanyoo/yii2-mailgun-mailer) for Yii2
+* [narendravaghela/cakephp-mailgun](https://github.com/narendravaghela/cakephp-mailgun) for CakePHP
+* [drupal/mailgun](https://www.drupal.org/project/mailgun) for Drupal
+
+## Contribute
+
+This SDK is an Open Source under the MIT license. It is, thus, maintained by collaborators and contributors.
+
+Feel free to contribute in any way. As an example you may: 
+* Trying out the `dev-master` code
+* Create issues if you find problems
+* Reply to other people's issues
+* Review PRs
+
+### Running the test code
+
+If you want to run the tests you should run the following commands: 
+
+```terminal
+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](http://documentation.mailgun.com/) for additional 
 information about our API. 
 
 If you find a bug, please submit the issue in Github directly. 
-[Mailgun-PHP Issues](https://github.com/mailgun/Mailgun-PHP/issues)
-
-As always, if you need additional assistance, drop us a note through your Control Panel at
-[https://mailgun.com/cp/support](https://mailgun.com/cp/support).
+[Mailgun-PHP Issues](https://github.com/mailgun/mailgun-php/issues)
 
+As always, if you need additional assistance, drop us a note through your account at
+[https://app.mailgun.com/app/support/list](https://app.mailgun.com/app/support/list).

SharedHostInstall.md

@@ -1,39 +0,0 @@
-Shared Host Installation
-========================
-
-If you do not have SSH access to your server, fear not! You can still run
-composer and download the SDK. Here's how...
-
-Installation
-------------
-
-Linux / Mac OSX:  
-*PHP is typically installed by default, consult your distribution documentation. Instructions from [getcomposer.org](http://getcomposer.org/doc/00-intro.md#installation-nix).*  
-
-1. curl -sS https://getcomposer.org/installer | php  
-2. php composer.phar require mailgun/mailgun-php:~1.7.2  
-3. The files will be downloaded to your local computer.   
-4. Upload the files to your webserver.   
-
-
-Windows:  
-*PHP must be installed on your computer, [download](http://windows.php.net/download/0). Instructions from [getcomposer.org](http://getcomposer.org/doc/00-intro.md#installation-windows).* 
-
-1. Download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe).  
-2. Open a Command Prompt and type "php composer require mailgun/mailgun-php:~1.7.2".  
-3. The files will be downloaded to your local computer.   
-4. Upload the files to your webserver.   
-
-
-Support and Feedback
---------------------
-
-Be sure to visit the Mailgun official 
-[documentation website](http://documentation.mailgun.com/) for additional 
-information about our API. 
-
-If you find a bug, please submit the issue in Github directly. 
-[Mailgun-PHP Issues](https://github.com/mailgun/Mailgun-PHP/issues)
-
-As always, if you need additional assistance, drop us a note at 
-[support@mailgun.com](mailto:support@mailgun.com).

composer.json

@@ -2,18 +2,33 @@
     "name": "mailgun/mailgun-php",
     "description": "The Mailgun SDK provides methods for all API functions.",
     "require": {
-        "guzzlehttp/guzzle": "~5.0"
+        "php": "^7.1",
+        "psr/http-client": "^1.0",
+        "php-http/multipart-stream-builder": "^1.0",
+        "php-http/client-common": "^1.9 || ^2.0",
+        "php-http/discovery": "^1.6",
+        "webmozart/assert": "^1.2"
     },
     "require-dev": {
-        "php": ">=5.4.0",
-        "phpunit/phpunit": "~4.6"
+        "phpunit/phpunit": "^7.5",
+        "php-http/guzzle6-adapter": "^1.0",
+        "nyholm/psr7": "^1.0",
+        "nyholm/nsa": "^1.1"
     },
     "autoload": {
-        "psr-0": {
-            "Mailgun\\Tests": "tests/",
-            "Mailgun": "src/"
+        "psr-4": {
+            "Mailgun\\": "src/"
         }
     },
+    "autoload-dev": {
+        "psr-4": {
+            "Mailgun\\Tests\\": "tests/"
+        }
+    },
+    "suggest": {
+        "php-http/curl-client": "cURL client for PHP-HTTP",
+        "guzzlehttp/psr7": "PSR-7 message implementation that also provides common utility methods"
+    },
     "license": "MIT",
     "authors": [
         {
@@ -21,5 +36,13 @@
             "email": "travis@mailgunhq.com"
         }
     ],
-    "minimum-stability": "stable"
+    "scripts": {
+        "test": "vendor/bin/phpunit",
+        "test-coverage": "vendor/bin/phpunit --coverage-text --coverage-clover=build/coverage.xml"
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-master": "3.0-dev"
+        }
+    }
 }

doc/attachments.md

@@ -0,0 +1,47 @@
+# Attachments
+
+You may attach a file from memory or by a file path.
+
+## From file path
+
+```php
+$mg->messages()->send('example.com', [
+  'from'    => 'bob@example.com', 
+  'to'      => 'sally@example.com', 
+  'subject' => 'Test file path attachments', 
+  'text'    => 'Test',
+  'attachment' => [
+    ['filePath'=>'/tmp/foo.jpg', 'filename'=>'test.jpg']
+  ]
+]);
+```
+## From memory
+
+```php
+// Some how load the file to memory
+$binaryFile = '[Binary data]';
+
+$mg->messages()->send('example.com', [
+  'from'    => 'bob@example.com', 
+  'to'      => 'sally@example.com', 
+  'subject' => 'Test memory attachments', 
+  'text'    => 'Test',
+  'attachment' => [
+    ['fileContent'=>$binaryFile, 'filename'=>'test.jpg']
+  ]
+]);
+```
+
+## Inline attachments
+
+```php
+$mg->messages()->send('example.com', [
+  'from'    => 'bob@example.com', 
+  'to'      => 'sally@example.com', 
+  'subject' => 'Test inline attachments', 
+  'text'    => 'Test',
+  'inline' => [
+    ['filePath'=>'/tmp/foo.jpg', 'filename'=>'test.jpg']
+  ]
+]);
+```

doc/index.md

@@ -0,0 +1,335 @@
+# API documentation
+
+This page will document the API classes and ways to properly use the API. These resources will eventually move to
+the official documentation at [https://documentation.mailgun.com](https://documentation.mailgun.com/api_reference.html).
+
+Other relevant documentation pages might be:
+
+* [Attachments](attachments.md)
+* [Pagination](pagination.md)
+* [Message Builder](/src/Message/README.md)
+* [Batch Message](/src/Message/README.md)
+
+## Domain API
+
+#### Get a list of all domains
+
+```php
+$mailgun->domains()->index();
+```
+
+#### Show a single domains
+
+```php
+$mailgun->domains()->show('example.com');
+```
+
+#### Verify a domain
+
+```php
+$mailgun->domains()->verify('example.com');
+```
+
+#### Create a new domain
+
+```php
+$mailgun->domains()->create('new.example.com', 'password', 'disable', '*');
+```
+
+#### Delete a domain
+
+```php
+$mailgun->domains()->delete('example.com');
+```
+
+#### Get credentials for a domain
+
+```php
+$mailgun->domains()->credentials('example.com');
+```
+
+#### Create credentials for a domain
+
+```php
+$mailgun->domains()->createCredential('example.com', 'login', 'password');
+```
+
+#### Update credentials for a domain
+
+```php
+$mailgun->domains()->updateCredential('example.com', 'login', 'password');
+```
+
+#### Delete credentials for a domain
+
+```php
+$mailgun->domains()->deleteCredential('example.com', 'login');
+```
+
+#### Get connection for a domain
+
+```php
+$mailgun->domains()->connection('example.com');
+```
+
+#### Update connection for a domain
+
+```php
+$mailgun->domains()->updateConnection('example.com', true, false);
+```
+
+## Event API
+
+#### Get all events for a domain
+```php
+$mailgun->events()->get('example.com');
+```
+
+## Message API
+
+#### Send a message
+```php
+$parameters = [
+    'from'    => 'bob@example.com',
+    'to'      => 'sally@example.com',
+    'subject' => 'The PHP SDK is awesome!',
+    'text'    => 'It is so simple to send a message.'
+];
+$mailgun->messages()->send('example.com', $parameters);
+```
+#### Send a message with Mime
+
+Below in an example how to create a Mime message with SwiftMailer.
+
+```php
+$message = new Swift_Message('Mail Subject');
+$message->setFrom(['from@exemple.com' => 'Example Inc']);
+$message->setTo(['user0gmail.com' => 'User 0', 'user1@hotmail.com' => 'User 1']);
+// $message->setBcc('admin@example.com'); Do not do this, BCC will be visible for all receipients if you do.
+$message->setCc('invoice@example.com');
+
+$messageBody = 'Look at the <b>fancy</b> HTML body.';
+$message->setBody($messageBody, 'text/html');
+
+// We need all "tos". Incluce the BCC here.
+$to = ['admin@example.com', 'user0gmail.com', 'user1@hotmail.com', 'invoice@example.com']
+
+// Send the message
+$mailgun->messages()->sendMime('example.com', $to, $message->toString(), []);
+```
+
+#### Show a stored message
+
+If you got an URL to a stored message you may get the details by:
+
+```php
+$url = // ...
+$mailgun->messages()->show($url);
+```
+
+## Route API
+
+#### Show all routes
+
+```php
+$mailgun->routes()->index();
+```
+
+#### Show a routes
+
+Get a route by its ID
+
+```php
+$mailgun->routes()->show(4711);
+```
+#### Create a route
+
+```php
+$expression = "match_recipient('.*@gmail.com')";
+$actions = ["forward('alice@example.com')"];
+$description = 'Test route';
+
+$mailgun->routes()->create($expression, $actions, $description);
+```
+
+#### Update a route
+
+```php
+$expression = "match_recipient('.*@gmail.com')";
+$actions = ["forward('alice@example.com')"];
+$description = 'Test route';
+
+$mailgun->routes()->update(4711, $expression, $actions, $description);
+```
+
+#### Delete a route
+```php
+$mailgun->routes()->delete(4711);
+```
+
+## Stats API
+
+#### Get total stats for a domain
+```php
+$mailgun->stats()->total('example.com');
+```
+
+#### Get all stats for a domain
+```php
+$mailgun->stats()->all('example.com');
+```
+
+## Suppression API
+
+The suppression API consists of 3 parts; `Bounce`, `Complaint` and `Unsubscribe`.
+
+### Bounce API
+#### Get all bounces
+```php
+$mailgun->suppressions()->bounces()->index('example.com');
+```
+
+#### Show bounces for a specific address
+```php
+$mailgun->suppressions()->bounces()->show('example.com', 'alice@gmail.com');
+```
+
+#### Create a bounce
+```php
+$mailgun->suppressions()->bounces()->create('example.com', 'alice@gmail.com');
+```
+
+#### Delete a bounce
+```php
+$mailgun->suppressions()->bounces()->delete('example.com', 'alice@gmail.com');
+```
+
+#### Delete all bounces
+```php
+$mailgun->suppressions()->bounces()->deleteAll('example.com');
+```
+
+### Complaint API
+#### Get all complaints
+```php
+$mailgun->suppressions()->complaints()->index('example.com');
+```
+
+#### Show complaints for a specific address
+```php
+$mailgun->suppressions()->complaints()->show('example.com', 'alice@gmail.com');
+```
+
+#### Create a complaint
+```php
+$mailgun->suppressions()->complaints()->create('example.com', 'alice@gmail.com');
+```
+
+#### Delete a complaint
+```php
+$mailgun->suppressions()->complaints()->delete('example.com', 'alice@gmail.com');
+```
+
+#### Delete all complaints
+```php
+$mailgun->suppressions()->complaints()->deleteAll('example.com');
+```
+
+## Unsubscribe API
+
+#### Get all unsubscriptions
+```php
+$mailgun->suppressions()->unsubscribes()->index('example.com');
+```
+
+#### Show unsubscriptions for a specific address
+```php
+$mailgun->suppressions()->unsubscribes()->show('example.com', 'alice@gmail.com');
+```
+
+#### Create an unsubscription
+```php
+$mailgun->suppressions()->unsubscribes()->create('example.com', 'alice@gmail.com');
+```
+
+#### Delete an unsubscription
+```php
+$mailgun->suppressions()->unsubscribes()->delete('example.com', 'alice@gmail.com');
+```
+
+#### Delete all unsubscriptions
+```php
+$mailgun->suppressions()->unsubscribes()->deleteAll('example.com');
+```
+
+## Tag API
+
+#### Show all tags
+```php
+$mailgun->tags()->index('example.com');
+```
+
+#### Show a single tag
+```php
+$mailgun->tags()->show('example.com', 'foo');
+```
+
+#### Update a tag
+```php
+$mailgun->tags()->update('example.com', 'foo', 'description');
+```
+
+#### Show stats for a tag
+```php
+$mailgun->tags()->stats('example.com', 'foo');
+```
+
+#### Delete a tag
+```php
+$mailgun->tags()->delete('example.com', 'foo');
+```
+
+## Webhook API
+#### Verify webhook signature
+```php
+
+$timestamp = $_POST['timestamp'];
+$token = $_POST['token'];
+$signature = $_POST['signature'];
+
+$mailgun = Mailgun::create('my_api_key');
+$valid = $mailgun->webhooks()->verifyWebhookSignature($timestamp, $token, $signature);
+
+if (!$valid) {
+    // Create a 403 response
+
+    exit();
+}
+
+// The signature is valid
+```
+
+#### Show all webhooks
+```php
+$mailgun->webhooks()->index('example.com');
+```
+
+#### Show a single webhooks
+```php
+$mailgun->webhooks()->show('example.com', 'accept');
+```
+
+#### Create a webhooks
+```php
+$mailgun->webhooks()->create('example.com', 'accept', 'https://www.exmple.com/webhook');
+```
+
+#### Update a webhooks
+```php
+$mailgun->webhooks()->update('example.com', 4711, 'https://www.exmple.com/webhook');
+```
+
+#### Delete a webhooks
+```php
+$mailgun->webhooks()->delete('example.com', 4711);
+```

doc/pagination.md

@@ -0,0 +1,17 @@
+# Pagination
+
+Some API endpoints do support pagination. 
+
+```php
+
+/** @var Mailgun\Model\Tag\IndexReponse $response */
+$response = $mailgun->tags()->index('example.com');
+
+// Parse through the first response
+// ...
+
+$nextResponse = $mailgun->tags()->nextPage($response);
+$previousResponse = $mailgun->tags()->previousPage($response);
+$firstResponse = $mailgun->tags()->firstPage($response);
+$lastResponse = $mailgun->tags()->lastPage($response);
+```

phpstan.neon

@@ -0,0 +1,7 @@
+parameters:
+    level: 5
+    paths:
+      - src
+
+    excludes_analyse:
+        - %currentWorkingDirectory%/src/HttpClient/Plugin/HistoryTrait.php

phpunit.xml.dist

@@ -1,19 +1,21 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<phpunit bootstrap="tests/Bootstrap.php"
+<phpunit bootstrap="vendor/autoload.php"
          colors="true"
          processIsolation="false"
          stopOnFailure="false"
-         syntaxCheck="false"
          convertErrorsToExceptions="true"
          convertNoticesToExceptions="true"
-         convertWarningsToExceptions="true"
-         testSuiteLoaderClass="PHPUnit_Runner_StandardTestSuiteLoader">
+         convertWarningsToExceptions="true">
 
     <testsuites>
-        <testsuite>
-            <directory>tests/Mailgun/Tests</directory>
+        <testsuite name="Mailgun test suite">
+            <directory>tests</directory>
         </testsuite>
     </testsuites>
 
-
+    <filter>
+        <whitelist processUncoveredFilesFromWhitelist="true">
+            <directory suffix=".php">src</directory>
+        </whitelist>
+    </filter>
 </phpunit>

src/Api/Attachment.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class Attachment extends HttpApi
+{
+    /**
+     * @return ResponseInterface
+     */
+    public function show(string $url)
+    {
+        Assert::stringNotEmpty($url);
+        Assert::regex($url, '@https://.*mailgun\.(net|org)/v.+@');
+        Assert::regex($url, '|/attachments/[0-9]+|');
+
+        $response = $this->httpGet($url);
+
+        if (200 !== $response->getStatusCode()) {
+            $this->handleErrors($response);
+        }
+
+        return $response;
+    }
+}

src/Api/Domain.php

@@ -0,0 +1,288 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Model\Domain\ConnectionResponse;
+use Mailgun\Model\Domain\CreateCredentialResponse;
+use Mailgun\Model\Domain\CreateResponse;
+use Mailgun\Model\Domain\CredentialResponse;
+use Mailgun\Model\Domain\DeleteCredentialResponse;
+use Mailgun\Model\Domain\DeleteResponse;
+use Mailgun\Model\Domain\IndexResponse;
+use Mailgun\Model\Domain\ShowResponse;
+use Mailgun\Model\Domain\UpdateConnectionResponse;
+use Mailgun\Model\Domain\UpdateCredentialResponse;
+use Mailgun\Model\Domain\VerifyResponse;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @see https://documentation.mailgun.com/api-domains.html
+ *
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+class Domain extends HttpApi
+{
+    /**
+     * Returns a list of domains on the account.
+     *
+     *
+     * @return IndexResponse
+     */
+    public function index(int $limit = 100, int $skip = 0)
+    {
+        Assert::range($limit, 1, 1000);
+
+        $params = [
+            'limit' => $limit,
+            'skip' => $skip,
+        ];
+
+        $response = $this->httpGet('/v3/domains', $params);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * Returns a single domain.
+     *
+     * @param string $domain name of the domain
+     *
+     * @return ShowResponse|array|ResponseInterface
+     */
+    public function show(string $domain)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpGet(sprintf('/v3/domains/%s', $domain));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * Creates a new domain for the account.
+     * See below for spam filtering parameter information.
+     * {@link https://documentation.mailgun.com/user_manual.html#um-spam-filter}.
+     *
+     * @see https://documentation.mailgun.com/en/latest/api-domains.html#domains
+     *
+     * @param string $domain     name of the domain
+     * @param string $smtpPass   password for SMTP authentication
+     * @param string $spamAction `disable` or `tag` - inbound spam filtering
+     * @param bool   $wildcard   domain will accept email for subdomains
+     *
+     * @return CreateResponse|array|ResponseInterface
+     */
+    public function create(string $domain, string $smtpPass = null, string $spamAction = null, bool $wildcard = null)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $params['name'] = $domain;
+
+        if (!empty($smtpPass)) {
+            Assert::stringNotEmpty($smtpPass);
+
+            $params['smtp_password'] = $smtpPass;
+        }
+
+        if (!empty($spamAction)) {
+            // TODO(sean.johnson): Extended spam filter input validation.
+            Assert::stringNotEmpty($spamAction);
+
+            $params['spam_action'] = $spamAction;
+        }
+
+        if (null !== $wildcard) {
+            Assert::boolean($wildcard);
+
+            $params['wildcard'] = $wildcard ? 'true' : 'false';
+        }
+
+        $response = $this->httpPost('/v3/domains', $params);
+
+        return $this->hydrateResponse($response, CreateResponse::class);
+    }
+
+    /**
+     * Removes a domain from the account.
+     * WARNING: This action is irreversible! Be cautious!
+     *
+     * @param string $domain name of the domain
+     *
+     * @return DeleteResponse|array|ResponseInterface
+     */
+    public function delete(string $domain)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpDelete(sprintf('/v3/domains/%s', $domain));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+
+    /**
+     * Returns a list of SMTP credentials for the specified domain.
+     *
+     * @param string $domain name of the domain
+     * @param int    $limit  Number of credentials to return
+     * @param int    $skip   Number of credentials to omit from the list
+     *
+     * @return CredentialResponse
+     */
+    public function credentials(string $domain, int $limit = 100, int $skip = 0)
+    {
+        Assert::stringNotEmpty($domain);
+        $params = [
+            'limit' => $limit,
+            'skip' => $skip,
+        ];
+
+        $response = $this->httpGet(sprintf('/v3/domains/%s/credentials', $domain), $params);
+
+        return $this->hydrateResponse($response, CredentialResponse::class);
+    }
+
+    /**
+     * Create a new SMTP credential pair for the specified domain.
+     *
+     * @param string $domain   name of the domain
+     * @param string $login    SMTP Username
+     * @param string $password SMTP Password. Length min 5, max 32.
+     *
+     * @return CreateCredentialResponse|array|ResponseInterface
+     */
+    public function createCredential(string $domain, string $login, string $password)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($login);
+        Assert::stringNotEmpty($password);
+        Assert::lengthBetween($password, 5, 32, 'SMTP password must be between 5 and 32 characters.');
+
+        $params = [
+            'login' => $login,
+            'password' => $password,
+        ];
+
+        $response = $this->httpPost(sprintf('/v3/domains/%s/credentials', $domain), $params);
+
+        return $this->hydrateResponse($response, CreateCredentialResponse::class);
+    }
+
+    /**
+     * Update a set of SMTP credentials for the specified domain.
+     *
+     * @param string $domain name of the domain
+     * @param string $login  SMTP Username
+     * @param string $pass   New SMTP Password. Length min 5, max 32.
+     *
+     * @return UpdateCredentialResponse|array|ResponseInterface
+     */
+    public function updateCredential(string $domain, string $login, string $pass)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($login);
+        Assert::stringNotEmpty($pass);
+        Assert::lengthBetween($pass, 5, 32, 'SMTP password must be between 5 and 32 characters.');
+
+        $params = [
+            'password' => $pass,
+        ];
+
+        $response = $this->httpPut(sprintf('/v3/domains/%s/credentials/%s', $domain, $login), $params);
+
+        return $this->hydrateResponse($response, UpdateCredentialResponse::class);
+    }
+
+    /**
+     * Remove a set of SMTP credentials from the specified domain.
+     *
+     * @param string $domain name of the domain
+     * @param string $login  SMTP Username
+     *
+     * @return DeleteCredentialResponse|array|ResponseInterface
+     */
+    public function deleteCredential(string $domain, string $login)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($login);
+
+        $response = $this->httpDelete(
+            sprintf(
+                '/v3/domains/%s/credentials/%s',
+                $domain,
+                $login
+            )
+        );
+
+        return $this->hydrateResponse($response, DeleteCredentialResponse::class);
+    }
+
+    /**
+     * Returns delivery connection settings for the specified domain.
+     *
+     * @param string $domain name of the domain
+     *
+     * @return ConnectionResponse|ResponseInterface
+     */
+    public function connection(string $domain)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpGet(sprintf('/v3/domains/%s/connection', $domain));
+
+        return $this->hydrateResponse($response, ConnectionResponse::class);
+    }
+
+    /**
+     * Updates the specified delivery connection settings for the specified domain.
+     * If a parameter is passed in as null, it will not be updated.
+     *
+     * @param string    $domain     name of the domain
+     * @param bool|null $requireTLS enforces that messages are sent only over a TLS connection
+     * @param bool|null $noVerify   disables TLS certificate and hostname verification
+     *
+     * @return UpdateConnectionResponse|array|ResponseInterface
+     */
+    public function updateConnection(string $domain, ?bool $requireTLS, ?bool $noVerify)
+    {
+        Assert::stringNotEmpty($domain);
+        $params = [];
+
+        if (null !== $requireTLS) {
+            $params['require_tls'] = $requireTLS ? 'true' : 'false';
+        }
+
+        if (null !== $noVerify) {
+            $params['skip_verification'] = $noVerify ? 'true' : 'false';
+        }
+
+        $response = $this->httpPut(sprintf('/v3/domains/%s/connection', $domain), $params);
+
+        return $this->hydrateResponse($response, UpdateConnectionResponse::class);
+    }
+
+    /**
+     * Returns a single domain.
+     *
+     * @param string $domain name of the domain
+     *
+     * @return VerifyResponse|array|ResponseInterface
+     */
+    public function verify(string $domain)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpPut(sprintf('/v3/domains/%s/verify', $domain));
+
+        return $this->hydrateResponse($response, VerifyResponse::class);
+    }
+}

src/Api/EmailValidation.php

@@ -0,0 +1,97 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Exception\HttpClientException;
+use Mailgun\Exception\HttpServerException;
+use Mailgun\Exception\InvalidArgumentException;
+use Mailgun\Model\EmailValidation\ParseResponse;
+use Mailgun\Model\EmailValidation\ValidateResponse;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-email-validation.html
+ *
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+class EmailValidation extends HttpApi
+{
+    /**
+     * Addresses are validated based off defined checks.
+     *
+     * This operation is only accessible with the private API key and not subject to the daily usage limits.
+     *
+     * @param string $address             An email address to validate. Maximum: 512 characters.
+     * @param bool   $mailboxVerification If set to true, a mailbox verification check will be performed
+     *                                    against the address. The default is False.
+     *
+     * @throws InvalidArgumentException Thrown when local validation returns an error
+     * @throws HttpClientException      Thrown when there's an error on Client side
+     * @throws HttpServerException      Thrown when there's an error on Server side
+     * @throws \Exception               Thrown when we don't catch a Client or Server side Exception
+     *
+     * @return ValidateResponse|ResponseInterface
+     */
+    public function validate(string $address, bool $mailboxVerification = false)
+    {
+        Assert::stringNotEmpty($address);
+
+        $params = [
+            'address' => $address,
+            'mailbox_verification' => $mailboxVerification,
+        ];
+
+        $response = $this->httpGet('/address/private/validate', $params);
+
+        return $this->hydrateResponse($response, ValidateResponse::class);
+    }
+
+    /**
+     * Parses a delimiter-separated list of email addresses into two lists: parsed addresses and unparsable portions.
+     *
+     * The parsed addresses are a list of addresses that are syntactically valid
+     * (and optionally pass DNS and ESP specific grammar checks).
+     *
+     * The unparsable list is a list of character sequences that could not be parsed
+     * (or optionally failed DNS or ESP specific grammar checks).
+     *
+     * Delimiter characters are comma (,) and semicolon (;).
+     *
+     * This operation is only accessible with the private API key and not subject to the daily usage limits.
+     *
+     * @param string $addresses  A delimiter separated list of addresses. Maximum: 8000 characters.
+     * @param bool   $syntaxOnly Perform only syntax checks or DNS and ESP specific validation as well.
+     *                           The default is True.
+     *
+     * @throws InvalidArgumentException Thrown when local validation returns an error
+     * @throws HttpClientException      Thrown when there's an error on Client side
+     * @throws HttpServerException      Thrown when there's an error on Server side
+     * @throws \Exception               Thrown when we don't catch a Client or Server side Exception
+     *
+     * @return ParseResponse|ResponseInterface
+     */
+    public function parse(string $addresses, bool $syntaxOnly = true)
+    {
+        Assert::stringNotEmpty($addresses);
+        Assert::maxLength($addresses, 8000);
+
+        $params = [
+            'addresses' => $addresses,
+            'syntax_only' => $syntaxOnly,
+        ];
+
+        $response = $this->httpGet('/address/private/parse', $params);
+
+        return $this->hydrateResponse($response, ParseResponse::class);
+    }
+}

src/Api/Event.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Model\Event\EventResponse;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-events.html
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class Event extends HttpApi
+{
+    use Pagination;
+
+    /**
+     * @return EventResponse
+     */
+    public function get(string $domain, array $params = [])
+    {
+        Assert::stringNotEmpty($domain);
+
+        if (array_key_exists('limit', $params)) {
+            Assert::range($params['limit'], 1, 300);
+        }
+
+        $response = $this->httpGet(sprintf('/v3/%s/events', $domain), $params);
+
+        return $this->hydrateResponse($response, EventResponse::class);
+    }
+}

src/Api/HttpApi.php

@@ -0,0 +1,219 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Exception\UnknownErrorException;
+use Mailgun\Hydrator\Hydrator;
+use Mailgun\Hydrator\NoopHydrator;
+use Mailgun\Exception\HttpClientException;
+use Mailgun\Exception\HttpServerException;
+use Mailgun\HttpClient\RequestBuilder;
+use Psr\Http\Client as Psr18;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+abstract class HttpApi
+{
+    /**
+     * The HTTP client.
+     *
+     * @var ClientInterface
+     */
+    protected $httpClient;
+
+    /**
+     * @var Hydrator|null
+     */
+    protected $hydrator;
+
+    /**
+     * @var RequestBuilder
+     */
+    protected $requestBuilder;
+
+    public function __construct(ClientInterface $httpClient, RequestBuilder $requestBuilder, Hydrator $hydrator)
+    {
+        $this->httpClient = $httpClient;
+        $this->requestBuilder = $requestBuilder;
+        if (!$hydrator instanceof NoopHydrator) {
+            $this->hydrator = $hydrator;
+        }
+    }
+
+    /**
+     * @return mixed|ResponseInterface
+     *
+     * @throws \Exception
+     */
+    protected function hydrateResponse(ResponseInterface $response, string $class)
+    {
+        if (null === $this->hydrator) {
+            return $response;
+        }
+
+        if (200 !== $response->getStatusCode() && 201 !== $response->getStatusCode()) {
+            $this->handleErrors($response);
+        }
+
+        return $this->hydrator->hydrate($response, $class);
+    }
+
+    /**
+     * Throw the correct exception for this error.
+     *
+     * @throws \Exception
+     */
+    protected function handleErrors(ResponseInterface $response)
+    {
+        $statusCode = $response->getStatusCode();
+        switch ($statusCode) {
+            case 400:
+                throw HttpClientException::badRequest($response);
+            case 401:
+                throw HttpClientException::unauthorized($response);
+            case 402:
+                throw HttpClientException::requestFailed($response);
+            case 403:
+                throw  HttpClientException::forbidden($response);
+            case 404:
+                throw HttpClientException::notFound($response);
+            case 413:
+                throw HttpClientException::payloadTooLarge($response);
+            case 500 <= $statusCode:
+                throw HttpServerException::serverError($statusCode);
+            default:
+                throw new UnknownErrorException();
+        }
+    }
+
+    /**
+     * Send a GET request with query parameters.
+     *
+     * @param string $path           Request path
+     * @param array  $parameters     GET parameters
+     * @param array  $requestHeaders Request Headers
+     */
+    protected function httpGet(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
+    {
+        if (count($parameters) > 0) {
+            $path .= '?'.http_build_query($parameters);
+        }
+
+        try {
+            $response = $this->httpClient->sendRequest(
+                $this->requestBuilder->create('GET', $path, $requestHeaders)
+            );
+        } catch (Psr18\NetworkExceptionInterface $e) {
+            throw HttpServerException::networkError($e);
+        }
+
+        return $response;
+    }
+
+    /**
+     * Send a POST request with parameters.
+     *
+     * @param string $path           Request path
+     * @param array  $parameters     POST parameters
+     * @param array  $requestHeaders Request headers
+     */
+    protected function httpPost(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
+    {
+        return $this->httpPostRaw($path, $this->createRequestBody($parameters), $requestHeaders);
+    }
+
+    /**
+     * Send a POST request with raw data.
+     *
+     * @param string       $path           Request path
+     * @param array|string $body           Request body
+     * @param array        $requestHeaders Request headers
+     */
+    protected function httpPostRaw(string $path, $body, array $requestHeaders = []): ResponseInterface
+    {
+        try {
+            $response = $this->httpClient->sendRequest(
+                $this->requestBuilder->create('POST', $path, $requestHeaders, $body)
+            );
+        } catch (Psr18\NetworkExceptionInterface $e) {
+            throw HttpServerException::networkError($e);
+        }
+
+        return $response;
+    }
+
+    /**
+     * Send a PUT request.
+     *
+     * @param string $path           Request path
+     * @param array  $parameters     PUT parameters
+     * @param array  $requestHeaders Request headers
+     */
+    protected function httpPut(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
+    {
+        try {
+            $response = $this->httpClient->sendRequest(
+                $this->requestBuilder->create('PUT', $path, $requestHeaders, $this->createRequestBody($parameters))
+            );
+        } catch (Psr18\NetworkExceptionInterface $e) {
+            throw HttpServerException::networkError($e);
+        }
+
+        return $response;
+    }
+
+    /**
+     * Send a DELETE request.
+     *
+     * @param string $path           Request path
+     * @param array  $parameters     DELETE parameters
+     * @param array  $requestHeaders Request headers
+     */
+    protected function httpDelete(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface
+    {
+        try {
+            $response = $this->httpClient->sendRequest(
+                $this->requestBuilder->create('DELETE', $path, $requestHeaders, $this->createRequestBody($parameters))
+            );
+        } catch (Psr18\NetworkExceptionInterface $e) {
+            throw HttpServerException::networkError($e);
+        }
+
+        return $response;
+    }
+
+    /**
+     * Prepare a set of key-value-pairs to be encoded as multipart/form-data.
+     *
+     * @param array $parameters Request parameters
+     */
+    private function createRequestBody(array $parameters): array
+    {
+        $resources = [];
+        foreach ($parameters as $key => $values) {
+            if (!is_array($values)) {
+                $values = [$values];
+            }
+            foreach ($values as $value) {
+                $resources[] = [
+                    'name' => $key,
+                    'content' => $value,
+                ];
+            }
+        }
+
+        return $resources;
+    }
+}

src/Api/Ip.php

@@ -0,0 +1,112 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Model\Ip\IndexResponse;
+use Mailgun\Model\Ip\ShowResponse;
+use Mailgun\Model\Ip\UpdateResponse;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-ips.html
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class Ip extends HttpApi
+{
+    /**
+     * Returns a list of IPs.
+     *
+     *
+     * @return IndexResponse|ResponseInterface
+     */
+    public function index(bool $dedicated = false)
+    {
+        Assert::boolean($dedicated);
+
+        $params = [
+            'dedicated' => $dedicated,
+        ];
+
+        $response = $this->httpGet('/v3/ips', $params);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * Returns a list of IPs assigned to a domain.
+     *
+     *
+     * @return IndexResponse|ResponseInterface
+     */
+    public function domainIndex(string $domain)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpGet(sprintf('/v3/domains/%s/ip', $domain));
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * Returns a single ip.
+     *
+     *
+     * @return ShowResponse|ResponseInterface
+     */
+    public function show(string $ip)
+    {
+        Assert::ip($ip);
+
+        $response = $this->httpGet(sprintf('/v3/ips/%s', $ip));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * Assign a dedicated IP to the domain specified.
+     *
+     *
+     * @return UpdateResponse|ResponseInterface
+     */
+    public function assign(string $domain, string $ip)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::ip($ip);
+
+        $params = [
+            'id' => $ip,
+        ];
+
+        $response = $this->httpPost(sprintf('/v3/domains/%s/ips', $domain), $params);
+
+        return $this->hydrateResponse($response, UpdateResponse::class);
+    }
+
+    /**
+     * Unassign an IP from the domain specified.
+     *
+
+     *
+     * @return UpdateResponse|ResponseInterface
+     */
+    public function unassign(string $domain, string $ip)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::ip($ip);
+
+        $response = $this->httpDelete(sprintf('/v3/domains/%s/ips/%s', $domain, $ip));
+
+        return $this->hydrateResponse($response, UpdateResponse::class);
+    }
+}

src/Api/MailingList.php

@@ -0,0 +1,155 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Api\MailingList\Member;
+use Mailgun\Assert;
+use Mailgun\Model\MailingList\CreateResponse;
+use Mailgun\Model\MailingList\DeleteResponse;
+use Mailgun\Model\MailingList\PagesResponse;
+use Mailgun\Model\MailingList\ShowResponse;
+use Mailgun\Model\MailingList\UpdateResponse;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-mailinglists.html
+ */
+class MailingList extends HttpApi
+{
+    public function member(): Member
+    {
+        return new Member($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    /**
+     * Returns a paginated list of mailing lists on the domain.
+     *
+     * @param int $limit Maximum number of records to return (optional: 100 by default)
+     *
+     * @return PagesResponse
+     *
+     * @throws \Exception
+     */
+    public function pages(int $limit = 100)
+    {
+        Assert::range($limit, 1, 1000);
+
+        $params = [
+            'limit' => $limit,
+        ];
+
+        $response = $this->httpGet('/v3/lists/pages', $params);
+
+        return $this->hydrateResponse($response, PagesResponse::class);
+    }
+
+    /**
+     * Creates a new mailing list on the current domain.
+     *
+     * @param string $address     Address for the new mailing list
+     * @param string $name        Name for the new mailing list (optional)
+     * @param string $description Description for the new mailing list (optional)
+     * @param string $accessLevel List access level, one of: readonly (default), members, everyone
+     *
+     * @return CreateResponse
+     *
+     * @throws \Exception
+     */
+    public function create(string $address, string $name = null, string $description = null, string $accessLevel = 'readonly')
+    {
+        Assert::stringNotEmpty($address);
+        Assert::nullOrStringNotEmpty($name);
+        Assert::nullOrStringNotEmpty($description);
+        Assert::oneOf($accessLevel, ['readonly', 'members', 'everyone']);
+
+        $params = [
+            'address' => $address,
+            'name' => $name,
+            'description' => $description,
+            'access_level' => $accessLevel,
+        ];
+
+        $response = $this->httpPost('/v3/lists', $params);
+
+        return $this->hydrateResponse($response, CreateResponse::class);
+    }
+
+    /**
+     * Returns a single mailing list.
+     *
+     * @param string $address Address of the mailing list
+     *
+     * @return ShowResponse
+     *
+     * @throws \Exception
+     */
+    public function show(string $address)
+    {
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpGet(sprintf('/v3/lists/%s', $address));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * Updates a mailing list.
+     *
+     * @param string $address    Address of the mailing list
+     * @param array  $parameters Array of field => value pairs to update
+     *
+     * @return UpdateResponse
+     *
+     * @throws \Exception
+     */
+    public function update(string $address, array $parameters = [])
+    {
+        Assert::stringNotEmpty($address);
+        Assert::isArray($parameters);
+
+        foreach ($parameters as $field => $value) {
+            switch ($field) {
+                case 'address':
+                case 'name':
+                case 'description':
+                    Assert::stringNotEmpty($value);
+
+                    break;
+                case 'access_level':
+                    Assert::oneOf($value, ['readonly', 'members', 'everyone']);
+
+                    break;
+            }
+        }
+
+        $response = $this->httpPut(sprintf('/v3/lists/%s', $address), $parameters);
+
+        return $this->hydrateResponse($response, UpdateResponse::class);
+    }
+
+    /**
+     * Removes a mailing list from the domain.
+     *
+     * @param string $address Address of the mailing list
+     *
+     * @return DeleteResponse
+     *
+     * @throws \Exception
+     */
+    public function delete(string $address)
+    {
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpDelete(sprintf('/v3/lists/%s', $address));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Api/MailingList/Member.php

@@ -0,0 +1,242 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api\MailingList;
+
+use Mailgun\Api\HttpApi;
+use Mailgun\Assert;
+use Mailgun\Exception\InvalidArgumentException;
+use Mailgun\Model\MailingList\Member\CreateResponse;
+use Mailgun\Model\MailingList\Member\DeleteResponse;
+use Mailgun\Model\MailingList\Member\IndexResponse;
+use Mailgun\Model\MailingList\Member\ShowResponse;
+use Mailgun\Model\MailingList\Member\UpdateResponse;
+use Mailgun\Model\MailingList\UpdateResponse as MailingListUpdateResponse;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-mailinglists.html
+ */
+class Member extends HttpApi
+{
+    /**
+     * Returns a paginated list of members of the mailing list.
+     *
+     * @param string    $address    Address of the mailing list
+     * @param int       $limit      Maximum number of records to return (optional: 100 by default)
+     * @param bool|null $subscribed `true` to lists subscribed, `false` for unsubscribed. list all if null
+     *
+     * @return IndexResponse
+     *
+     * @throws \Exception
+     */
+    public function index(string $address, int $limit = 100, bool $subscribed = null)
+    {
+        Assert::stringNotEmpty($address);
+        Assert::greaterThan($limit, 0);
+
+        $params = [
+            'limit' => $limit,
+        ];
+
+        if (true === $subscribed) {
+            $params['subscribed'] = 'yes';
+        } elseif (false === $subscribed) {
+            $params['subscribed'] = 'no';
+        }
+
+        $response = $this->httpGet(sprintf('/v3/lists/%s/members/pages', $address), $params);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * Shows a single member of the mailing list.
+     *
+     * @param string $list    Address of the mailing list
+     * @param string $address Address of the member
+     *
+     * @return ShowResponse
+     *
+     * @throws \Exception
+     */
+    public function show(string $list, string $address)
+    {
+        Assert::stringNotEmpty($list);
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpGet(sprintf('/v3/lists/%s/members/%s', $list, $address));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * Creates (or updates) a member of the mailing list.
+     *
+     * @param string $list       Address of the mailing list
+     * @param string $address    Address for the member
+     * @param string $name       Name for the member (optional)
+     * @param array  $vars       Array of field => value pairs to store additional data
+     * @param bool   $subscribed `true` to add as subscribed (default), `false` as unsubscribed
+     * @param bool   $upsert     `true` to update member if present, `false` to raise error in case of a duplicate member (default)
+     *
+     * @return CreateResponse
+     *
+     * @throws \Exception
+     */
+    public function create(string $list, string $address, string $name = null, array $vars = [], bool $subscribed = true, bool $upsert = false)
+    {
+        Assert::stringNotEmpty($list);
+        Assert::stringNotEmpty($address);
+        Assert::nullOrStringNotEmpty($name);
+
+        $params = [
+            'address' => $address,
+            'name' => $name,
+            'vars' => \json_encode($vars),
+            'subscribed' => $subscribed ? 'yes' : 'no',
+            'upsert' => $upsert ? 'yes' : 'no',
+        ];
+
+        $response = $this->httpPost(sprintf('/v3/lists/%s/members', $list), $params);
+
+        return $this->hydrateResponse($response, CreateResponse::class);
+    }
+
+    /**
+     * Adds multiple members (up to 1000) to the mailing list.
+     *
+     * @param string $list    Address of the mailing list
+     * @param array  $members Array of members, each item should be either a single string address or an array of member properties
+     * @param bool   $upsert  `true` to update existing members, `false` (default) to ignore duplicates
+     *
+     * @return UpdateResponse
+     *
+     * @throws \Exception
+     */
+    public function createMultiple(string $list, array $members, $upsert = false)
+    {
+        Assert::stringNotEmpty($list);
+        Assert::isArray($members);
+
+        // workaround for webmozart/asserts <= 1.2
+        if (count($members) > 1000) {
+            throw new InvalidArgumentException(sprintf(
+                'Expected an Array to contain at most %2$d elements. Got: %d',
+                1000,
+                count($members)
+            ));
+        }
+
+        foreach ($members as $data) {
+            if (is_string($data)) {
+                Assert::stringNotEmpty($data);
+                // single address - no additional validation required
+                continue;
+            }
+
+            Assert::isArray($data);
+
+            foreach ($data as $field => &$value) {
+                switch ($field) {
+                    case 'address':
+                        Assert::stringNotEmpty($value);
+
+                        break;
+                    case 'vars':
+                        if (is_array($value)) {
+                            $value = json_encode($value);
+                        }
+                        // We should assert that "vars"'s $value is a string.
+                        // no break
+                    case 'name':
+                        Assert::string($value);
+
+                        break;
+                    case 'subscribed':
+                        Assert::oneOf($value, ['yes', 'no']);
+
+                        break;
+                }
+            }
+        }
+
+        $params = [
+            'members' => json_encode($members),
+            'upsert' => $upsert ? 'yes' : 'no',
+        ];
+
+        $response = $this->httpPost(sprintf('/v3/lists/%s/members.json', $list), $params);
+
+        return $this->hydrateResponse($response, MailingListUpdateResponse::class);
+    }
+
+    /**
+     * Updates a member on the mailing list.
+     *
+     * @param string $list       Address of the mailing list
+     * @param string $address    Address of the member
+     * @param array  $parameters Array of key => value pairs to update
+     *
+     * @return UpdateResponse
+     *
+     * @throws \Exception
+     */
+    public function update(string $list, string $address, array $parameters = [])
+    {
+        Assert::stringNotEmpty($list);
+        Assert::stringNotEmpty($address);
+        Assert::isArray($parameters);
+
+        foreach ($parameters as $field => $value) {
+            switch ($field) {
+                case 'vars':
+                    if (is_array($value)) {
+                        $value = json_encode($value);
+                    }
+                    // We should assert that "vars"'s $value is a string.
+                    // no break
+                case 'address':
+                case 'name':
+                    Assert::stringNotEmpty($value);
+
+                    break;
+                case 'subscribed':
+                    Assert::oneOf($value, ['yes', 'no']);
+
+                    break;
+            }
+        }
+
+        $response = $this->httpPut(sprintf('/v3/lists/%s/members/%s', $list, $address), $parameters);
+
+        return $this->hydrateResponse($response, UpdateResponse::class);
+    }
+
+    /**
+     * Removes a member from the mailing list.
+     *
+     * @param string $list    Address of the mailing list
+     * @param string $address Address of the member
+     *
+     * @return DeleteResponse
+     *
+     * @throws \Exception
+     */
+    public function delete(string $list, string $address)
+    {
+        Assert::stringNotEmpty($list);
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpDelete(sprintf('/v3/lists/%s/members/%s', $list, $address));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Api/Message.php

@@ -0,0 +1,205 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Exception\InvalidArgumentException;
+use Mailgun\Message\BatchMessage;
+use Mailgun\Model\Message\SendResponse;
+use Mailgun\Model\Message\ShowResponse;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-sending.html
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class Message extends HttpApi
+{
+    public function getBatchMessage(string $domain, bool $autoSend = true): BatchMessage
+    {
+        return new BatchMessage($this, $domain, $autoSend);
+    }
+
+    /**
+     * @see https://documentation.mailgun.com/en/latest/api-sending.html#sending
+     *
+     * @return SendResponse|ResponseInterface
+     */
+    public function send(string $domain, array $params)
+    {
+        Assert::string($domain);
+        Assert::notEmpty($domain);
+        Assert::notEmpty($params);
+
+        $postDataMultipart = [];
+        $fields = ['attachment', 'inline'];
+        foreach ($fields as $fieldName) {
+            if (!isset($params[$fieldName])) {
+                continue;
+            }
+
+            Assert::isArray($params[$fieldName]);
+            foreach ($params[$fieldName] as $file) {
+                $postDataMultipart[] = $this->prepareFile($fieldName, $file);
+            }
+
+            unset($params[$fieldName]);
+        }
+
+        $postDataMultipart = array_merge($this->prepareMultipartParameters($params), $postDataMultipart);
+        try {
+            $response = $this->httpPostRaw(sprintf('/v3/%s/messages', $domain), $postDataMultipart);
+        } finally {
+            $this->closeResources($postDataMultipart);
+        }
+
+        return $this->hydrateResponse($response, SendResponse::class);
+    }
+
+    /**
+     * @see https://documentation.mailgun.com/en/latest/api-sending.html#sending
+     *
+     * @param array  $recipients with all you send emails to. Including bcc and cc
+     * @param string $message    Message filepath or content
+     *
+     * @return SendResponse|ResponseInterface
+     */
+    public function sendMime(string $domain, array $recipients, string  $message, array $params)
+    {
+        Assert::string($domain);
+        Assert::notEmpty($domain);
+        Assert::notEmpty($recipients);
+        Assert::notEmpty($message);
+        Assert::nullOrIsArray($params);
+
+        $params['to'] = $recipients;
+        $postDataMultipart = $this->prepareMultipartParameters($params);
+
+        if (strlen($message) < PHP_MAXPATHLEN && is_file($message)) {
+            $fileData = ['filePath' => $message];
+        } else {
+            $fileData = [
+                'fileContent' => $message,
+                'filename' => 'message',
+            ];
+        }
+        $postDataMultipart[] = $this->prepareFile('message', $fileData);
+        try {
+            $response = $this->httpPostRaw(sprintf('/v3/%s/messages.mime', $domain), $postDataMultipart);
+        } finally {
+            $this->closeResources($postDataMultipart);
+        }
+
+        return $this->hydrateResponse($response, SendResponse::class);
+    }
+
+    /**
+     * Get stored message.
+     *
+     * @see https://documentation.mailgun.com/en/latest/api-sending.html#retrieving-stored-messages
+     *
+     * @param bool $rawMessage if true we will use "Accept: message/rfc2822" header
+     *
+     * @return ShowResponse|ResponseInterface
+     */
+    public function show(string $url, bool $rawMessage = false)
+    {
+        Assert::notEmpty($url);
+
+        $headers = [];
+        if ($rawMessage) {
+            $headers['Accept'] = 'message/rfc2822';
+        }
+
+        $response = $this->httpGet($url, [], $headers);
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * @param array $filePath array('fileContent' => 'content') or array('filePath' => '/foo/bar')
+     *
+     * @throws InvalidArgumentException
+     */
+    private function prepareFile(string $fieldName, array $filePath): array
+    {
+        $filename = isset($filePath['filename']) ? $filePath['filename'] : null;
+        $deleteRequired = false;
+
+        if (isset($filePath['fileContent'])) {
+            // File from memory
+            $filename = tempnam(sys_get_temp_dir(), "MAILGUN_TMP");
+            $resource = fopen($filename, 'r+');
+            fwrite($resource, $filePath['fileContent']);
+            rewind($resource);
+            $deleteRequired = true;
+        } elseif (isset($filePath['filePath'])) {
+            // File form path
+            $path = $filePath['filePath'];
+
+            // Remove leading @ symbol
+            if (0 === strpos($path, '@')) {
+                $path = substr($path, 1);
+            }
+
+            $resource = fopen($path, 'r');
+        } else {
+            throw new InvalidArgumentException('When using a file you need to specify parameter "fileContent" or "filePath"');
+        }
+
+        return [
+            'name' => $fieldName,
+            'content' => $resource,
+            'filename' => $filename,
+            'deleteRequired' => $deleteRequired,
+        ];
+    }
+
+    /**
+     * Prepare multipart parameters. Make sure each POST parameter is split into an array with 'name' and 'content' keys.
+     */
+    private function prepareMultipartParameters(array $params): array
+    {
+        $postDataMultipart = [];
+        foreach ($params as $key => $value) {
+            // If $value is not an array we cast it to an array
+            foreach ((array) $value as $subValue) {
+                $postDataMultipart[] = [
+                    'name' => $key,
+                    'content' => $subValue,
+                ];
+            }
+        }
+
+        return $postDataMultipart;
+    }
+
+    /**
+     * Close open resources.
+     */
+    private function closeResources(array $params): void
+    {
+        foreach ($params as $param) {
+            if (is_array($param) && array_key_exists('content', $param) && is_resource($param['content'])) {
+                fclose($param['content']);
+            }
+            if (is_array($param)) {
+                $isFile = array_key_exists('filename', $param) && is_file($param['filename']);
+                $deleteRequired = $param['deleteRequired'] ?? false;
+                if ($isFile && $deleteRequired) {
+                    unlink($param['filename']);
+                }
+            }
+        }
+    }
+}

src/Api/Pagination.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Model\PagingProvider;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+trait Pagination
+{
+    abstract protected function httpGet(string $path, array $parameters = [], array $requestHeaders = []): ResponseInterface;
+
+    abstract protected function hydrateResponse(ResponseInterface $response, string $className);
+
+    public function nextPage(PagingProvider $response): ?PagingProvider
+    {
+        return $this->getPaginationUrl($response->getNextUrl(), get_class($response));
+    }
+
+    public function previousPage(PagingProvider $response): ?PagingProvider
+    {
+        return $this->getPaginationUrl($response->getPreviousUrl(), get_class($response));
+    }
+
+    public function firstPage(PagingProvider $response): ?PagingProvider
+    {
+        return $this->getPaginationUrl($response->getFirstUrl(), get_class($response));
+    }
+
+    public function lastPage(PagingProvider $response): ?PagingProvider
+    {
+        return $this->getPaginationUrl($response->getLastUrl(), get_class($response));
+    }
+
+    private function getPaginationUrl(string $url, string $class): ?PagingProvider
+    {
+        Assert::stringNotEmpty($class);
+
+        if (empty($url)) {
+            return null;
+        }
+
+        $response = $this->httpGet($url);
+
+        return $this->hydrateResponse($response, $class);
+    }
+}

src/Api/Route.php

@@ -0,0 +1,155 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Model\Route\CreateResponse;
+use Mailgun\Model\Route\DeleteResponse;
+use Mailgun\Model\Route\IndexResponse;
+use Mailgun\Model\Route\ShowResponse;
+use Mailgun\Model\Route\UpdateResponse;
+
+/**
+ * @see https://documentation.mailgun.com/api-routes.html
+ *
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+class Route extends HttpApi
+{
+    /**
+     * Fetches the list of Routes.
+     *
+     * @param int $limit Maximum number of records to return. (100 by default)
+     * @param int $skip  Number of records to skip. (0 by default)
+     *
+     * @return IndexResponse
+     */
+    public function index(int $limit = 100, int $skip = 0)
+    {
+        Assert::greaterThan($limit, 0);
+        Assert::greaterThanEq($skip, 0);
+        Assert::range($limit, 1, 1000);
+
+        $params = [
+            'limit' => $limit,
+            'skip' => $skip,
+        ];
+
+        $response = $this->httpGet('/v3/routes', $params);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * Returns a single Route object based on its ID.
+     *
+     * @param string $routeId Route ID returned by the Routes::index() method
+     *
+     * @return ShowResponse
+     */
+    public function show(string $routeId)
+    {
+        Assert::stringNotEmpty($routeId);
+
+        $response = $this->httpGet(sprintf('/v3/routes/%s', $routeId));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * Creates a new Route.
+     *
+     * @param string $expression  A filter expression like "match_recipient('.*@gmail.com')"
+     * @param array  $actions     Route action. This action is executed when the expression evaluates to True. Example: "forward('alice@example.com')"
+     * @param string $description An arbitrary string
+     * @param int    $priority    Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0.
+     *
+     * @return CreateResponse
+     */
+    public function create(string $expression, array $actions, string $description, int $priority = 0)
+    {
+        Assert::isArray($actions);
+
+        $params = [
+            'priority' => (string) $priority,
+            'expression' => $expression,
+            'action' => $actions,
+            'description' => $description,
+        ];
+
+        $response = $this->httpPost('/v3/routes', $params);
+
+        return $this->hydrateResponse($response, CreateResponse::class);
+    }
+
+    /**
+     * Updates a given Route by ID. All parameters are optional.
+     * This API call only updates the specified fields leaving others unchanged.
+     *
+     * @param string      $routeId     Route ID returned by the Routes::index() method
+     * @param string|null $expression  A filter expression like "match_recipient('.*@gmail.com')"
+     * @param array       $actions     Route action. This action is executed when the expression evaluates to True. Example: "forward('alice@example.com')"
+     * @param string|null $description An arbitrary string
+     * @param int|null    $priority    Integer: smaller number indicates higher priority. Higher priority routes are handled first. Defaults to 0.
+     *
+     * @return UpdateResponse
+     */
+    public function update(
+        string $routeId,
+        string $expression = null,
+        array $actions = [],
+        string $description = null,
+        int $priority = null
+    ) {
+        Assert::stringNotEmpty($routeId);
+        $params = [];
+
+        if (!empty($expression)) {
+            $params['expression'] = trim($expression);
+        }
+
+        foreach ($actions as $action) {
+            Assert::stringNotEmpty($action);
+
+            $params['action'] = isset($params['action']) ? $params['action'] : [];
+            $params['action'][] = $action;
+        }
+
+        if (!empty($description)) {
+            $params['description'] = trim($description);
+        }
+
+        if (!empty($priority)) {
+            $params['priority'] = (string) $priority;
+        }
+
+        $response = $this->httpPut(sprintf('/v3/routes/%s', $routeId), $params);
+
+        return $this->hydrateResponse($response, UpdateResponse::class);
+    }
+
+    /**
+     * Deletes a Route based on the ID.
+     *
+     * @param string $routeId Route ID returned by the Routes::index() method
+     *
+     * @return DeleteResponse
+     */
+    public function delete(string $routeId)
+    {
+        Assert::stringNotEmpty($routeId);
+
+        $response = $this->httpDelete(sprintf('/v3/routes/%s', $routeId));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Api/Stats.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Model\Stats\AllResponse;
+use Mailgun\Model\Stats\TotalResponse;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-stats.html
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class Stats extends HttpApi
+{
+    /**
+     * @return TotalResponse|array
+     */
+    public function total(string $domain, array $params = [])
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpGet(sprintf('/v3/%s/stats/total', rawurlencode($domain)), $params);
+
+        return $this->hydrateResponse($response, TotalResponse::class);
+    }
+
+    /**
+     * @return AllResponse|array
+     */
+    public function all(string $domain, array $params = [])
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpGet(sprintf('/v3/%s/stats', rawurlencode($domain)), $params);
+
+        return $this->hydrateResponse($response, AllResponse::class);
+    }
+}

src/Api/Suppression.php

@@ -0,0 +1,64 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Api\Suppression\Bounce;
+use Mailgun\Api\Suppression\Complaint;
+use Mailgun\Api\Suppression\Unsubscribe;
+use Mailgun\Hydrator\Hydrator;
+use Psr\Http\Client\ClientInterface;
+use Mailgun\HttpClient\RequestBuilder;
+
+/**
+ * @see https://documentation.mailgun.com/api-suppressions.html
+ *
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+class Suppression
+{
+    /**
+     * @var ClientInterface
+     */
+    private $httpClient;
+
+    /**
+     * @var RequestBuilder
+     */
+    private $requestBuilder;
+
+    /**
+     * @var Hydrator
+     */
+    private $hydrator;
+
+    public function __construct(ClientInterface $httpClient, RequestBuilder $requestBuilder, Hydrator $hydrator)
+    {
+        $this->httpClient = $httpClient;
+        $this->requestBuilder = $requestBuilder;
+        $this->hydrator = $hydrator;
+    }
+
+    public function bounces(): Bounce
+    {
+        return new Bounce($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function complaints(): Complaint
+    {
+        return new Complaint($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function unsubscribes(): Unsubscribe
+    {
+        return new Unsubscribe($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+}

src/Api/Suppression/Bounce.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api\Suppression;
+
+use Mailgun\Api\HttpApi;
+use Mailgun\Api\Pagination;
+use Mailgun\Assert;
+use Mailgun\Model\Suppression\Bounce\CreateResponse;
+use Mailgun\Model\Suppression\Bounce\DeleteResponse;
+use Mailgun\Model\Suppression\Bounce\IndexResponse;
+use Mailgun\Model\Suppression\Bounce\ShowResponse;
+
+/**
+ * @see https://documentation.mailgun.com/api-suppressions.html#bounces
+ *
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+class Bounce extends HttpApi
+{
+    use Pagination;
+
+    /**
+     * @param string $domain Domain to list bounces for
+     * @param int    $limit  optional
+     *
+     * @return IndexResponse
+     */
+    public function index(string $domain, int $limit = 100)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::range($limit, 1, 10000, '"Limit" parameter must be between 1 and 10000');
+
+        $params = [
+            'limit' => $limit,
+        ];
+
+        $response = $this->httpGet(sprintf('/v3/%s/bounces', $domain), $params);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * @param string $domain  Domain to show bounce from
+     * @param string $address Bounce address to show
+     *
+     * @return ShowResponse
+     */
+    public function show(string $domain, string $address)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpGet(sprintf('/v3/%s/bounces/%s', $domain, $address));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * @param string $domain  Domain to create a bounce for
+     * @param string $address Address to create a bounce for
+     * @param array  $params  optional
+     *
+     * @return CreateResponse
+     */
+    public function create(string $domain, string $address, array $params = [])
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+
+        $params['address'] = $address;
+
+        $response = $this->httpPost(sprintf('/v3/%s/bounces', $domain), $params);
+
+        return $this->hydrateResponse($response, CreateResponse::class);
+    }
+
+    /**
+     * @param string $domain  Domain to delete a bounce for
+     * @param string $address Bounce address to delete
+     *
+     * @return DeleteResponse
+     */
+    public function delete(string $domain, string $address)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpDelete(sprintf('/v3/%s/bounces/%s', $domain, $address));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+
+    /**
+     * @param string $domain Domain to delete all bounces for
+     *
+     * @return DeleteResponse
+     */
+    public function deleteAll(string $domain)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpDelete(sprintf('/v3/%s/bounces', $domain));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Api/Suppression/Complaint.php

@@ -0,0 +1,118 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api\Suppression;
+
+use Mailgun\Api\HttpApi;
+use Mailgun\Api\Pagination;
+use Mailgun\Assert;
+use Mailgun\Model\Suppression\Complaint\CreateResponse;
+use Mailgun\Model\Suppression\Complaint\DeleteResponse;
+use Mailgun\Model\Suppression\Complaint\IndexResponse;
+use Mailgun\Model\Suppression\Complaint\ShowResponse;
+
+/**
+ * @see https://documentation.mailgun.com/api-suppressions.html#complaints
+ *
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+class Complaint extends HttpApi
+{
+    use Pagination;
+
+    /**
+     * @param string $domain Domain to get complaints for
+     * @param int    $limit  optional
+     *
+     * @return IndexResponse
+     */
+    public function index(string $domain, int $limit = 100)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::range($limit, 1, 10000, 'Limit parameter must be between 1 and 10000');
+
+        $params = [
+            'limit' => $limit,
+        ];
+
+        $response = $this->httpGet(sprintf('/v3/%s/complaints', $domain), $params);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * @param string $domain  Domain to show complaint for
+     * @param string $address Complaint address
+     *
+     * @return ShowResponse
+     */
+    public function show(string $domain, string $address)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+        $response = $this->httpGet(sprintf('/v3/%s/complaints/%s', $domain, $address));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * @param string $domain    Domain to create complaint for
+     * @param string $address   Complaint address
+     * @param string $createdAt (optional) rfc2822 compliant format. (new \DateTime())->format('r')
+     *
+     * @return CreateResponse
+     */
+    public function create(string $domain, string $address, string $createdAt = null)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+
+        $params['address'] = $address;
+        if (null !== $createdAt) {
+            Assert::stringNotEmpty($createdAt);
+            $params['created_at'] = $createdAt;
+        }
+
+        $response = $this->httpPost(sprintf('/v3/%s/complaints', $domain), $params);
+
+        return $this->hydrateResponse($response, CreateResponse::class);
+    }
+
+    /**
+     * @param string $domain  Domain to delete complaint for
+     * @param string $address Complaint address
+     *
+     * @return DeleteResponse
+     */
+    public function delete(string $domain, string $address)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpDelete(sprintf('/v3/%s/complaints/%s', $domain, $address));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+
+    /**
+     * @param string $domain Domain to delete all bounces for
+     *
+     * @return DeleteResponse
+     */
+    public function deleteAll(string $domain)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpDelete(sprintf('/v3/%s/complaints', $domain));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Api/Suppression/Unsubscribe.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api\Suppression;
+
+use Mailgun\Api\HttpApi;
+use Mailgun\Api\Pagination;
+use Mailgun\Assert;
+use Mailgun\Model\Suppression\Unsubscribe\CreateResponse;
+use Mailgun\Model\Suppression\Unsubscribe\DeleteResponse;
+use Mailgun\Model\Suppression\Unsubscribe\IndexResponse;
+use Mailgun\Model\Suppression\Unsubscribe\ShowResponse;
+
+/**
+ * @see https://documentation.mailgun.com/api-suppressions.html#unsubscribes
+ *
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+class Unsubscribe extends HttpApi
+{
+    use Pagination;
+
+    /**
+     * @param string $domain Domain to get unsubscribes for
+     * @param int    $limit  optional
+     *
+     * @return IndexResponse
+     */
+    public function index(string $domain, int $limit = 100)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::range($limit, 1, 10000, 'Limit parameter must be between 1 and 10000');
+
+        $params = [
+            'limit' => $limit,
+        ];
+
+        $response = $this->httpGet(sprintf('/v3/%s/unsubscribes', $domain), $params);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * @param string $domain  Domain to show unsubscribe for
+     * @param string $address Unsubscribe address
+     *
+     * @return ShowResponse
+     */
+    public function show(string $domain, string $address)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpGet(sprintf('/v3/%s/unsubscribes/%s', $domain, $address));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * @param string $domain  Domain to create unsubscribe for
+     * @param string $address Unsubscribe address
+     * @param array  $params  optional
+     *
+     * @return CreateResponse
+     */
+    public function create(string $domain, string $address, array $params = [])
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+
+        $params['address'] = $address;
+
+        $response = $this->httpPost(sprintf('/v3/%s/unsubscribes', $domain), $params);
+
+        return $this->hydrateResponse($response, CreateResponse::class);
+    }
+
+    /**
+     * @param string      $domain  Domain to delete unsubscribe for
+     * @param string      $address Unsubscribe address
+     * @param string|null $tag     Unsubscribe tag
+     *
+     * @return DeleteResponse
+     */
+    public function delete(string $domain, string $address, string $tag = null)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($address);
+        Assert::nullOrStringNotEmpty($tag);
+
+        $params = [];
+        if (!is_null($tag)) {
+            $params['tag'] = $tag;
+        }
+
+        $response = $this->httpDelete(sprintf('/v3/%s/unsubscribes/%s', $domain, $address), $params);
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+
+    /**
+     * @param string $domain Domain to delete all unsubscribes for
+     *
+     * @return DeleteResponse
+     */
+    public function deleteAll(string $domain)
+    {
+        Assert::stringNotEmpty($domain);
+
+        $response = $this->httpDelete(sprintf('/v3/%s/unsubscribes', $domain));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Api/Tag.php

@@ -0,0 +1,157 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Model\Tag\CountryResponse;
+use Mailgun\Model\Tag\DeleteResponse;
+use Mailgun\Model\Tag\DeviceResponse;
+use Mailgun\Model\Tag\IndexResponse;
+use Mailgun\Model\Tag\ProviderResponse;
+use Mailgun\Model\Tag\ShowResponse;
+use Mailgun\Model\Tag\StatisticsResponse;
+use Mailgun\Model\Tag\UpdateResponse;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-tags.html
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class Tag extends HttpApi
+{
+    /**
+     * Returns a list of tags.
+
+     *
+     * @return IndexResponse|ResponseInterface
+     */
+    public function index(string $domain, int $limit = 100)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::range($limit, 1, 1000);
+
+        $params = [
+            'limit' => $limit,
+        ];
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags', $domain), $params);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * Returns a single tag.
+     *
+     * @return ShowResponse|ResponseInterface
+     */
+    public function show(string $domain, string $tag)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags/%s', $domain, $tag));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * Update a tag.
+     *
+     *
+     * @return UpdateResponse|ResponseInterface
+     */
+    public function update(string $domain, string $tag, string $description)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $params = [
+            'description' => $description,
+        ];
+
+        $response = $this->httpPut(sprintf('/v3/%s/tags/%s', $domain, $tag), $params);
+
+        return $this->hydrateResponse($response, UpdateResponse::class);
+    }
+
+    /**
+     * Returns statistics for a single tag.
+     *
+     *
+     * @return StatisticsResponse|ResponseInterface
+     */
+    public function stats(string $domain, string $tag, array $params)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats', $domain, $tag), $params);
+
+        return $this->hydrateResponse($response, StatisticsResponse::class);
+    }
+
+    /**
+     * Removes a tag from the account.
+     *
+     *
+     * @return DeleteResponse|ResponseInterface
+     */
+    public function delete(string $domain, string $tag)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $response = $this->httpDelete(sprintf('/v3/%s/tags/%s', $domain, $tag));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+
+    /**
+     * @return CountryResponse|ResponseInterface
+     */
+    public function countries(string $domain, string $tag)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/countries', $domain, $tag));
+
+        return $this->hydrateResponse($response, CountryResponse::class);
+    }
+
+    /**
+     * @return ProviderResponse|ResponseInterface
+     */
+    public function providers(string $domain, string $tag)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/providers', $domain, $tag));
+
+        return $this->hydrateResponse($response, ProviderResponse::class);
+    }
+
+    /**
+     * @return DeviceResponse|ResponseInterface
+     */
+    public function devices(string $domain, string $tag)
+    {
+        Assert::stringNotEmpty($domain);
+        Assert::stringNotEmpty($tag);
+
+        $response = $this->httpGet(sprintf('/v3/%s/tags/%s/stats/aggregates/devices', $domain, $tag));
+
+        return $this->hydrateResponse($response, DeviceResponse::class);
+    }
+}

src/Api/Webhook.php

@@ -0,0 +1,137 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Api;
+
+use Mailgun\Assert;
+use Mailgun\Hydrator\Hydrator;
+use Mailgun\Model\Webhook\CreateResponse;
+use Mailgun\Model\Webhook\DeleteResponse;
+use Mailgun\Model\Webhook\IndexResponse;
+use Mailgun\Model\Webhook\ShowResponse;
+use Mailgun\Model\Webhook\UpdateResponse;
+use Mailgun\HttpClient\RequestBuilder;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Client\ClientInterface;
+
+/**
+ * @see https://documentation.mailgun.com/en/latest/api-webhooks.html
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class Webhook extends HttpApi
+{
+    /**
+     * @var string
+     */
+    private $apiKey;
+
+    public function __construct(ClientInterface $httpClient, RequestBuilder $requestBuilder, Hydrator $hydrator, string $apiKey)
+    {
+        parent::__construct($httpClient, $requestBuilder, $hydrator);
+        $this->apiKey = $apiKey;
+    }
+
+    /**
+     * This function verifies the webhook signature with your API key to to see if it is authentic.
+     *
+     * If this function returns FALSE, you must not process the request.
+     * You should reject the request with status code 403 Forbidden.
+     */
+    public function verifyWebhookSignature(int $timestamp, string $token, string $signature): bool
+    {
+        if (empty($timestamp) || empty($token) || empty($signature)) {
+            return false;
+        }
+
+        $hmac = hash_hmac('sha256', $timestamp.$token, $this->apiKey);
+
+        if (function_exists('hash_equals')) {
+            // hash_equals is constant time, but will not be introduced until PHP 5.6
+            return hash_equals($hmac, $signature);
+        } else {
+            return $hmac === $signature;
+        }
+    }
+
+    /**
+     * @return IndexResponse|ResponseInterface
+     */
+    public function index(string $domain)
+    {
+        Assert::notEmpty($domain);
+        $response = $this->httpGet(sprintf('/v3/domains/%s/webhooks', $domain));
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * @return ShowResponse|ResponseInterface
+     */
+    public function show(string $domain, string $webhook)
+    {
+        Assert::notEmpty($domain);
+        Assert::notEmpty($webhook);
+        $response = $this->httpGet(sprintf('/v3/domains/%s/webhooks/%s', $domain, $webhook));
+
+        return $this->hydrateResponse($response, ShowResponse::class);
+    }
+
+    /**
+     * @return CreateResponse|ResponseInterface
+     */
+    public function create(string $domain, string $id, string $url)
+    {
+        Assert::notEmpty($domain);
+        Assert::notEmpty($id);
+        Assert::notEmpty($url);
+
+        $params = [
+            'id' => $id,
+            'url' => $url,
+        ];
+
+        $response = $this->httpPost(sprintf('/v3/domains/%s/webhooks', $domain), $params);
+
+        return $this->hydrateResponse($response, CreateResponse::class);
+    }
+
+    /**
+     * @return UpdateResponse|ResponseInterface
+     */
+    public function update(string $domain, string $id, string $url)
+    {
+        Assert::notEmpty($domain);
+        Assert::notEmpty($id);
+        Assert::notEmpty($url);
+
+        $params = [
+            'url' => $url,
+        ];
+
+        $response = $this->httpPut(sprintf('/v3/domains/%s/webhooks/%s', $domain, $id), $params);
+
+        return $this->hydrateResponse($response, UpdateResponse::class);
+    }
+
+    /**
+     * @return DeleteResponse|ResponseInterface
+     */
+    public function delete(string $domain, string $id)
+    {
+        Assert::notEmpty($domain);
+        Assert::notEmpty($id);
+
+        $response = $this->httpDelete(sprintf('/v3/domains/%s/webhooks/%s', $domain, $id));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Assert.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun;
+
+use Mailgun\Exception\InvalidArgumentException;
+
+/**
+ * We need to override Webmozart\Assert because we want to throw our own Exception.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class Assert extends \Webmozart\Assert\Assert
+{
+    protected static function reportInvalidArgument($message)
+    {
+        throw new InvalidArgumentException($message);
+    }
+}

src/Exception.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun;
+
+/**
+ * All Mailgun exception implements this exception.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+interface Exception extends \Throwable
+{
+}

src/Exception/HttpClientException.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Exception;
+
+use Mailgun\Exception;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class HttpClientException extends \RuntimeException implements Exception
+{
+    /**
+     * @var ResponseInterface|null
+     */
+    private $response;
+
+    /**
+     * @var array
+     */
+    private $responseBody = [];
+
+    /**
+     * @var int
+     */
+    private $responseCode;
+
+    public function __construct(string $message, int $code, ResponseInterface $response)
+    {
+        parent::__construct($message, $code);
+
+        $this->response = $response;
+        $this->responseCode = $response->getStatusCode();
+        $body = $response->getBody()->__toString();
+        if (0 !== strpos($response->getHeaderLine('Content-Type'), 'application/json')) {
+            $this->responseBody['message'] = $body;
+        } else {
+            $this->responseBody = json_decode($body, true);
+        }
+    }
+
+    public static function badRequest(ResponseInterface $response)
+    {
+        $body = $response->getBody()->__toString();
+        if (0 !== strpos($response->getHeaderLine('Content-Type'), 'application/json')) {
+            $validationMessage = $body;
+        } else {
+            $jsonDecoded = json_decode($body, true);
+            $validationMessage = isset($jsonDecoded['message']) ? $jsonDecoded['message'] : $body;
+        }
+
+        $message = sprintf("The parameters passed to the API were invalid. Check your inputs!\n\n%s", $validationMessage);
+
+        return new self($message, 400, $response);
+    }
+
+    public static function unauthorized(ResponseInterface $response)
+    {
+        return new self('Your credentials are incorrect.', 401, $response);
+    }
+
+    public static function requestFailed(ResponseInterface $response)
+    {
+        return new self('Parameters were valid but request failed. Try again.', 402, $response);
+    }
+
+    public static function notFound(ResponseInterface $response)
+    {
+        return new self('The endpoint you have tried to access does not exist. Check if the domain matches the domain you have configure on Mailgun.', 404, $response);
+    }
+
+    public static function payloadTooLarge(ResponseInterface $response)
+    {
+        return new self('Payload too large, your total attachment size is too big.', 413, $response);
+    }
+
+    public static function forbidden(ResponseInterface $response)
+    {
+        $body = $response->getBody()->__toString();
+        if (0 !== strpos($response->getHeaderLine('Content-Type'), 'application/json')) {
+            $validationMessage = $body;
+        } else {
+            $jsonDecoded = json_decode($body, true);
+            $validationMessage = isset($jsonDecoded['Error']) ? $jsonDecoded['Error'] : $body;
+        }
+
+        $message = sprintf("Forbidden!\n\n%s", $validationMessage);
+
+        return new self($message, 403, $response);
+    }
+
+    public function getResponse(): ?ResponseInterface
+    {
+        return $this->response;
+    }
+
+    public function getResponseBody(): array
+    {
+        return $this->responseBody;
+    }
+
+    public function getResponseCode(): int
+    {
+        return $this->responseCode;
+    }
+}

src/Exception/HttpServerException.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Exception;
+
+use Mailgun\Exception;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class HttpServerException extends \RuntimeException implements Exception
+{
+    public static function serverError(int $httpStatus = 500)
+    {
+        return new self('An unexpected error occurred at Mailgun\'s servers. Try again later and contact support if the error still exists.', $httpStatus);
+    }
+
+    public static function networkError(\Throwable $previous)
+    {
+        return new self('Mailgun\'s servers are currently unreachable.', 0, $previous);
+    }
+
+    public static function unknownHttpResponseCode(int $code)
+    {
+        return new self(sprintf('Unknown HTTP response code ("%d") received from the API server', $code));
+    }
+}

src/Exception/HydrationException.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Exception;
+
+use Mailgun\Exception;
+
+final class HydrationException extends \RuntimeException implements Exception
+{
+}

src/Exception/InvalidArgumentException.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Exception;
+
+use Mailgun\Exception;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class InvalidArgumentException extends \InvalidArgumentException implements Exception
+{
+}

src/Exception/UnknownErrorException.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Exception;
+
+use Mailgun\Exception;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class UnknownErrorException extends \Exception implements Exception
+{
+}

src/HttpClient/HttpClientConfigurator.php

@@ -0,0 +1,147 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\HttpClient;
+
+use Http\Client\Common\Plugin;
+use Http\Client\Common\PluginClient;
+use Http\Discovery\Psr17FactoryDiscovery;
+use Http\Discovery\Psr18ClientDiscovery;
+use Mailgun\HttpClient\Plugin\History;
+use Mailgun\HttpClient\Plugin\ReplaceUriPlugin;
+use Psr\Http\Client\ClientInterface;
+use Psr\Http\Message\UriFactoryInterface;
+
+/**
+ * Configure a HTTP client.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class HttpClientConfigurator
+{
+    /**
+     * @var string
+     */
+    private $endpoint = 'https://api.mailgun.net';
+
+    /**
+     * If debug is true we will send all the request to the endpoint without appending any path.
+     *
+     * @var bool
+     */
+    private $debug = false;
+
+    /**
+     * @var string
+     */
+    private $apiKey;
+
+    /**
+     * @var UriFactoryInterface
+     */
+    private $uriFactory;
+
+    /**
+     * @var ClientInterface
+     */
+    private $httpClient;
+
+    /**
+     * @var History
+     */
+    private $responseHistory;
+
+    public function __construct()
+    {
+        $this->responseHistory = new History();
+    }
+
+    public function createConfiguredClient(): PluginClient
+    {
+        $plugins = [
+            new Plugin\AddHostPlugin($this->getUriFactory()->createUri($this->endpoint)),
+            new Plugin\HeaderDefaultsPlugin([
+                'User-Agent' => 'mailgun-sdk-php/v2 (https://github.com/mailgun/mailgun-php)',
+                'Authorization' => 'Basic '.base64_encode(sprintf('api:%s', $this->getApiKey())),
+            ]),
+            new Plugin\HistoryPlugin($this->responseHistory),
+        ];
+
+        if ($this->debug) {
+            $plugins[] = new ReplaceUriPlugin($this->getUriFactory()->createUri($this->endpoint));
+        }
+
+        return new PluginClient($this->getHttpClient(), $plugins);
+    }
+
+    public function setDebug(bool $debug): self
+    {
+        $this->debug = $debug;
+
+        return $this;
+    }
+
+    public function setEndpoint(string $endpoint): self
+    {
+        $this->endpoint = $endpoint;
+
+        return $this;
+    }
+
+    public function getApiKey(): string
+    {
+        return $this->apiKey;
+    }
+
+    public function setApiKey(string $apiKey): self
+    {
+        $this->apiKey = $apiKey;
+
+        return $this;
+    }
+
+    private function getUriFactory(): UriFactoryInterface
+    {
+        if (null === $this->uriFactory) {
+            $this->uriFactory = Psr17FactoryDiscovery::findUrlFactory();
+        }
+
+        return $this->uriFactory;
+    }
+
+    public function setUriFactory(UriFactoryInterface $uriFactory): self
+    {
+        $this->uriFactory = $uriFactory;
+
+        return $this;
+    }
+
+    private function getHttpClient(): ClientInterface
+    {
+        if (null === $this->httpClient) {
+            $this->httpClient = Psr18ClientDiscovery::find();
+        }
+
+        return $this->httpClient;
+    }
+
+    public function setHttpClient(ClientInterface $httpClient): self
+    {
+        $this->httpClient = $httpClient;
+
+        return $this;
+    }
+
+    public function getResponseHistory(): History
+    {
+        return $this->responseHistory;
+    }
+}

src/HttpClient/Plugin/History.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\HttpClient\Plugin;
+
+use Http\Client\Common\Plugin\Journal;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * A plugin to remember the last response.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class History implements Journal
+{
+    use HistoryTrait;
+    /**
+     * @var ResponseInterface
+     */
+    private $lastResponse;
+
+    /**
+     * @return ResponseInterface|null
+     */
+    public function getLastResponse()
+    {
+        return $this->lastResponse;
+    }
+
+    public function addSuccess(RequestInterface $request, ResponseInterface $response)
+    {
+        $this->lastResponse = $response;
+    }
+}

src/HttpClient/Plugin/HistoryTrait.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\HttpClient\Plugin;
+
+use Http\Client\Exception;
+use Psr\Http\Client\ClientExceptionInterface;
+use Psr\Http\Message\RequestInterface;
+
+/*
+ * Below is a some code to make the History plugin compatible with both 1.x and 2.x of php-client/client-common
+ */
+if (\interface_exists(\Http\Client\Common\HttpMethodsClientInterface::class)) {
+    /**
+     * @internal code for php-http/client-common:2.x
+     */
+    trait HistoryTrait
+    {
+        public function addFailure(RequestInterface $request, ClientExceptionInterface $exception)
+        {
+        }
+    }
+} else {
+    /**
+     * @internal code for php-http/client-common:1.x
+     */
+    trait HistoryTrait
+    {
+        public function addFailure(RequestInterface $request, Exception $exception)
+        {
+        }
+    }
+}

src/HttpClient/Plugin/ReplaceUriPlugin.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\HttpClient\Plugin;
+
+use Http\Client\Common\Plugin;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\UriInterface;
+
+/**
+ * Replaces a URI with a new one. Good for debugging.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class ReplaceUriPlugin implements Plugin
+{
+    use Plugin\VersionBridgePlugin;
+
+    /**
+     * @var UriInterface
+     */
+    private $uri;
+
+    public function __construct(UriInterface $uri)
+    {
+        $this->uri = $uri;
+    }
+
+    public function doHandleRequest(RequestInterface $request, callable $next, callable $first)
+    {
+        $request = $request->withUri($this->uri);
+
+        return $next($request);
+    }
+}

src/HttpClient/RequestBuilder.php

@@ -0,0 +1,138 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\HttpClient;
+
+use Http\Discovery\Psr17FactoryDiscovery;
+use Http\Message\MultipartStream\MultipartStreamBuilder;
+use Psr\Http\Message\RequestFactoryInterface;
+use Psr\Http\Message\RequestInterface;
+use Psr\Http\Message\StreamFactoryInterface;
+use Psr\Http\Message\StreamInterface;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+class RequestBuilder
+{
+    /**
+     * @var RequestFactoryInterface|null
+     */
+    private $requestFactory;
+
+    /**
+     * @var StreamFactoryInterface|null
+     */
+    private $streamFactory;
+
+    /**
+     * @var MultipartStreamBuilder
+     */
+    private $multipartStreamBuilder;
+
+    /**
+     * Creates a new PSR-7 request.
+     *
+     * @param array|string|null $body Request body. If body is an array we will send a as multipart stream request.
+     *                                If array, each array *item* MUST look like:
+     *                                array (
+     *                                'content' => string|resource|StreamInterface,
+     *                                'name'    => string,
+     *                                'filename'=> string (optional)
+     *                                'headers' => array (optinal) ['header-name' => 'header-value']
+     *                                )
+     */
+    public function create(string $method, string $uri, array $headers = [], $body = null): RequestInterface
+    {
+        if (!is_array($body)) {
+            $stream = $this->getStreamFactory()->createStream((string) $body);
+
+            return $this->createRequest($method, $uri, $headers, $stream);
+        }
+
+        $builder = $this->getMultipartStreamBuilder();
+        foreach ($body as $item) {
+            $name = $item['name'];
+            $content = $item['content'];
+            unset($item['name']);
+            unset($item['content']);
+
+            $builder->addResource($name, $content, $item);
+        }
+
+        $multipartStream = $builder->build();
+        $boundary = $builder->getBoundary();
+        $builder->reset();
+
+        $headers['Content-Type'] = 'multipart/form-data; boundary="'.$boundary.'"';
+
+        return $this->createRequest($method, $uri, $headers, $multipartStream);
+    }
+
+    private function getRequestFactory(): RequestFactoryInterface
+    {
+        if (null === $this->requestFactory) {
+            $this->requestFactory = Psr17FactoryDiscovery::findRequestFactory();
+        }
+
+        return $this->requestFactory;
+    }
+
+    public function setRequestFactory(RequestFactoryInterface $requestFactory): self
+    {
+        $this->requestFactory = $requestFactory;
+
+        return $this;
+    }
+
+    private function getStreamFactory(): StreamFactoryInterface
+    {
+        if (null === $this->streamFactory) {
+            $this->streamFactory = Psr17FactoryDiscovery::findStreamFactory();
+        }
+
+        return $this->streamFactory;
+    }
+
+    public function setStreamFactory(StreamFactoryInterface $streamFactory): self
+    {
+        $this->streamFactory = $streamFactory;
+
+        return $this;
+    }
+
+    private function getMultipartStreamBuilder(): MultipartStreamBuilder
+    {
+        if (null === $this->multipartStreamBuilder) {
+            $this->multipartStreamBuilder = new MultipartStreamBuilder();
+        }
+
+        return $this->multipartStreamBuilder;
+    }
+
+    public function setMultipartStreamBuilder(MultipartStreamBuilder $multipartStreamBuilder): self
+    {
+        $this->multipartStreamBuilder = $multipartStreamBuilder;
+
+        return $this;
+    }
+
+    private function createRequest(string $method, string $uri, array $headers, StreamInterface $stream)
+    {
+        $request = $this->getRequestFactory()->createRequest($method, $uri);
+        $request = $request->withBody($stream);
+        foreach ($headers as $name => $value) {
+            $request = $request->withAddedHeader($name, $value);
+        }
+
+        return $request;
+    }
+}

src/Hydrator/ArrayHydrator.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Hydrator;
+
+use Mailgun\Exception\HydrationException;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Serialize an HTTP response to array.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class ArrayHydrator implements Hydrator
+{
+    /**
+     * @return array
+     */
+    public function hydrate(ResponseInterface $response, string $class)
+    {
+        $body = $response->getBody()->__toString();
+        if (0 !== strpos($response->getHeaderLine('Content-Type'), 'application/json')) {
+            throw new HydrationException('The ArrayHydrator cannot hydrate response with Content-Type:'.$response->getHeaderLine('Content-Type'));
+        }
+
+        $content = json_decode($body, true);
+        if (JSON_ERROR_NONE !== json_last_error()) {
+            throw new HydrationException(sprintf('Error (%d) when trying to json_decode response', json_last_error()));
+        }
+
+        return $content;
+    }
+}

src/Hydrator/Hydrator.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Hydrator;
+
+use Mailgun\Exception\HydrationException;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Deserialize a PSR-7 response to something else.
+ */
+interface Hydrator
+{
+    /**
+     * @throws HydrationException
+     */
+    public function hydrate(ResponseInterface $response, string $class);
+}

src/Hydrator/ModelHydrator.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Hydrator;
+
+use Mailgun\Exception\HydrationException;
+use Mailgun\Model\ApiResponse;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Serialize an HTTP response to domain object.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class ModelHydrator implements Hydrator
+{
+    /**
+     * @return ResponseInterface
+     */
+    public function hydrate(ResponseInterface $response, string $class)
+    {
+        $body = $response->getBody()->__toString();
+        $contentType = $response->getHeaderLine('Content-Type');
+
+        if (0 !== strpos($contentType, 'application/json') && 0 !== strpos($contentType, 'application/octet-stream')) {
+            throw new HydrationException('The ModelHydrator cannot hydrate response with Content-Type: '.$contentType);
+        }
+
+        $data = json_decode($body, true);
+
+        if (JSON_ERROR_NONE !== json_last_error()) {
+            throw new HydrationException(sprintf('Error (%d) when trying to json_decode response', json_last_error()));
+        }
+
+        if (is_subclass_of($class, ApiResponse::class)) {
+            $object = call_user_func($class.'::create', $data);
+        } else {
+            $object = new $class($data);
+        }
+
+        return $object;
+    }
+}

src/Hydrator/NoopHydrator.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Hydrator;
+
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * Do not serialize at all. Just return a PSR-7 response.
+ *
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class NoopHydrator implements Hydrator
+{
+    /**
+     * @throws \LogicException
+     */
+    public function hydrate(ResponseInterface $response, string $class)
+    {
+        throw new \LogicException('The NoopHydrator should never be called');
+    }
+}

src/Mailgun.php

@@ -0,0 +1,141 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun;
+
+use Http\Client\Common\PluginClient;
+use Mailgun\HttpClient\HttpClientConfigurator;
+use Mailgun\HttpClient\Plugin\History;
+use Mailgun\HttpClient\RequestBuilder;
+use Mailgun\Hydrator\ModelHydrator;
+use Mailgun\Hydrator\Hydrator;
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Client\ClientInterface;
+
+/**
+ * This class is the base class for the Mailgun SDK.
+ */
+class Mailgun
+{
+    /**
+     * @var string|null
+     */
+    private $apiKey;
+
+    /**
+     * @var ClientInterface|PluginClient
+     */
+    private $httpClient;
+
+    /**
+     * @var Hydrator
+     */
+    private $hydrator;
+
+    /**
+     * @var RequestBuilder
+     */
+    private $requestBuilder;
+
+    /**
+     * This is a object that holds the last response from the API.
+     *
+     * @var History
+     */
+    private $responseHistory;
+
+    public function __construct(
+        HttpClientConfigurator $configurator,
+        Hydrator $hydrator = null,
+        RequestBuilder $requestBuilder = null
+    ) {
+        $this->requestBuilder = $requestBuilder ?: new RequestBuilder();
+        $this->hydrator = $hydrator ?: new ModelHydrator();
+
+        $this->httpClient = $configurator->createConfiguredClient();
+        $this->apiKey = $configurator->getApiKey();
+        $this->responseHistory = $configurator->getResponseHistory();
+    }
+
+    public static function create(string $apiKey, string $endpoint = 'https://api.mailgun.net'): self
+    {
+        $httpClientConfigurator = (new HttpClientConfigurator())
+            ->setApiKey($apiKey)
+            ->setEndpoint($endpoint);
+
+        return new self($httpClientConfigurator);
+    }
+
+    public function getLastResponse(): ?ResponseInterface
+    {
+        return $this->responseHistory->getLastResponse();
+    }
+
+    public function attachment(): Api\Attachment
+    {
+        return new Api\Attachment($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function domains(): Api\Domain
+    {
+        return new Api\Domain($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function emailValidation(): Api\EmailValidation
+    {
+        return new Api\EmailValidation($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function events(): Api\Event
+    {
+        return new Api\Event($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function ips(): Api\Ip
+    {
+        return new Api\Ip($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function mailingList(): Api\MailingList
+    {
+        return new Api\MailingList($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function messages(): Api\Message
+    {
+        return new Api\Message($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function routes(): Api\Route
+    {
+        return new Api\Route($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function suppressions(): Api\Suppression
+    {
+        return new Api\Suppression($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function stats(): Api\Stats
+    {
+        return new Api\Stats($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function tags(): Api\Tag
+    {
+        return new Api\Tag($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
+
+    public function webhooks(): Api\Webhook
+    {
+        return new Api\Webhook($this->httpClient, $this->requestBuilder, $this->hydrator, $this->apiKey);
+    }
+}

src/Mailgun/Connection/Exceptions/GenericHTTPError.php

@@ -1,25 +0,0 @@
-<?php
-namespace Mailgun\Connection\Exceptions;
-
-class GenericHTTPError extends \Exception
-{
-	protected $httpResponseCode;
-	protected $httpResponseBody;
-	
-	public function __construct($message=null, $response_code=null, $response_body=null, $code=0, \Exception $previous=null) {
-		parent::__construct($message, $code, $previous);
-		
-		$this->httpResponseCode = $response_code;
-		$this->httpResponseBody = $response_body;
-	}
-	
-	public function getHttpResponseCode() {
-		return $this->httpResponseCode;
-	}
-	
-	public function getHttpResponseBody() {
-		return $this->httpResponseBody;
-	}
-}
-
-?>

src/Mailgun/Connection/Exceptions/InvalidCredentials.php

@@ -1,4 +0,0 @@
-<?php
-namespace Mailgun\Connection\Exceptions;
-
-class InvalidCredentials extends \Exception{}

src/Mailgun/Connection/Exceptions/MissingEndpoint.php

@@ -1,4 +0,0 @@
-<?php
-namespace Mailgun\Connection\Exceptions;
-
-class MissingEndpoint extends \Exception{}

src/Mailgun/Connection/Exceptions/MissingRequiredParameters.php

@@ -1,4 +0,0 @@
-<?php
-namespace Mailgun\Connection\Exceptions;
-
-class MissingRequiredParameters extends \Exception{}

src/Mailgun/Connection/Exceptions/NoDomainsConfigured.php

@@ -1,4 +0,0 @@
-<?php
-namespace Mailgun\Connection\Exceptions;
-
-class NoDomainsConfigured extends \Exception{}

src/Mailgun/Connection/RestClient.php

@@ -1,235 +0,0 @@
-<?PHP
-
-namespace Mailgun\Connection;
-
-use GuzzleHttp\Client as Guzzle;
-use GuzzleHttp\Message\ResponseInterface;
-use GuzzleHttp\Post\PostBodyInterface;
-use GuzzleHttp\Post\PostFile;
-use GuzzleHttp\Query;
-use Mailgun\Connection\Exceptions\GenericHTTPError;
-use Mailgun\Connection\Exceptions\InvalidCredentials;
-use Mailgun\Connection\Exceptions\MissingRequiredParameters;
-use Mailgun\Connection\Exceptions\MissingEndpoint;
-use Mailgun\Constants\Api;
-use Mailgun\Constants\ExceptionMessages;
-
-/**
- * This class is a wrapper for the Guzzle (HTTP Client Library).
- */
-class RestClient
-{
-    /**
-     * @var string
-     */
-    private $apiKey;
-
-    /**
-     * @var Guzzle
-     */
-    protected $mgClient;
-
-    /**
-     * @param string $apiKey
-     * @param string $apiEndpoint
-     * @param string $apiVersion
-     * @param bool   $ssl
-     */
-    public function __construct($apiKey, $apiEndpoint, $apiVersion, $ssl)
-    {
-        $this->apiKey = $apiKey;
-        $this->mgClient = new Guzzle([
-            'base_url'=>$this->generateEndpoint($apiEndpoint, $apiVersion, $ssl),
-            'defaults'=>[
-                'auth' => array(Api::API_USER, $this->apiKey),
-                'exceptions' => false,
-                'config' => ['curl' => [ CURLOPT_FORBID_REUSE => true ]],
-                'headers' => [
-                    'User-Agent' => Api::SDK_USER_AGENT.'/'.Api::SDK_VERSION,
-                ],
-            ],
-        ]);
-    }
-
-    /**
-     * @param string $endpointUrl
-     * @param array  $postData
-     * @param array  $files
-     *
-     * @return \stdClass
-     *
-     * @throws GenericHTTPError
-     * @throws InvalidCredentials
-     * @throws MissingEndpoint
-     * @throws MissingRequiredParameters
-     */
-    public function post($endpointUrl, $postData = array(), $files = array())
-    {
-        $request = $this->mgClient->createRequest('POST', $endpointUrl, ['body' => $postData]);
-        /** @var \GuzzleHttp\Post\PostBodyInterface $postBody */
-        $postBody = $request->getBody();
-        $postBody->setAggregator(Query::duplicateAggregator());
-
-        $fields = ['message', 'attachment', 'inline'];
-        foreach ($fields as $fieldName) {
-            if (isset($files[$fieldName])) {
-                if (is_array($files[$fieldName])) {
-                    foreach ($files[$fieldName] as $file) {
-                        $this->addFile($postBody, $fieldName, $file);
-                    }
-                } else {
-                    $this->addFile($postBody, $fieldName, $files[$fieldName]);
-                }
-            }
-        }
-
-        $response = $this->mgClient->send($request);
-
-        return $this->responseHandler($response);
-    }
-
-    /**
-     * @param string $endpointUrl
-     * @param array  $queryString
-     *
-     * @return \stdClass
-     *
-     * @throws GenericHTTPError
-     * @throws InvalidCredentials
-     * @throws MissingEndpoint
-     * @throws MissingRequiredParameters
-     */
-    public function get($endpointUrl, $queryString = array())
-    {
-        $response = $this->mgClient->get($endpointUrl, ['query' => $queryString]);
-
-        return $this->responseHandler($response);
-    }
-
-    /**
-     * @param string $endpointUrl
-     *
-     * @return \stdClass
-     *
-     * @throws GenericHTTPError
-     * @throws InvalidCredentials
-     * @throws MissingEndpoint
-     * @throws MissingRequiredParameters
-     */
-    public function delete($endpointUrl)
-    {
-        $response = $this->mgClient->delete($endpointUrl);
-
-        return $this->responseHandler($response);
-    }
-
-    /**
-     * @param string $endpointUrl
-     * @param array  $putData
-     *
-     * @return \stdClass
-     *
-     * @throws GenericHTTPError
-     * @throws InvalidCredentials
-     * @throws MissingEndpoint
-     * @throws MissingRequiredParameters
-     */
-    public function put($endpointUrl, $putData)
-    {
-        $request = $this->mgClient->createRequest('PUT', $endpointUrl, ['body' => $putData]);
-        /** @var \GuzzleHttp\Post\PostBodyInterface $postBody */
-        $postBody = $request->getBody();
-        $postBody->setAggregator(Query::duplicateAggregator());
-
-        $response = $this->mgClient->send($request);
-
-        return $this->responseHandler($response);
-    }
-
-    /**
-     * @param ResponseInterface $responseObj
-     *
-     * @return \stdClass
-     *
-     * @throws GenericHTTPError
-     * @throws InvalidCredentials
-     * @throws MissingEndpoint
-     * @throws MissingRequiredParameters
-     */
-    public function responseHandler($responseObj)
-    {
-        $httpResponseCode = $responseObj->getStatusCode();
-        if ($httpResponseCode === 200) {
-            $data = (string) $responseObj->getBody();
-            $jsonResponseData = json_decode($data, false);
-            $result = new \stdClass();
-            // return response data as json if possible, raw if not
-            $result->http_response_body = $data && $jsonResponseData === null ? $data : $jsonResponseData;
-        } elseif ($httpResponseCode == 400) {
-            throw new MissingRequiredParameters(ExceptionMessages::EXCEPTION_MISSING_REQUIRED_PARAMETERS.$this->getResponseExceptionMessage($responseObj));
-        } elseif ($httpResponseCode == 401) {
-            throw new InvalidCredentials(ExceptionMessages::EXCEPTION_INVALID_CREDENTIALS);
-        } elseif ($httpResponseCode == 404) {
-            throw new MissingEndpoint(ExceptionMessages::EXCEPTION_MISSING_ENDPOINT.$this->getResponseExceptionMessage($responseObj));
-        } else {
-            throw new GenericHTTPError(ExceptionMessages::EXCEPTION_GENERIC_HTTP_ERROR, $httpResponseCode, $responseObj->getBody());
-        }
-        $result->http_response_code = $httpResponseCode;
-
-        return $result;
-    }
-
-    /**
-     * @param \Guzzle\Http\Message\Response $responseObj
-     *
-     * @return string
-     */
-    protected function getResponseExceptionMessage(\GuzzleHttp\Message\Response $responseObj)
-    {
-        $body = (string) $responseObj->getBody();
-        $response = json_decode($body);
-        if (json_last_error() == JSON_ERROR_NONE && isset($response->message)) {
-            return " ".$response->message;
-        }
-    }
-
-    /**
-     * @param string $apiEndpoint
-     * @param string $apiVersion
-     * @param bool   $ssl
-     *
-     * @return string
-     */
-    private function generateEndpoint($apiEndpoint, $apiVersion, $ssl)
-    {
-        if (!$ssl) {
-            return "http://".$apiEndpoint."/".$apiVersion."/";
-        } else {
-            return "https://".$apiEndpoint."/".$apiVersion."/";
-        }
-    }
-
-    /**
-     * Add a file to the postBody.
-     *
-     * @param PostBodyInterface $postBody
-     * @param string            $fieldName
-     * @param string|array      $filePath
-     */
-    private function addFile(PostBodyInterface $postBody, $fieldName, $filePath)
-    {
-        $filename = null;
-        // Backward compatibility code
-        if (is_array($filePath)) {
-            $filename = $filePath['remoteName'];
-            $filePath = $filePath['filePath'];
-        }
-
-        // Remove leading @ symbol
-        if (strpos($filePath, '@') === 0) {
-            $filePath = substr($filePath, 1);
-        }
-
-        $postBody->addFile(new PostFile($fieldName, fopen($filePath, 'r'), $filename));
-    }
-}

src/Mailgun/Constants/Api.php

@@ -1,16 +0,0 @@
-<?php
-
-
-namespace Mailgun\Constants;
-
-
-class Api {
-    const API_USER = "api";
-    const SDK_VERSION = "1.7";
-    const SDK_USER_AGENT = "mailgun-sdk-php";
-    const RECIPIENT_COUNT_LIMIT = 1000;
-    const CAMPAIGN_ID_LIMIT = 3;
-    const TAG_LIMIT = 3;
-    const DEFAULT_TIME_ZONE = "UTC";
-}
- 

src/Mailgun/Constants/ExceptionMessages.php

@@ -1,21 +0,0 @@
-<?php
-
-
-namespace Mailgun\Constants;
-
-
-class ExceptionMessages {
-    const EXCEPTION_INVALID_CREDENTIALS = "Your credentials are incorrect.";
-    const EXCEPTION_GENERIC_HTTP_ERROR = "An HTTP Error has occurred! Check your network connection and try again.";
-    const EXCEPTION_MISSING_REQUIRED_PARAMETERS = "The parameters passed to the API were invalid. Check your inputs!";
-    const EXCEPTION_MISSING_REQUIRED_MIME_PARAMETERS = "The parameters passed to the API were invalid. Check your inputs!";
-    const EXCEPTION_MISSING_ENDPOINT = "The endpoint you've tried to access does not exist. Check your URL.";
-    const TOO_MANY_RECIPIENTS = "You've exceeded the maximum recipient count (1,000) on the to field with autosend disabled.";
-    const INVALID_PARAMETER_NON_ARRAY = "The parameter you've passed in position 2 must be an array.";
-    const INVALID_PARAMETER_ATTACHMENT = "Attachments must be passed with an \"@\" preceding the file path. Web resources not supported.";
-    const INVALID_PARAMETER_INLINE = "Inline images must be passed with an \"@\" preceding the file path. Web resources not supported.";
-    const TOO_MANY_PARAMETERS_CAMPAIGNS = "You've exceeded the maximum (3) campaigns for a single message.";
-    const TOO_MANY_PARAMETERS_TAGS = "You've exceeded the maximum (3) tags for a single message.";
-    const TOO_MANY_PARAMETERS_RECIPIENT = "You've exceeded the maximum recipient count (1,000) on the to field with autosend disabled.";
-}
- 

src/Mailgun/Lists/OptInHandler.php

@@ -1,53 +0,0 @@
-<?PHP
-
-namespace Mailgun\Lists;
-
-use Mailgun\Messages\Exceptions\InvalidParameter;
-use Mailgun\Messages\Exceptions\TooManyParameters;
-use Mailgun\Messages\Expcetions\InvalidParameterType;
-
-/**
- * This class is used for creating a unique hash for
- * mailing list subscription double-opt in requests.
- *
- * @link https://github.com/mailgun/mailgun-php/blob/master/src/Mailgun/Lists/README.md
- */
-class OptInHandler{
-
-    /**
-     * @param string $mailingList
-     * @param string $secretAppId
-     * @param string $recipientAddress
-     * @return string
-     */
-	public function generateHash($mailingList, $secretAppId, $recipientAddress){
-		$innerPayload = array('r' => $recipientAddress, 'l' => $mailingList);
-		$encodedInnerPayload = base64_encode(json_encode($innerPayload));
-
-		$innerHash = hash_hmac("sha1", $encodedInnerPayload, $secretAppId);
-		$outerPayload = array('h' => $innerHash, 'p' => $encodedInnerPayload);
-
-		return urlencode(base64_encode(json_encode($outerPayload)));
-	}
-
-    /**
-     * @param string $secretAppId
-     * @param string $uniqueHash
-     * @return array|bool
-     */
-	public function validateHash($secretAppId, $uniqueHash){
-		$decodedOuterPayload = json_decode(base64_decode(urldecode($uniqueHash)), true);
-
-		$decodedHash = $decodedOuterPayload['h'];
-		$innerPayload = $decodedOuterPayload['p'];
-
-		$decodedInnerPayload = json_decode(base64_decode($innerPayload), true);
-		$computedInnerHash = hash_hmac("sha1", $innerPayload, $secretAppId);
-
-		if($computedInnerHash == $decodedHash){
-			return array('recipientAddress' => $decodedInnerPayload['r'], 'mailingList' => $decodedInnerPayload['l']);
-		}
-
-		return false;
-	}
-}

src/Mailgun/Lists/README.md

@@ -1,116 +0,0 @@
-Mailgun - Lists
-====================
-
-This is the Mailgun PHP *Lists* utilities. 
-
-The below assumes you've already installed the Mailgun PHP SDK in to your project. 
-If not, go back to the master README for instructions.
-
-There is currently one utility provided.
-
-OptInHandler: Provides methods for authenticating an OptInRequest. 
-
-The typical flow for using this utility would be as follows:  
-**Recipient Requests Subscribe** -> [Validate Recipient Address] -> [Generate Opt In Link] -> [Email Recipient Opt In Link]  
-**Recipient Clicks Opt In Link** -> [Validate Opt In Link] -> [Subscribe User] -> [Send final confirmation]  
-
-The above flow is modeled below.
-
-Usage - Opt-In Handler (Recipient Requests Subscribe)
------------------------------------------------------
-Here's how to use Opt-In Handler to validate Opt-In requests. 
-
-```php
-# First, instantiate the SDK with your API credentials, domain, and required parameters for example. 
-$mg = new Mailgun('key-example');
-$mgValidate = new Mailgun('pub-key-example');
-
-$domain = 'example.com';
-$mailingList = 'youlist@example.com';
-$secretPassphrase = 'a_secret_passphrase';
-$recipientAddress = 'recipient@example.com';
-
-# Let's validate the customer's email address, using Mailgun's validation endpoint.
-$result = $mgValidate->get('address/validate', array('address' => $recipientAddress));
-
-if($result->http_response_body->is_valid == true){
-	# Next, instantiate an OptInHandler object from the SDK.
-	$optInHandler = $mg->OptInHandler();
-	
-	# Next, generate a hash.
-	$generatedHash = $optInHandler->generateHash($mailingList, $secretPassphrase, $recipientAddress);
-	
-	# Now, let's send a confirmation to the recipient with our link.
-	$mg->sendMessage($domain, array('from'    => 'bob@example.com', 
-	                                'to'      => $recipientAddress, 
-	                                'subject' => 'Please Confirm!', 
-	                                'html'    => "<html><body>Hello,<br><br>You have requested to be subscribed 
-	                                			  to the mailing list $mailingList. Please <a 
-	                                			  href=\"http://yourdomain.com/subscribe.php?hash=$generatedHash\">
-	                                			  confirm</a> your subscription.<br><br>Thank you!</body></html>"));
-	                                			  
-	# Finally, let's add the subscriber to a Mailing List, as unsubscribed, so we can track non-conversions.
-	$mg->post("lists/$mailingList/members", array('address'    => $recipientAddress, 
-	                                		      'subscribed' => 'no',
-	                                			  'upsert'     => 'yes'));
-}
-```
-
-Usage - Opt-In Handler (Recipient Clicks Opt In Link)
------------------------------------------------------
-Here's how to use Opt-In Handler to validate an Opt-In Hash. 
-
-```php
-# First, instantiate the SDK with your API credentials and domain. 
-$mg = new Mailgun('key-example');
-$domain = 'example.com';
-
-# Next, instantiate an OptInHandler object from the SDK.
-$optInHandler = $mg->OptInHandler();
-
-# Next, grab the hash.
-$inboundHash = $_GET['hash'];
-$secretPassphrase = 'a_secret_passphrase';
-
-# Now, validate the captured hash.
-$hashValidation = $optInHandler->validateHash($secretPassphrase, $inboundHash);
-
-# Lastly, check to see if we have results, parse, subscribe, and send confirmation.
-if($hashValidation){
-	$validatedList = $hashValidation['mailingList'];
-	$validatedRecipient = $hashValidation['recipientAddress'];
-	
-	$mg->put("lists/$validatedList/members/$validatedRecipient", 
-						array('address'    => $validatedRecipient, 
-                              'subscribed' => 'yes'));
-    
-    $mg->sendMessage($domain, array('from'    => 'bob@example.com', 
-                                    'to'      => $validatedRecipient, 
-                                    'subject' => 'Confirmation Received!', 
-                                    'html'    => "<html><body>Hello,<br><br>We've successfully subscribed 
-                                	              you to the list, $validatedList!<br><br>Thank you!
-                                	              </body></html>"));
-}
-```
-
-A few notes:  
-1. 'a_secret_passphrase' can be anything. It's used as the *key* in hashing, 
-since your email address will vary.  
-2. validateHash() will return an array containing the recipient address and list 
-address.  
-3. You should *always* send an email confirmation before and after the 
-subscription request.  
-4. WARNING: On $_GET['hash'], you need to sanitize this value to prevent 
-malicious attempts to inject code.  
-
-Available Functions
------------------------------------------------------
-
-`string generateHash(string $mailingList, string $secretAppId, string $recipientAddress)` 
-
-`array validateHash(string $secretAppId, string $uniqueHash)`  
-
-More Documentation
-------------------
-See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) 
-for more information.

src/Mailgun/Mailgun.php

@@ -1,157 +0,0 @@
-<?PHP
-
-namespace Mailgun;
-
-use Mailgun\Constants\ExceptionMessages;
-use Mailgun\Messages\Exceptions;
-use Mailgun\Connection\RestClient;
-use Mailgun\Messages\BatchMessage;
-use Mailgun\Lists\OptInHandler;
-use Mailgun\Messages\MessageBuilder;
-
-/**
- * This class is the base class for the Mailgun SDK.
- * See the official documentation (link below) for usage instructions.
- *
- * @link https://github.com/mailgun/mailgun-php/blob/master/README.md
- */
-class Mailgun{
-
-    /**
-     * @var RestClient
-     */
-    protected $restClient;
-
-    /**
-     * @var null|string
-     */
-    protected $apiKey;
-
-    /**
-     * @param string|null $apiKey
-     * @param string $apiEndpoint
-     * @param string $apiVersion
-     * @param bool $ssl
-     */
-    public function __construct($apiKey = null, $apiEndpoint = "api.mailgun.net", $apiVersion = "v3", $ssl = true){
-        $this->apiKey = $apiKey;
-        $this->restClient = new RestClient($apiKey, $apiEndpoint, $apiVersion, $ssl);
-    }
-
-    /**
-     *  This function allows the sending of a fully formed message OR a custom
-     *  MIME string. If sending MIME, the string must be passed in to the 3rd
-     *  position of the function call.
-     *
-     * @param string $workingDomain
-     * @param array $postData
-     * @param array $postFiles
-     * @throws Exceptions\MissingRequiredMIMEParameters
-     */
-    public function sendMessage($workingDomain, $postData, $postFiles = array()){
-        if(is_array($postFiles)){
-            return $this->post("$workingDomain/messages", $postData, $postFiles);
-        }
-        else if(is_string($postFiles)){
-
-            $tempFile = tempnam(sys_get_temp_dir(), "MG_TMP_MIME");
-            $fileHandle = fopen($tempFile, "w");
-            fwrite($fileHandle, $postFiles);
-
-            $result = $this->post("$workingDomain/messages.mime", $postData, array("message" => $tempFile));
-            fclose($fileHandle);
-            unlink($tempFile);
-            return $result;
-        }
-        else{
-            throw new Exceptions\MissingRequiredMIMEParameters(ExceptionMessages::EXCEPTION_MISSING_REQUIRED_MIME_PARAMETERS);
-        }
-    }
-
-    /**
-     * This function checks the signature in a POST request to see if it is
-     * authentic.
-     *
-     * Pass an array of parameters.  If you pass nothing, $_POST will be
-     * used instead.
-     *
-     * If this function returns FALSE, you must not process the request.
-     * You should reject the request with status code 403 Forbidden.
-     *
-     * @param array|null $postData
-     * @return bool
-     */
-    public function verifyWebhookSignature($postData = NULL) {
-        if(is_null($postData)) {
-            $postData = $_POST;
-        }
-        $hmac = hash_hmac('sha256', "{$postData["timestamp"]}{$postData["token"]}", $this->apiKey);
-        $sig = $postData['signature'];
-        if(function_exists('hash_equals')) {
-            // hash_equals is constant time, but will not be introduced until PHP 5.6
-            return hash_equals($hmac, $sig);
-        }
-        else {
-            return ($hmac == $sig);
-        }
-    }
-
-    /**
-     * @param string $endpointUrl
-     * @param array $postData
-     * @param array $files
-     * @return \stdClass
-     */
-    public function post($endpointUrl, $postData = array(), $files = array()){
-        return $this->restClient->post($endpointUrl, $postData, $files);
-    }
-
-    /**
-     * @param string $endpointUrl
-     * @param array $queryString
-     * @return \stdClass
-     */
-    public function get($endpointUrl, $queryString = array()){
-        return $this->restClient->get($endpointUrl, $queryString);
-    }
-
-    /**
-     * @param string $endpointUrl
-     * @return \stdClass
-     */
-    public function delete($endpointUrl){
-        return $this->restClient->delete($endpointUrl);
-    }
-
-    /**
-     * @param string $endpointUrl
-     * @param array $putData
-     * @return \stdClass
-     */
-    public function put($endpointUrl, $putData){
-        return $this->restClient->put($endpointUrl, $putData);
-    }
-
-    /**
-     * @return MessageBuilder
-     */
-    public function MessageBuilder(){
-        return new MessageBuilder();
-    }
-
-    /**
-     * @return OptInHandler
-     */
-    public function OptInHandler(){
-        return new OptInHandler();
-    }
-
-    /**
-     * @param string $workingDomain
-     * @param bool $autoSend
-     * @return BatchMessage
-     */
-    public function BatchMessage($workingDomain, $autoSend = true){
-        return new BatchMessage($this->restClient, $workingDomain, $autoSend);
-    }
-}

src/Mailgun/Messages/BatchMessage.php

@@ -1,141 +0,0 @@
-<?PHP
-
-namespace Mailgun\Messages;
-
-use Mailgun\Constants\Api;
-use Mailgun\Constants\ExceptionMessages;
-use Mailgun\Messages\Exceptions\TooManyParameters;
-use Mailgun\Messages\Exceptions\MissingRequiredMIMEParameters;
-
-/**
- * This class is used for batch sending. See the official documentation (link below)
- * for usage instructions.
- *
- * @link https://github.com/mailgun/mailgun-php/blob/master/src/Mailgun/Messages/README.md
- */
-class BatchMessage extends MessageBuilder{
-
-    /**
-     * @var array
-     */
-	private $batchRecipientAttributes;
-
-    /**
-     * @var boolean
-     */
-	private $autoSend;
-
-    /**
-     * @var \Mailgun\Connection\RestClient
-     */
-	private $restClient;
-
-    /**
-     * @var string
-     */
-	private $workingDomain;
-
-    /**
-     * @var array
-     */
-	private $messageIds = array();
-
-    /**
-     * @param \Mailgun\Connection\RestClient $restClient
-     * @param string $workingDomain
-     * @param boolean $autoSend
-     */
-	public function __construct($restClient, $workingDomain, $autoSend){
-		$this->batchRecipientAttributes = array();
-		$this->autoSend = $autoSend;
-		$this->restClient = $restClient;
-		$this->workingDomain = $workingDomain;
-		$this->endpointUrl = $workingDomain . "/messages";
-	}
-
-    /**
-     * @param string $headerName
-     * @param string $address
-     * @param array $variables
-     * @throws MissingRequiredMIMEParameters
-     * @throws TooManyParameters
-     */
-	protected function addRecipient($headerName, $address, $variables){
-		if(array_key_exists($headerName, $this->counters['recipients'])){
-			if($this->counters['recipients'][$headerName] == Api::RECIPIENT_COUNT_LIMIT){
-				if($this->autoSend == false){
-					throw new TooManyParameters(ExceptionMessages::TOO_MANY_RECIPIENTS);
-				}
-				$this->sendMessage();
-			}
-		}
-
-		$compiledAddress = $this->parseAddress($address, $variables);
-
-		if(isset($this->message[$headerName])){
-			array_push($this->message[$headerName], $compiledAddress);
-		}
-		elseif($headerName == "h:reply-to"){
-			$this->message[$headerName] = $compiledAddress;
-		}
-		else{
-			$this->message[$headerName] = array($compiledAddress);
-		}
-
-		if(array_key_exists($headerName, $this->counters['recipients'])){
-			$this->counters['recipients'][$headerName] += 1;
-			if(!array_key_exists("id", $variables)){
-				$variables['id'] = $this->counters['recipients'][$headerName];
-			}
-		}
-		$this->batchRecipientAttributes["$address"] = $variables;
-	}
-
-    /**
-     * @param array $message
-     * @param array $files
-     * @throws MissingRequiredMIMEParameters
-     */
-	public function sendMessage($message = array(), $files = array()){
-		if(count($message) < 1){
-			$message = $this->message;
-			$files = $this->files;
-		}
-		if(!array_key_exists("from", $message)){
-			throw new MissingRequiredMIMEParameters(ExceptionMessages::EXCEPTION_MISSING_REQUIRED_MIME_PARAMETERS);
-		}
-		elseif(!array_key_exists("to", $message)){
-			throw new MissingRequiredMIMEParameters(ExceptionMessages::EXCEPTION_MISSING_REQUIRED_MIME_PARAMETERS);
-		}
-		elseif(!array_key_exists("subject", $message)){
-			throw new MissingRequiredMIMEParameters(ExceptionMessages::EXCEPTION_MISSING_REQUIRED_MIME_PARAMETERS);
-		}
-		elseif((!array_key_exists("text", $message) && !array_key_exists("html", $message))){
-			throw new MissingRequiredMIMEParameters(ExceptionMessages::EXCEPTION_MISSING_REQUIRED_MIME_PARAMETERS);
-		}
-		else{
-			$message["recipient-variables"] = json_encode($this->batchRecipientAttributes);
-			$response = $this->restClient->post($this->endpointUrl, $message, $files);
-			$this->batchRecipientAttributes = array();
-			$this->counters['recipients']['to'] = 0;
-			$this->counters['recipients']['cc'] = 0;
-			$this->counters['recipients']['bcc'] = 0;
-			unset($this->message["to"]);
-			array_push($this->messageIds, $response->http_response_body->id);
-		}
-	}
-
-    /**
-     * @throws MissingRequiredMIMEParameters
-     */
-	public function finalize(){
-		$this->sendMessage();
-	}
-
-    /**
-     * @return string[]
-     */
-	public function getMessageIds(){
-		return $this->messageIds;
-	}
-}

src/Mailgun/Messages/Exceptions/InvalidParameter.php

@@ -1,4 +0,0 @@
-<?php
-namespace Mailgun\Messages\Exceptions;
-
-class InvalidParameter extends \Exception{}

src/Mailgun/Messages/Exceptions/InvalidParameterType.php

@@ -1,4 +0,0 @@
-<?php
-namespace Mailgun\Messages\Exceptions;
-
-class InvalidParameterType extends \Exception{}

src/Mailgun/Messages/Exceptions/MissingRequiredMIMEParameters.php

@@ -1,4 +0,0 @@
-<?php
-namespace Mailgun\Messages\Exceptions;
-
-class MissingRequiredMIMEParameters extends \Exception{}

src/Mailgun/Messages/Exceptions/TooManyParameters.php

@@ -1,4 +0,0 @@
-<?php
-namespace Mailgun\Messages\Exceptions;
-
-class TooManyParameters extends \Exception{}

src/Mailgun/Messages/MessageBuilder.php

@@ -1,482 +0,0 @@
-<?PHP
-
-namespace Mailgun\Messages;
-
-use Mailgun\Constants\Api;
-use Mailgun\Constants\ExceptionMessages;
-use Mailgun\Messages\Exceptions\InvalidParameter;
-use Mailgun\Messages\Exceptions\TooManyParameters;
-
-/**
- * This class is used for composing a properly formed
- * message object. Dealing with arrays can be cumbersome,
- * this class makes the process easier. See the official
- * documentation (link below) for usage instructions.
- *
- * @link https://github.com/mailgun/mailgun-php/blob/master/src/Mailgun/Messages/README.md
- */
-class MessageBuilder
-{
-    /**
-     * @var array
-     */
-    protected $message = array();
-
-    /**
-     * @var array
-     */
-    protected $variables = array();
-
-    /**
-     * @var array
-     */
-    protected $files = array();
-
-    /**
-     * @var array
-     */
-    protected $counters = array(
-        'recipients' => array(
-            'to'  => 0,
-            'cc'  => 0,
-            'bcc' => 0
-        ),
-        'attributes' => array(
-            'attachment'    => 0,
-            'campaign_id'   => 0,
-            'custom_option' => 0,
-            'tag'           => 0
-        )
-    );
-
-    /**
-     * @param array $params
-     * @param string $key
-     * @param mixed $default
-     * @return mixed
-     */
-    protected function safeGet($params, $key, $default)
-    {
-        if (array_key_exists($key, $params)) {
-            return $params[$key];
-        }
-
-        return $default;
-    }
-
-    /**
-     * @param array $params
-     * @return mixed|string
-     */
-    protected function getFullName($params)
-    {
-        if (array_key_exists("first", $params)) {
-            $first = $this->safeGet($params, "first", "");
-            $last  = $this->safeGet($params, "last", "");
-
-            return trim("$first $last");
-        }
-
-        return $this->safeGet($params, "full_name", "");
-    }
-
-    /**
-     * @param string $address
-     * @param array $variables
-     * @return string
-     */
-    protected function parseAddress($address, $variables)
-    {
-        if (!is_array($variables)) {
-            return $address;
-        }
-        $fullName = $this->getFullName($variables);
-        if ($fullName != null) {
-            return "'$fullName' <$address>";
-        }
-
-        return $address;
-    }
-
-    /**
-     * @param string $headerName
-     * @param string $address
-     * @param array $variables
-     */
-    protected function addRecipient($headerName, $address, $variables)
-    {
-        $compiledAddress = $this->parseAddress($address, $variables);
-
-        if (isset($this->message[$headerName])) {
-            array_push($this->message[$headerName], $compiledAddress);
-        } elseif ($headerName == "h:reply-to") {
-            $this->message[$headerName] = $compiledAddress;
-        } else {
-            $this->message[$headerName] = array($compiledAddress);
-        }
-        if (array_key_exists($headerName, $this->counters['recipients'])) {
-            $this->counters['recipients'][$headerName] += 1;
-        }
-    }
-
-    /**
-     * @param string $address
-     * @param array|null $variables
-     * @return mixed
-     * @throws TooManyParameters
-     */
-    public function addToRecipient($address, $variables = null)
-    {
-        if ($this->counters['recipients']['to'] > Api::RECIPIENT_COUNT_LIMIT) {
-            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_RECIPIENT);
-        }
-        $this->addRecipient("to", $address, $variables);
-
-        return end($this->message['to']);
-    }
-
-    /**
-     * @param string $address
-     * @param array|null $variables
-     * @return mixed
-     * @throws TooManyParameters
-     */
-    public function addCcRecipient($address, $variables = null)
-    {
-        if ($this->counters['recipients']['cc'] > Api::RECIPIENT_COUNT_LIMIT) {
-            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_RECIPIENT);
-        }
-        $this->addRecipient("cc", $address, $variables);
-
-        return end($this->message['cc']);
-    }
-
-    /**
-     * @param string $address
-     * @param array|null $variables
-     * @return mixed
-     * @throws TooManyParameters
-     */
-    public function addBccRecipient($address, $variables = null)
-    {
-        if ($this->counters['recipients']['bcc'] > Api::RECIPIENT_COUNT_LIMIT) {
-            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_RECIPIENT);
-        }
-        $this->addRecipient("bcc", $address, $variables);
-
-        return end($this->message['bcc']);
-    }
-
-    /**
-     * @param string $address
-     * @param array|null $variables
-     * @return mixed
-     */
-    public function setFromAddress($address, $variables = null)
-    {
-        $this->addRecipient("from", $address, $variables);
-
-        return $this->message['from'];
-    }
-
-    /**
-     * @param string $address
-     * @param array|null $variables
-     * @return mixed
-     */
-    public function setReplyToAddress($address, $variables = null)
-    {
-        $this->addRecipient("h:reply-to", $address, $variables);
-
-        return $this->message['h:reply-to'];
-    }
-
-    /**
-     * @param string $subject
-     * @return mixed
-     */
-    public function setSubject($subject = "")
-    {
-        if ($subject == null || $subject == "") {
-            $subject = " ";
-        }
-        $this->message['subject'] = $subject;
-
-        return $this->message['subject'];
-    }
-
-    /**
-     * @param string $headerName
-     * @param mixed $headerData
-     * @return mixed
-     */
-    public function addCustomHeader($headerName, $headerData)
-    {
-        if (!preg_match("/^h:/i", $headerName)) {
-            $headerName = "h:" . $headerName;
-        }
-        $this->message[$headerName] = array($headerData);
-
-        return $this->message[$headerName];
-    }
-
-    /**
-     * @param string $textBody
-     * @return string
-     */
-    public function setTextBody($textBody)
-    {
-        if ($textBody == null || $textBody == "") {
-            $textBody = " ";
-        }
-        $this->message['text'] = $textBody;
-
-        return $this->message['text'];
-    }
-
-    /**
-     * @param string $htmlBody
-     * @return string
-     */
-    public function setHtmlBody($htmlBody)
-    {
-        if ($htmlBody == null || $htmlBody == "") {
-            $htmlBody = " ";
-        }
-        $this->message['html'] = $htmlBody;
-
-        return $this->message['html'];
-    }
-
-    /**
-     * @param string $attachmentPath
-     * @param string|null $attachmentName
-     * @return bool
-     */
-    public function addAttachment($attachmentPath, $attachmentName = null)
-    {
-        if (isset($this->files["attachment"])) {
-            $attachment = array(
-                'filePath'   => $attachmentPath,
-                'remoteName' => $attachmentName
-            );
-            array_push($this->files["attachment"], $attachment);
-        } else {
-            $this->files["attachment"] = array(
-                array(
-                    'filePath'   => $attachmentPath,
-                    'remoteName' => $attachmentName
-                )
-            );
-        }
-
-        return true;
-    }
-
-    /**
-     * @param string $inlineImagePath
-     * @param string|null $inlineImageName
-     * @throws InvalidParameter
-     */
-    public function addInlineImage($inlineImagePath, $inlineImageName = null)
-    {
-        if (preg_match("/^@/", $inlineImagePath)) {
-            if (isset($this->files['inline'])) {
-                $inlineAttachment = array(
-                    'filePath'   => $inlineImagePath,
-                    'remoteName' => $inlineImageName
-                );
-                array_push($this->files['inline'], $inlineAttachment);
-            } else {
-                $this->files['inline'] = array(
-                    array(
-                        'filePath'   => $inlineImagePath,
-                        'remoteName' => $inlineImageName
-                    )
-                );
-            }
-
-            return true;
-        } else {
-            throw new InvalidParameter(ExceptionMessages::INVALID_PARAMETER_INLINE);
-        }
-    }
-
-    /**
-     * @param boolean $testMode
-     * @return string
-     */
-    public function setTestMode($testMode)
-    {
-        if (filter_var($testMode, FILTER_VALIDATE_BOOLEAN)) {
-            $testMode = "yes";
-        } else {
-            $testMode = "no";
-        }
-        $this->message['o:testmode'] = $testMode;
-
-        return $this->message['o:testmode'];
-    }
-
-    /**
-     * @param string|int $campaignId
-     * @return string|int
-     * @throws TooManyParameters
-     */
-    public function addCampaignId($campaignId)
-    {
-        if ($this->counters['attributes']['campaign_id'] < Api::CAMPAIGN_ID_LIMIT) {
-            if (isset($this->message['o:campaign'])) {
-                array_push($this->message['o:campaign'], $campaignId);
-            } else {
-                $this->message['o:campaign'] = array($campaignId);
-            }
-            $this->counters['attributes']['campaign_id'] += 1;
-
-            return $this->message['o:campaign'];
-        } else {
-            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_CAMPAIGNS);
-        }
-    }
-
-    /**
-     * @param string $tag
-     * @throws TooManyParameters
-     */
-    public function addTag($tag)
-    {
-        if ($this->counters['attributes']['tag'] < Api::TAG_LIMIT) {
-            if (isset($this->message['o:tag'])) {
-                array_push($this->message['o:tag'], $tag);
-            } else {
-                $this->message['o:tag'] = array($tag);
-            }
-            $this->counters['attributes']['tag'] += 1;
-
-            return $this->message['o:tag'];
-        } else {
-            throw new TooManyParameters(ExceptionMessages::TOO_MANY_PARAMETERS_TAGS);
-        }
-    }
-
-    /**
-     * @param boolean $enabled
-     * @return mixed
-     */
-    public function setDkim($enabled)
-    {
-        if (filter_var($enabled, FILTER_VALIDATE_BOOLEAN)) {
-            $enabled = "yes";
-        } else {
-            $enabled = "no";
-        }
-        $this->message["o:dkim"] = $enabled;
-
-        return $this->message["o:dkim"];
-    }
-
-    /**
-     * @param boolean $enabled
-     * @return string
-     */
-    public function setOpenTracking($enabled)
-    {
-        if (filter_var($enabled, FILTER_VALIDATE_BOOLEAN)) {
-            $enabled = "yes";
-        } else {
-            $enabled = "no";
-        }
-        $this->message['o:tracking-opens'] = $enabled;
-
-        return $this->message['o:tracking-opens'];
-    }
-
-    /**
-     * @param boolean $enabled
-     * @return string
-     */
-    public function setClickTracking($enabled)
-    {
-        if (filter_var($enabled, FILTER_VALIDATE_BOOLEAN)) {
-            $enabled = "yes";
-        } elseif ($enabled == "html") {
-            $enabled = "html";
-        } else {
-            $enabled = "no";
-        }
-        $this->message['o:tracking-clicks'] = $enabled;
-
-        return $this->message['o:tracking-clicks'];
-    }
-
-    /**
-     * @param string $timeDate
-     * @param string|null $timeZone
-     * @return string
-     */
-    public function setDeliveryTime($timeDate, $timeZone = null)
-    {
-        if (isset($timeZone)) {
-            $timeZoneObj = new \DateTimeZone("$timeZone");
-        } else {
-            $timeZoneObj = new \DateTimeZone(Api::DEFAULT_TIME_ZONE);
-        }
-
-        $dateTimeObj                     = new \DateTime($timeDate, $timeZoneObj);
-        $formattedTimeDate               = $dateTimeObj->format(\DateTime::RFC2822);
-        $this->message['o:deliverytime'] = $formattedTimeDate;
-
-        return $this->message['o:deliverytime'];
-    }
-
-    /**
-     * @param string $customName
-     * @param mixed $data
-     */
-    public function addCustomData($customName, $data)
-    {
-        $this->message['v:' . $customName] = json_encode($data);
-    }
-
-    /**
-     * @param string $parameterName
-     * @param mixed $data
-     * @return mixed
-     */
-    public function addCustomParameter($parameterName, $data)
-    {
-        if (isset($this->message[$parameterName])) {
-            array_push($this->message[$parameterName], $data);
-
-            return $this->message[$parameterName];
-        } else {
-            $this->message[$parameterName] = array($data);
-
-            return $this->message[$parameterName];
-        }
-    }
-
-    /**
-     * @param array $message
-     */
-    public function setMessage($message)
-    {
-        $this->message = $message;
-    }
-
-    /**
-     * @return array
-     */
-    public function getMessage()
-    {
-        return $this->message;
-    }
-
-    /**
-     * @return array
-     */
-    public function getFiles()
-    {
-        return $this->files;
-    }
-}

src/Mailgun/Messages/README.md

@@ -1,138 +0,0 @@
-Mailgun - Messages
-====================
-
-This is the Mailgun PHP *Message* utilities. 
-
-The below assumes you've already installed the Mailgun PHP SDK in to your 
-project. If not, go back to the master README for instructions.
-
-There are two utilities included, Message Builder and Batch Message. 
-
-Message Builder: Allows you to build a message object by calling methods for 
-each MIME attribute. 
-Batch Message: Inherits Message Builder and allows you to iterate through 
-recipients from a list. Messages will fire after the 1,000th recipient has been 
-added. 
-
-Usage - Message Builder
------------------------
-Here's how to use Message Builder to build your Message. 
-
-```php
-# First, instantiate the SDK with your API credentials and define your domain. 
-$mg = new Mailgun("key-example");
-$domain = "example.com";
-
-# Next, instantiate a Message Builder object from the SDK.
-$messageBldr = $mg->MessageBuilder();
-
-# Define the from address.
-$messageBldr->setFromAddress("me@example.com", array("first"=>"PHP", "last" => "SDK"));
-# Define a to recipient.
-$messageBldr->addToRecipient("john.doe@example.com", array("first" => "John", "last" => "Doe"));
-# Define a cc recipient.
-$messageBldr->addCcRecipient("sally.doe@example.com", array("first" => "Sally", "last" => "Doe"));
-# Define the subject. 
-$messageBldr->setSubject("A message from the PHP SDK using Message Builder!");
-# Define the body of the message.
-$messageBldr->setTextBody("This is the text body of the message!");
-
-# Other Optional Parameters.
-$messageBldr->addCampaignId("My-Awesome-Campaign");
-$messageBldr->addCustomHeader("Customer-Id", "12345");
-$messageBldr->addAttachment("@/tron.jpg");
-$messageBldr->setDeliveryTime("tomorrow 8:00AM", "PST");
-$messageBldr->setClickTracking(true);
-
-# Finally, send the message.
-$mg->post("{$domain}/messages", $messageBldr->getMessage(), $messageBldr->getFiles());
-```
-
-Available Functions
------------------------------------------------------
-
-`string addToRecipient(string $address, array $attributes)` 
-
-`string addCcRecipient(string $address, array $attributes)`  
-
-`string addBccRecipient(string $address, array $attributes)`  
-
-`string setFromAddress(string $address, array $attributes)`  
-
-`string setSubject(string $subject)`  
-
-`string setTextBody(string $textBody)`  
-
-`string setHtmlBody(string $htmlBody)`  
-
-`bool addAttachment(string $attachmentPath)`  
-
-`bool addInlineImage(string $inlineImagePath)`  
-
-`string setTestMode(bool $testMode)`  
-
-`string addCampaignId(string $campaignId)`  
-
-`string setDkim(bool $enabled)`  
-
-`string setOpenTracking($enabled)`  
-
-`string setClickTracking($enabled)`  
-
-`string setDeliveryTime(string $timeDate, string $timeZone)`  
-
-`string addCustomData(string $optionName, string $data)`  
-
-`string addCustomParameter(string $parameterName, string $data)`
-
-`array getMessage()`  
-
-`array getFiles()`  
-
-
-Usage - Batch Message
----------------------
-Here's how to use Batch Message to easily handle batch sending jobs. 
-
-```php
-# First, instantiate the SDK with your API credentials and define your domain. 
-$mg = new Mailgun("key-example");
-$domain = "example.com";
-
-# Next, instantiate a Message Builder object from the SDK, pass in your sending 
-domain.
-$batchMsg = $mg->BatchMessage($domain);
-
-# Define the from address.
-$batchMsg->setFromAddress("me@example.com", array("first"=>"PHP", "last" => "SDK"));
-# Define the subject. 
-$batchMsg->setSubject("A Batch Message from the PHP SDK!");
-# Define the body of the message.
-$batchMsg->setTextBody("This is the text body of the message!");
-
-# Next, let's add a few recipients to the batch job.
-$batchMsg->addToRecipient("john.doe@example.com", array("first" => "John", "last" => "Doe"));
-$batchMsg->addToRecipient("sally.doe@example.com", array("first" => "Sally", "last" => "Doe"));
-$batchMsg->addToRecipient("mike.jones@example.com", array("first" => "Mike", "last" => "Jones"));
-...
-// After 1,000 recipeints, Batch Message will automatically post your message to 
-the messages endpoint. 
-
-// Call finalize() to send any remaining recipients still in the buffer.
-$batchMsg->finalize();
-
-```
-
-Available Functions (Inherits all Batch Message and Messages Functions)
------------------------------------------------------------------------
-
-`addToRecipient(string $address, string $attributes)`  
-
-`sendMessage(array $message, array $files)` 
- 
-`array finalize()`  
-
-More Documentation
-------------------
-See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) 
-for more information.

src/Message/BatchMessage.php

@@ -0,0 +1,140 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Message;
+
+use Mailgun\Api\Message;
+use Mailgun\Message\Exceptions\MissingRequiredParameter;
+use Mailgun\Message\Exceptions\RuntimeException;
+use Mailgun\Message\Exceptions\TooManyRecipients;
+
+/**
+ * This class is used for batch sending. See the official documentation (link below)
+ * for usage instructions.
+ *
+ * @see https://github.com/mailgun/mailgun-php/blob/master/src/Mailgun/Message/README.md
+ */
+class BatchMessage extends MessageBuilder
+{
+    /**
+     * @var array
+     */
+    private $batchRecipientAttributes = [];
+
+    /**
+     * @var bool
+     */
+    private $autoSend;
+
+    /**
+     * @var array
+     */
+    private $messageIds = [];
+
+    /**
+     * @var string
+     */
+    private $domain;
+
+    /**
+     * @var Message
+     */
+    private $api;
+
+    public function __construct(Message $messageApi, string $domain, bool $autoSend)
+    {
+        $this->api = $messageApi;
+        $this->domain = $domain;
+        $this->autoSend = $autoSend;
+    }
+
+    /**
+     * @param array $variables {
+     *
+     *     @var string $id
+     *     @var string $full_name
+     *     @var string $first
+     *     @var string $last
+     * }
+     *
+     * @throws MissingRequiredParameter
+     * @throws TooManyRecipients
+     */
+    protected function addRecipient(string $headerName, string $address, array $variables): MessageBuilder
+    {
+        if (array_key_exists($headerName, $this->counters['recipients'])) {
+            if (self::RECIPIENT_COUNT_LIMIT === $this->counters['recipients'][$headerName]) {
+                if (false === $this->autoSend) {
+                    throw TooManyRecipients::whenAutoSendDisabled();
+                }
+                $this->finalize();
+            }
+        }
+
+        parent::addRecipient($headerName, $address, $variables);
+
+        if (array_key_exists($headerName, $this->counters['recipients']) && !array_key_exists('id', $variables)) {
+            $variables['id'] = $headerName.'_'.$this->counters['recipients'][$headerName];
+        }
+
+        $this->batchRecipientAttributes[$address] = $variables;
+
+        return $this;
+    }
+
+    /**
+     * @throws RuntimeException
+     * @throws MissingRequiredParameter
+     */
+    public function finalize(): void
+    {
+        $message = $this->message;
+
+        if (empty($this->domain)) {
+            throw new RuntimeException('You must call BatchMessage::setDomain before sending messages.');
+        }
+
+        if (empty($message['from'])) {
+            throw MissingRequiredParameter::create('from');
+        }
+
+        if (empty($message['to'])) {
+            throw MissingRequiredParameter::create('to');
+        }
+
+        if (empty($message['subject'])) {
+            throw MissingRequiredParameter::create('subject');
+        }
+
+        if (empty($message['text']) && empty($message['html'])) {
+            throw MissingRequiredParameter::create('text" or "html');
+        }
+
+        $message['recipient-variables'] = json_encode($this->batchRecipientAttributes);
+        $response = $this->api->send($this->domain, $message);
+
+        $this->batchRecipientAttributes = [];
+        $this->counters['recipients']['to'] = 0;
+        $this->counters['recipients']['cc'] = 0;
+        $this->counters['recipients']['bcc'] = 0;
+        unset($this->message['to']);
+
+        $this->messageIds[] = $response->getId();
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getMessageIds(): array
+    {
+        return $this->messageIds;
+    }
+}

src/Message/Exceptions/LimitExceeded.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Message\Exceptions;
+
+use Mailgun\Exception;
+
+class LimitExceeded extends \Exception implements Exception
+{
+    public static function create(string $field, int $limit)
+    {
+        return new self(sprintf('You\'ve exceeded the maximum (%d) %s for a single message.', $limit, $field));
+    }
+}

src/Message/Exceptions/MissingRequiredParameter.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Message\Exceptions;
+
+use Mailgun\Exception;
+
+class MissingRequiredParameter extends \Exception implements Exception
+{
+    public static function create(string $parameter, string $message = null)
+    {
+        if (null === $message) {
+            $message = 'The parameters passed to the API were invalid. Please specify "%s".';
+        }
+
+        return new self(sprintf($message, $parameter));
+    }
+}

src/Message/Exceptions/RuntimeException.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Message\Exceptions;
+
+use Mailgun\Exception;
+
+class RuntimeException extends \RuntimeException implements Exception
+{
+}

src/Message/Exceptions/TooManyRecipients.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Message\Exceptions;
+
+use Mailgun\Exception;
+use Mailgun\Message\MessageBuilder;
+
+class TooManyRecipients extends LimitExceeded implements Exception
+{
+    public static function create(string $field, int $limit = MessageBuilder::RECIPIENT_COUNT_LIMIT)
+    {
+        return new self(sprintf('You\'ve exceeded the maximum recipient count (%s) for filed "%s".', $limit, $field));
+    }
+
+    public static function whenAutoSendDisabled(int $limit = MessageBuilder::RECIPIENT_COUNT_LIMIT)
+    {
+        return new self(sprintf('You\'ve exceeded the maximum recipient count (%s) with autosend disabled.', $limit));
+    }
+}

src/Message/MessageBuilder.php

@@ -0,0 +1,410 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Message;
+
+use Mailgun\Message\Exceptions\LimitExceeded;
+use Mailgun\Message\Exceptions\TooManyRecipients;
+
+/**
+ * This class is used for composing a properly formed
+ * message object. Dealing with arrays can be cumbersome,
+ * this class makes the process easier. See the official
+ * documentation (link below) for usage instructions.
+ *
+ * @see https://github.com/mailgun/mailgun-php/blob/master/src/Mailgun/Message/README.md
+ */
+class MessageBuilder
+{
+    const RECIPIENT_COUNT_LIMIT = 1000;
+
+    const CAMPAIGN_ID_LIMIT = 3;
+
+    const TAG_LIMIT = 3;
+
+    /**
+     * @var array
+     */
+    protected $message = [];
+
+    /**
+     * @var array
+     */
+    protected $variables = [];
+
+    /**
+     * @var array
+     */
+    protected $counters = [
+        'recipients' => [
+            'to' => 0,
+            'cc' => 0,
+            'bcc' => 0,
+        ],
+        'attributes' => [
+            'attachment' => 0,
+            'campaign_id' => 0,
+            'custom_option' => 0,
+            'tag' => 0,
+        ],
+    ];
+
+    private function get(array $params, string $key, $default)
+    {
+        if (array_key_exists($key, $params)) {
+            return $params[$key];
+        }
+
+        return $default;
+    }
+
+    /**
+     * @param array $params {
+     *
+     *     @var string $full_name
+     *     @var string $first
+     *     @var string $last
+     * }
+     */
+    private function getFullName(array $params): string
+    {
+        if (isset($params['full_name'])) {
+            return $this->get($params, 'full_name', '');
+        }
+
+        return trim(sprintf('%s %s', $this->get($params, 'first', ''), $this->get($params, 'last', '')));
+    }
+
+    /**
+     *     @var string
+     *     @var string $first
+     *     @var string $last
+     * }
+     */
+    protected function parseAddress(string $address, array $variables): string
+    {
+        $fullName = $this->getFullName($variables);
+        if (!empty($fullName)) {
+            return sprintf('"%s" <%s>', $fullName, $address);
+        }
+
+        return $address;
+    }
+
+    /**
+     * @param array $variables {
+     *
+     *     @var string $full_name
+     *     @var string $first
+     *     @var string $last
+     * }
+     */
+    protected function addRecipient(string $headerName, string $address, array $variables): self
+    {
+        $compiledAddress = $this->parseAddress($address, $variables);
+
+        if ('h:reply-to' === $headerName) {
+            $this->message[$headerName] = $compiledAddress;
+        } elseif (isset($this->message[$headerName])) {
+            $this->message[$headerName][] = $compiledAddress;
+        } else {
+            $this->message[$headerName] = [$compiledAddress];
+        }
+        if (array_key_exists($headerName, $this->counters['recipients'])) {
+            ++$this->counters['recipients'][$headerName];
+        }
+
+        return $this;
+    }
+
+    /**
+     * @param array $variables {
+     *
+     *     @var string $id If used with BatchMessage
+     *     @var string $full_name
+     *     @var string $first
+     *     @var string $last
+     * }
+     *
+     * @throws TooManyRecipients
+     */
+    public function addToRecipient(string $address, array $variables = []): self
+    {
+        if ($this->counters['recipients']['to'] > self::RECIPIENT_COUNT_LIMIT) {
+            throw TooManyRecipients::create('to');
+        }
+        $this->addRecipient('to', $address, $variables);
+
+        return $this;
+    }
+
+    /**
+     * @param array $variables {
+     *
+     *     @var string $id If used with BatchMessage
+     *     @var string $full_name
+     *     @var string $first
+     *     @var string $last
+     * }
+     *
+     * @throws TooManyRecipients
+     */
+    public function addCcRecipient(string $address, array $variables = []): self
+    {
+        if ($this->counters['recipients']['cc'] > self::RECIPIENT_COUNT_LIMIT) {
+            throw TooManyRecipients::create('cc');
+        }
+
+        $this->addRecipient('cc', $address, $variables);
+
+        return $this;
+    }
+
+    /**
+     * @param array $variables {
+     *
+     *     @var string $id If used with BatchMessage
+     *     @var string $full_name
+     *     @var string $first
+     *     @var string $last
+     * }
+     *
+     * @throws TooManyRecipients
+     */
+    public function addBccRecipient(string $address, array $variables = []): self
+    {
+        if ($this->counters['recipients']['bcc'] > self::RECIPIENT_COUNT_LIMIT) {
+            throw TooManyRecipients::create('bcc');
+        }
+
+        $this->addRecipient('bcc', $address, $variables);
+
+        return $this;
+    }
+
+    /**
+     * @param array $variables {
+     *
+     *     @var string $id If used with BatchMessage
+     *     @var string $full_name
+     *     @var string $first
+     *     @var string $last
+     * }
+     */
+    public function setFromAddress(string $address, array $variables = []): self
+    {
+        $this->addRecipient('from', $address, $variables);
+
+        return $this;
+    }
+
+    /**
+     * @param array $variables {
+     *
+     *     @var string $id If used with BatchMessage
+     *     @var string $full_name
+     *     @var string $first
+     *     @var string $last
+     * }
+     */
+    public function setReplyToAddress(string $address, array $variables = []): self
+    {
+        $this->addRecipient('h:reply-to', $address, $variables);
+
+        return $this;
+    }
+
+    public function setSubject(string $subject): self
+    {
+        $this->message['subject'] = $subject;
+
+        return $this;
+    }
+
+    public function addCustomHeader(string $headerName, $headerData): self
+    {
+        if (!preg_match('/^h:/i', $headerName)) {
+            $headerName = 'h:'.$headerName;
+        }
+
+        if (!array_key_exists($headerName, $this->message)) {
+            $this->message[$headerName] = $headerData;
+        } else {
+            if (is_array($this->message[$headerName])) {
+                $this->message[$headerName][] = $headerData;
+            } else {
+                $this->message[$headerName] = [$this->message[$headerName], $headerData];
+            }
+        }
+
+        return $this;
+    }
+
+    public function setTextBody(string $textBody): self
+    {
+        $this->message['text'] = $textBody;
+
+        return $this;
+    }
+
+    public function setHtmlBody(string $htmlBody): self
+    {
+        $this->message['html'] = $htmlBody;
+
+        return $this;
+    }
+
+    public function addAttachment(string $attachmentPath, string $attachmentName = null): self
+    {
+        if (!isset($this->message['attachment'])) {
+            $this->message['attachment'] = [];
+        }
+
+        $this->message['attachment'][] = [
+            'filePath' => $attachmentPath,
+            'filename' => $attachmentName,
+        ];
+
+        return $this;
+    }
+
+    public function addInlineImage(string $inlineImagePath, string $inlineImageName = null): self
+    {
+        if (!isset($this->message['inline'])) {
+            $this->message['inline'] = [];
+        }
+
+        $this->message['inline'][] = [
+            'filePath' => $inlineImagePath,
+            'filename' => $inlineImageName,
+        ];
+
+        return $this;
+    }
+
+    public function setTestMode(bool $enabled): self
+    {
+        $this->message['o:testmode'] = $enabled ? 'yes' : 'no';
+
+        return $this;
+    }
+
+    /**
+     * @throws LimitExceeded
+     */
+    public function addCampaignId(string $campaignId): self
+    {
+        if ($this->counters['attributes']['campaign_id'] >= self::CAMPAIGN_ID_LIMIT) {
+            throw LimitExceeded::create('campaigns', self::CAMPAIGN_ID_LIMIT);
+        }
+        if (isset($this->message['o:campaign'])) {
+            array_push($this->message['o:campaign'], $campaignId);
+        } else {
+            $this->message['o:campaign'] = [$campaignId];
+        }
+        ++$this->counters['attributes']['campaign_id'];
+
+        return $this;
+    }
+
+    /**
+     * @throws LimitExceeded
+     */
+    public function addTag(string $tag): self
+    {
+        if ($this->counters['attributes']['tag'] >= self::TAG_LIMIT) {
+            throw LimitExceeded::create('tags', self::TAG_LIMIT);
+        }
+
+        if (isset($this->message['o:tag'])) {
+            array_push($this->message['o:tag'], $tag);
+        } else {
+            $this->message['o:tag'] = [$tag];
+        }
+        ++$this->counters['attributes']['tag'];
+
+        return $this;
+    }
+
+    public function setDkim(bool $enabled): self
+    {
+        $this->message['o:dkim'] = $enabled ? 'yes' : 'no';
+
+        return $this;
+    }
+
+    public function setOpenTracking(bool $enabled): self
+    {
+        $this->message['o:tracking-opens'] = $enabled ? 'yes' : 'no';
+
+        return $this;
+    }
+
+    public function setClickTracking(bool $enabled, bool $htmlOnly = false): self
+    {
+        $value = 'no';
+        if ($enabled) {
+            $value = 'yes';
+            if ($htmlOnly) {
+                $value = 'htmlonly';
+            }
+        }
+
+        $this->message['o:tracking-clicks'] = $value;
+
+        return $this;
+    }
+
+    public function setDeliveryTime(string $timeDate, string $timeZone = null): self
+    {
+        if (null !== $timeZone) {
+            $timeZoneObj = new \DateTimeZone($timeZone);
+        } else {
+            $timeZoneObj = new \DateTimeZone('UTC');
+        }
+
+        $dateTimeObj = new \DateTime($timeDate, $timeZoneObj);
+        $formattedTimeDate = $dateTimeObj->format(\DateTime::RFC2822);
+        $this->message['o:deliverytime'] = $formattedTimeDate;
+
+        return $this;
+    }
+
+    public function addCustomData(string $customName, $data): self
+    {
+        $this->message['v:'.$customName] = json_encode($data);
+
+        return $this;
+    }
+
+    public function addCustomParameter(string $parameterName, $data): self
+    {
+        if (isset($this->message[$parameterName])) {
+            $this->message[$parameterName][] = $data;
+        } else {
+            $this->message[$parameterName] = [$data];
+        }
+
+        return $this;
+    }
+
+    public function setMessage(array $message): self
+    {
+        $this->message = $message;
+
+        return $this;
+    }
+
+    public function getMessage(): array
+    {
+        return $this->message;
+    }
+}

src/Message/README.md

@@ -0,0 +1,84 @@
+Mailgun - Messages
+==================
+
+This is the Mailgun PHP *Message* utilities. 
+
+The below assumes you've already installed the Mailgun PHP SDK in to your 
+project. If not, go back to the master README for instructions.
+
+There are two utilities included, `MessageBuilder` and `BatchMessage`. 
+
+* `MessageBuilder`: Allows you to build a message object by calling methods for 
+each MIME attribute. 
+* `BatchMessage`: Extends `MessageBuilder` and allows you to iterate through 
+recipients from a list. Messages will fire after the 1,000th recipient has been 
+added. 
+
+Usage - Message Builder
+-----------------------
+Here's how to use Message Builder to build your Message. 
+
+```php
+# Next, instantiate a Message Builder object from the SDK.
+$builder = new MessageBuilder();
+
+# Define the from address.
+$builder->setFromAddress("me@example.com", array("first"=>"PHP", "last" => "SDK"));
+# Define a to recipient.
+$builder->addToRecipient("john.doe@example.com", array("first" => "John", "last" => "Doe"));
+# Define a cc recipient.
+$builder->addCcRecipient("sally.doe@example.com", array("full_name" => "Sally Doe"));
+# Define the subject. 
+$builder->setSubject("A message from the PHP SDK using Message Builder!");
+# Define the body of the message.
+$builder->setTextBody("This is the text body of the message!");
+
+# Other Optional Parameters.
+$builder->addCampaignId("My-Awesome-Campaign");
+$builder->addCustomHeader("Customer-Id", "12345");
+$builder->addAttachment("@/tron.jpg");
+$builder->setDeliveryTime("tomorrow 8:00AM", "PST");
+$builder->setClickTracking(true);
+
+# Finally, send the message.
+$mg = Mailgun::create('key-example');
+$domain = ;
+$mg->messages()->send("example.com", $builder->getMessage());
+```
+
+Usage - Batch Message
+---------------------
+Here's how to use Batch Message to easily handle batch sending jobs. 
+
+```php
+# First, instantiate the SDK with your API credentials and define your domain. 
+$mg = new Mailgun("key-example");
+
+# Next, instantiate a Message Builder object from the SDK, pass in your sending domain.
+$batchMessage = $mg->messages()->getBatchMessage("example.com");
+
+# Define the from address.
+$batchMessage->setFromAddress("me@example.com", array("first"=>"PHP", "last" => "SDK"));
+# Define the subject. 
+$batchMessage->setSubject("A Batch Message from the PHP SDK!");
+# Define the body of the message.
+$batchMessage->setTextBody("This is the text body of the message!");
+
+# Next, let's add a few recipients to the batch job.
+$batchMessage->addToRecipient("john.doe@example.com", array("first" => "John", "last" => "Doe"));
+$batchMessage->addToRecipient("sally.doe@example.com", array("first" => "Sally", "last" => "Doe"));
+$batchMessage->addToRecipient("mike.jones@example.com", array("first" => "Mike", "last" => "Jones"));
+...
+// After 1,000 recipients, Batch Message will automatically post your message to the messages endpoint. 
+
+// Call finalize() to send any remaining recipients still in the buffer.
+$batchMessage->finalize();
+
+$messageIds = $batchMessage->getMessageIds();
+
+```
+
+More Documentation
+------------------
+See the official [Mailgun Docs](http://documentation.mailgun.com/api-sending.html) 
+for more information.

src/Model/ApiResponse.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+interface ApiResponse
+{
+    /**
+     * Create an API response object from the HTTP response from the API server.
+     */
+    public static function create(array $data);
+}

src/Model/Domain/AbstractDomainResponse.php

@@ -0,0 +1,86 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+abstract class AbstractDomainResponse implements ApiResponse
+{
+    private $message;
+    private $domain;
+    private $inboundDnsRecords;
+    private $outboundDnsRecords;
+
+    public static function create(array $data): self
+    {
+        $rx = [];
+        $tx = [];
+        $domain = null;
+
+        if (isset($data['domain'])) {
+            $domain = Domain::create($data['domain']);
+        }
+
+        if (isset($data['receiving_dns_records'])) {
+            foreach ($data['receiving_dns_records'] as $item) {
+                $rx[] = DnsRecord::create($item);
+            }
+        }
+
+        if (isset($data['sending_dns_records'])) {
+            foreach ($data['sending_dns_records'] as $item) {
+                $tx[] = DnsRecord::create($item);
+            }
+        }
+
+        $model = new static();
+        $model->domain = $domain;
+        $model->inboundDnsRecords = $rx;
+        $model->outboundDnsRecords = $tx;
+        $model->message = $data['message'] ?? null;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getDomain(): ?Domain
+    {
+        return $this->domain;
+    }
+
+    /**
+     * @return DnsRecord[] tx
+     */
+    public function getInboundDNSRecords(): array
+    {
+        return $this->inboundDnsRecords;
+    }
+
+    /**
+     * @return DnsRecord[] tx
+     */
+    public function getOutboundDNSRecords(): array
+    {
+        return $this->outboundDnsRecords;
+    }
+
+    public function getMessage(): ?string
+    {
+        return $this->message;
+    }
+}

src/Model/Domain/ConnectionResponse.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+final class ConnectionResponse implements ApiResponse
+{
+    private $noVerify;
+    private $requireTLS;
+
+    public static function create(array $data): ?self
+    {
+        if (!isset($data['connection'])) {
+            return null;
+        }
+        $connSettings = $data['connection'];
+
+        $model = new self();
+        $model->noVerify = $connSettings['skip_verification'] ?? null;
+        $model->requireTLS = $connSettings['require_tls'] ?? null;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * Disable remote TLS certificate verification.
+     *
+     * @return bool
+     */
+    public function getSkipVerification(): ?bool
+    {
+        return $this->noVerify;
+    }
+
+    /**
+     * Requires TLS for all outbound communication.
+     *
+     * @return bool
+     */
+    public function getRequireTLS(): ?bool
+    {
+        return $this->requireTLS;
+    }
+}

src/Model/Domain/CreateCredentialResponse.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class CreateCredentialResponse implements ApiResponse
+{
+    private $message;
+
+    private function __construct()
+    {
+    }
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->message = $data['message'] ?? null;
+
+        return $model;
+    }
+
+    public function getMessage(): ?string
+    {
+        return $this->message;
+    }
+}

src/Model/Domain/CreateResponse.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class CreateResponse extends AbstractDomainResponse
+{
+}

src/Model/Domain/CredentialResponse.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+final class CredentialResponse implements ApiResponse
+{
+    private $totalCount;
+    private $items;
+
+    public static function create(array $data): self
+    {
+        $items = [];
+        if (isset($data['items'])) {
+            foreach ($data['items'] as $item) {
+                $items[] = CredentialResponseItem::create($item);
+            }
+        }
+
+        if (isset($data['total_count'])) {
+            $count = (int) $data['total_count'];
+        } else {
+            $count = count($items);
+        }
+
+        $model = new self();
+        $model->totalCount = $count;
+        $model->items = $items;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getTotalCount(): int
+    {
+        return $this->totalCount;
+    }
+
+    /**
+     * @return CredentialResponseItem[]
+     */
+    public function getCredentials(): array
+    {
+        return $this->items;
+    }
+}

src/Model/Domain/CredentialResponseItem.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+/**
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+final class CredentialResponseItem
+{
+    private $sizeBytes;
+    private $createdAt;
+    private $mailbox;
+    private $login;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->sizeBytes = $data['size_bytes'] ?? null;
+        $model->createdAt = isset($data['created_at']) ? new \DateTimeImmutable($data['created_at']) : null;
+        $model->mailbox = $data['mailbox'] ?? null;
+        $model->login = $data['login'] ?? null;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getSizeBytes(): ?int
+    {
+        return $this->sizeBytes;
+    }
+
+    public function getCreatedAt(): ?\DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+
+    public function getMailbox(): ?string
+    {
+        return $this->mailbox;
+    }
+
+    public function getLogin(): ?string
+    {
+        return $this->login;
+    }
+}

src/Model/Domain/DeleteCredentialResponse.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class DeleteCredentialResponse implements ApiResponse
+{
+    private $message;
+    private $error;
+    private $spec;
+
+    private function __construct()
+    {
+    }
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->message = $data['message'] ?? null;
+        $model->error = $data['error'] ?? null;
+        $model->spec = $data['spec'] ?? null;
+
+        return $model;
+    }
+
+    public function getMessage(): ?string
+    {
+        return $this->message;
+    }
+
+    public function getError(): ?string
+    {
+        return $this->error;
+    }
+
+    public function getSpec(): ?string
+    {
+        return $this->spec;
+    }
+}

src/Model/Domain/DeleteResponse.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class DeleteResponse implements ApiResponse
+{
+    private $message;
+    private $error;
+
+    private function __construct()
+    {
+    }
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->message = $data['message'] ?? null;
+        $model->error = $data['error'] ?? null;
+
+        return $model;
+    }
+
+    public function getMessage(): ?string
+    {
+        return $this->message;
+    }
+
+    public function getError(): ?string
+    {
+        return $this->error;
+    }
+}

src/Model/Domain/DnsRecord.php

@@ -0,0 +1,99 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+/**
+ * Represents a single DNS record for a domain.
+ *
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+final class DnsRecord
+{
+    private $name;
+    private $type;
+    private $value;
+    private $priority;
+    private $valid;
+    private $cached;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->name = $data['name'] ?? null;
+        $model->type = $data['record_type'] ?? null;
+        $model->value = $data['value'] ?? null;
+        $model->priority = $data['priority'] ?? null;
+        $model->valid = $data['valid'] ?? null;
+        $model->cached = $data['cached'] ?? [];
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * name of the record, as used in CNAME, etc.
+     */
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+
+    /**
+     * DNS record type.
+     *
+     * @return string
+     */
+    public function getType(): ?string
+    {
+        return $this->type;
+    }
+
+    /**
+     * DNS record value.
+     */
+    public function getValue(): ?string
+    {
+        return $this->value;
+    }
+
+    /**
+     * Record priority, used for MX.
+     */
+    public function getPriority(): ?string
+    {
+        return $this->priority;
+    }
+
+    /**
+     * DNS record has been added to domain DNS?
+     */
+    public function isValid(): bool
+    {
+        return 'valid' === $this->valid;
+    }
+
+    public function getValidity(): ?string
+    {
+        return $this->valid;
+    }
+
+    /**
+     * DNS record current value.
+     */
+    public function getCached(): array
+    {
+        return $this->cached;
+    }
+}

src/Model/Domain/Domain.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+/**
+ * Represents domain information in its simplest form.
+ *
+ * @author Sean Johnson <sean@ramcloud.io>
+ */
+final class Domain
+{
+    private $createdAt;
+    private $smtpLogin;
+    private $name;
+    private $smtpPassword;
+    private $wildcard;
+    private $spamAction;
+    private $state;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->name = $data['name'] ?? null;
+        $model->smtpLogin = $data['smtp_login'] ?? null;
+        $model->smtpPassword = $data['smtp_password'] ?? null;
+        $model->wildcard = $data['wildcard'] ?? null;
+        $model->spamAction = $data['spam_action'] ?? null;
+        $model->state = $data['state'] ?? null;
+        $model->createdAt = isset($data['created_at']) ? new \DateTimeImmutable($data['created_at']) : null;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getName(): ?string
+    {
+        return $this->name;
+    }
+
+    public function getSmtpUsername(): ?string
+    {
+        return $this->smtpLogin;
+    }
+
+    public function getSmtpPassword(): ?string
+    {
+        return $this->smtpPassword;
+    }
+
+    public function isWildcard(): ?bool
+    {
+        return $this->wildcard;
+    }
+
+    public function getSpamAction(): ?string
+    {
+        return $this->spamAction;
+    }
+
+    public function getState(): ?string
+    {
+        return $this->state;
+    }
+
+    public function getCreatedAt(): \DateTimeImmutable
+    {
+        return $this->createdAt;
+    }
+}

src/Model/Domain/IndexResponse.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+final class IndexResponse implements ApiResponse
+{
+    private $totalCount;
+    private $items;
+
+    public static function create(array $data): self
+    {
+        $items = [];
+
+        if (isset($data['items'])) {
+            foreach ($data['items'] as $item) {
+                $items[] = Domain::create($item);
+            }
+        }
+
+        if (isset($data['total_count'])) {
+            $count = $data['total_count'];
+        } else {
+            $count = count($items);
+        }
+
+        $model = new self();
+        $model->totalCount = $count;
+        $model->items = $items;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getTotalCount(): int
+    {
+        return $this->totalCount;
+    }
+
+    /**
+     * @return Domain[]
+     */
+    public function getDomains(): array
+    {
+        return $this->items;
+    }
+}

src/Model/Domain/ShowResponse.php

@@ -0,0 +1,79 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+final class ShowResponse implements ApiResponse
+{
+    private $domain;
+    private $inboundDnsRecords;
+    private $outboundDnsRecords;
+
+    public static function create(array $data): self
+    {
+        $rx = [];
+        $tx = [];
+        $domain = null;
+
+        if (isset($data['domain'])) {
+            $domain = Domain::create($data['domain']);
+        }
+
+        if (isset($data['receiving_dns_records'])) {
+            foreach ($data['receiving_dns_records'] as $item) {
+                $rx[] = DnsRecord::create($item);
+            }
+        }
+
+        if (isset($data['sending_dns_records'])) {
+            foreach ($data['sending_dns_records'] as $item) {
+                $tx[] = DnsRecord::create($item);
+            }
+        }
+
+        $model = new self();
+        $model->domain = $domain;
+        $model->inboundDnsRecords = $rx;
+        $model->outboundDnsRecords = $tx;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getDomain(): ?Domain
+    {
+        return $this->domain;
+    }
+
+    /**
+     * @return DnsRecord[]
+     */
+    public function getInboundDNSRecords(): array
+    {
+        return $this->inboundDnsRecords;
+    }
+
+    /**
+     * @return DnsRecord[]
+     */
+    public function getOutboundDNSRecords(): array
+    {
+        return $this->outboundDnsRecords;
+    }
+}

src/Model/Domain/UpdateConnectionResponse.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Sean Johnson <sean@mailgun.com>
+ */
+final class UpdateConnectionResponse implements ApiResponse
+{
+    private $message;
+    private $noVerify;
+    private $requireTLS;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->message = $data['message'] ?? null;
+        $model->noVerify = $data['skip-verification'] ?? null;
+        $model->requireTLS = $data['require-tls'] ?? null;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getMessage(): ?string
+    {
+        return $this->message;
+    }
+
+    public function getSkipVerification(): ?bool
+    {
+        return $this->noVerify;
+    }
+
+    public function getRequireTLS(): ?bool
+    {
+        return $this->requireTLS;
+    }
+}

src/Model/Domain/UpdateCredentialResponse.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class UpdateCredentialResponse implements ApiResponse
+{
+    private $message;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->message = $data['message'] ?? null;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getMessage(): ?string
+    {
+        return $this->message;
+    }
+}

src/Model/Domain/VerifyResponse.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Domain;
+
+/**
+ * @author Maxim Zasorin <maximzasorin@gmail.com>
+ */
+final class VerifyResponse extends AbstractDomainResponse
+{
+}

src/Model/EmailValidation/ParseResponse.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\EmailValidation;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class ParseResponse implements ApiResponse
+{
+    /**
+     * @var array
+     */
+    private $parsed;
+
+    /**
+     * @var array
+     */
+    private $unparseable;
+
+    private function __construct()
+    {
+    }
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->parsed = (isset($data['parsed']) && is_array($data['parsed'])) ? $data['parsed'] : [];
+        $model->unparseable = (isset($data['unparseable']) && is_array($data['unparseable'])) ? $data['unparseable'] : [];
+
+        return $model;
+    }
+
+    public function getParsed(): array
+    {
+        return $this->parsed;
+    }
+
+    public function getUnparseable(): array
+    {
+        return $this->unparseable;
+    }
+}

src/Model/EmailValidation/Parts.php

@@ -0,0 +1,65 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\EmailValidation;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class Parts
+{
+    /**
+     * @var string|null
+     */
+    private $displayName;
+
+    /**
+     * @var string|null
+     */
+    private $domain;
+
+    /**
+     * @var string|null
+     */
+    private $localPart;
+
+    private function __construct()
+    {
+    }
+
+    /**
+     * @return Parts
+     */
+    public static function create(array $data)
+    {
+        $model = new self();
+        $model->displayName = $data['display_name'] ?? null;
+        $model->domain = $data['domain'] ?? null;
+        $model->localPart = $data['local_part'] ?? null;
+
+        return $model;
+    }
+
+    public function getDisplayName(): ?string
+    {
+        return $this->displayName;
+    }
+
+    public function getDomain(): ?string
+    {
+        return $this->domain;
+    }
+
+    public function getLocalPart(): ?string
+    {
+        return $this->localPart;
+    }
+}

src/Model/EmailValidation/ValidateResponse.php

@@ -0,0 +1,119 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\EmailValidation;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author David Garcia <me@davidgarcia.cat>
+ */
+final class ValidateResponse implements ApiResponse
+{
+    /**
+     * @var string|null
+     */
+    private $address;
+
+    /**
+     * @var string|null
+     */
+    private $didYouMean;
+
+    /**
+     * @var bool
+     */
+    private $isDisposableAddress;
+
+    /**
+     * @var bool
+     */
+    private $isRoleAddress;
+
+    /**
+     * @var bool
+     */
+    private $isValid;
+
+    /**
+     * @var bool
+     */
+    private $mailboxVerification;
+
+    /**
+     * @var Parts
+     */
+    private $parts;
+
+    /**
+     * @var string|null
+     */
+    private $reason;
+
+    private function __construct()
+    {
+    }
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->address = $data['address'] ?? null;
+        $model->didYouMean = $data['did_you_mean'] ?? null;
+        $model->isDisposableAddress = $data['is_disposable_address'] ?? false;
+        $model->isRoleAddress = $data['is_role_address'] ?? false;
+        $model->isValid = $data['is_valid'] ?? false;
+        $model->mailboxVerification = isset($data['mailbox_verification']) ? 'true' === $data['mailbox_verification'] : false;
+        $model->parts = Parts::create($data['parts'] ?? []);
+        $model->reason = $data['reason'] ?? null;
+
+        return $model;
+    }
+
+    public function getAddress(): ?string
+    {
+        return $this->address;
+    }
+
+    public function getDidYouMean(): ?string
+    {
+        return $this->didYouMean;
+    }
+
+    public function isDisposableAddress(): bool
+    {
+        return $this->isDisposableAddress;
+    }
+
+    public function isRoleAddress(): bool
+    {
+        return $this->isRoleAddress;
+    }
+
+    public function isValid(): bool
+    {
+        return $this->isValid;
+    }
+
+    public function isMailboxVerification(): bool
+    {
+        return $this->mailboxVerification;
+    }
+
+    public function getParts(): Parts
+    {
+        return $this->parts;
+    }
+
+    public function getReason(): ?string
+    {
+        return $this->reason;
+    }
+}

src/Model/Event/Event.php

@@ -0,0 +1,195 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Event;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class Event
+{
+    private $event;
+    private $id;
+    private $timestamp;
+    private $eventDate;
+    private $tags;
+    private $url;
+    private $severity;
+    private $envelope;
+    private $deliveryStatus;
+    private $campaigns;
+    private $ip;
+    private $clientInfo;
+    private $reason;
+    private $userVariables;
+    private $flags;
+    private $routes;
+    private $message;
+    private $recipient;
+    private $geolocation;
+    private $storage;
+    private $method;
+
+    private function __construct()
+    {
+    }
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->event = $data['event'];
+        $model->id = $data['id'];
+        $model->timestamp = (int) $data['timestamp'];
+        $model->eventDate = (new \DateTimeImmutable())->setTimestamp((int) $data['timestamp']);
+        $model->tags = $data['tags'] ?? [];
+        $model->envelope = $data['envelope'] ?? [];
+        $model->campaigns = $data['campaigns'] ?? [];
+        $model->userVariables = $data['user-variables'] ?? [];
+        $model->flags = $data['flags'] ?? [];
+        $model->routes = $data['routes'] ?? [];
+        $model->message = $data['message'] ?? [];
+        $model->recipient = $data['recipient'] ?? '';
+        $model->method = $data['method'] ?? '';
+        $model->deliveryStatus = $data['delivery-status'] ?? [];
+        $model->severity = $data['severity'] ?? '';
+        $model->reason = $data['reason'] ?? '';
+        $model->geolocation = $data['geolocation'] ?? [];
+        $model->ip = $data['ip'] ?? '';
+        $model->clientInfo = $data['client-info'] ?? [];
+        $model->url = $data['url'] ?? '';
+        $model->storage = $data['storage'] ?? [];
+
+        return $model;
+    }
+
+    public function getEvent(): string
+    {
+        return $this->event;
+    }
+
+    public function getId(): string
+    {
+        return $this->id;
+    }
+
+    public function getTimestamp(): int
+    {
+        return $this->timestamp;
+    }
+
+    /**
+     * A \DateTimeImmutable representation of $timestamp.
+     */
+    public function getEventDate(): \DateTimeImmutable
+    {
+        return $this->eventDate;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getTags(): array
+    {
+        return $this->tags;
+    }
+
+    public function getUrl(): string
+    {
+        return $this->url;
+    }
+
+    public function getSeverity(): string
+    {
+        return $this->severity;
+    }
+
+    public function getEnvelope(): array
+    {
+        return $this->envelope;
+    }
+
+    public function getDeliveryStatus(): array
+    {
+        return $this->deliveryStatus;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getCampaigns(): array
+    {
+        return $this->campaigns;
+    }
+
+    public function getIp(): string
+    {
+        return $this->ip;
+    }
+
+    public function getClientInfo(): array
+    {
+        return $this->clientInfo;
+    }
+
+    public function getReason(): string
+    {
+        return $this->reason;
+    }
+
+    public function getUserVariables(): array
+    {
+        return $this->userVariables;
+    }
+
+    /**
+     * key=>bool.
+     */
+    public function getFlags(): array
+    {
+        return $this->flags;
+    }
+
+    /**
+     * multi dimensions.
+     */
+    public function getRoutes(): array
+    {
+        return $this->routes;
+    }
+
+    /**
+     * multi dimensions.
+     */
+    public function getMessage(): array
+    {
+        return $this->message;
+    }
+
+    public function getRecipient(): string
+    {
+        return $this->recipient;
+    }
+
+    public function getGeolocation(): array
+    {
+        return $this->geolocation;
+    }
+
+    public function getStorage(): array
+    {
+        return $this->storage;
+    }
+
+    public function getMethod(): string
+    {
+        return $this->method;
+    }
+}

src/Model/Event/EventResponse.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Event;
+
+use Mailgun\Model\PagingProvider;
+use Mailgun\Model\PaginationResponse;
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class EventResponse implements ApiResponse, PagingProvider
+{
+    use PaginationResponse;
+    private $items;
+
+    private function __construct()
+    {
+    }
+
+    public static function create(array $data)
+    {
+        $events = [];
+        if (isset($data['items'])) {
+            foreach ($data['items'] as $item) {
+                $events[] = Event::create($item);
+            }
+        }
+
+        $model = new self();
+        $model->items = $events;
+        $model->paging = $data['paging'];
+
+        return $model;
+    }
+
+    /**
+     * @return Event[]
+     */
+    public function getItems(): array
+    {
+        return $this->items;
+    }
+}

src/Model/Ip/IndexResponse.php

@@ -0,0 +1,56 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * Copyright (C) 2013 Mailgun
+ *
+ * This software may be modified and distributed under the terms
+ * of the MIT license. See the LICENSE file for details.
+ */
+
+namespace Mailgun\Model\Ip;
+
+use Mailgun\Model\ApiResponse;
+
+/**
+ * @author Tobias Nyholm <tobias.nyholm@gmail.com>
+ */
+final class IndexResponse implements ApiResponse
+{
+    /**
+     * @var string[]
+     */
+    private $items;
+
+    /**
+     * @var int
+     */
+    private $totalCount;
+
+    private function __construct()
+    {
+    }
+
+    public static function create(array $data)
+    {
+        $model = new self();
+        $model->items = $data['items'];
+        $model->totalCount = $data['total_count'] ?? 0;
+
+        return $model;
+    }
+
+    /**
+     * @return string[]
+     */
+    public function getItems(): array
+    {
+        return $this->items;
+    }
+
+    public function getTotalCount(): int
+    {
+        return $this->totalCount;
+    }
+}