Adding support for Mailing list (#514)

* Adding Mailing list API

* Added tests

* cs

* Fixed the tests

* code cleanup

src/Mailgun/Api/HttpApi.php

@@ -29,7 +29,7 @@ abstract class HttpApi
      *
      * @var HttpClient
      */
-    private $httpClient;
+    protected $httpClient;
 
     /**
      * @var Hydrator

src/Mailgun/Api/MailingList.php

@@ -0,0 +1,154 @@
+<?php
+
+/*
+ * 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;
+
+class MailingList extends HttpApi
+{
+    /**
+     * @return Member
+     */
+    public function 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($limit = 100)
+    {
+        Assert::integer($limit);
+        Assert::greaterThan($limit, 0);
+
+        $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($address, $name = null, $description = null, $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($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($address, $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($address)
+    {
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpDelete(sprintf('/v3/lists/%s', $address));
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Mailgun/Api/MailingList/Member.php

@@ -0,0 +1,233 @@
+<?php
+
+/*
+ * 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;
+
+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 string|null $subscribed `yes` to lists subscribed, `no` for unsubscribed. list all if null
+     *
+     * @return IndexResponse
+     *
+     * @throws \Exception
+     */
+    public function index($address, $limit = 100, $subscribed = null)
+    {
+        Assert::stringNotEmpty($address);
+        Assert::integer($limit);
+        Assert::greaterThan($limit, 0);
+        Assert::oneOf($subscribed, [null, 'yes', 'no']);
+
+        $params = [
+            'limit' => $limit,
+            'subscribed' => $subscribed,
+        ];
+
+        $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($list, $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 string $subscribed `yes` to add as subscribed (default), `no` as unsubscribed
+     * @param string $upsert     `yes` to update member if present, `no` to raise error in case of a duplicate member (default)
+     *
+     * @return CreateResponse
+     *
+     * @throws \Exception
+     */
+    public function create($list, $address, $name = null, array $vars = [], $subscribed = 'yes', $upsert = 'no')
+    {
+        Assert::stringNotEmpty($list);
+        Assert::stringNotEmpty($address);
+        Assert::nullOrStringNotEmpty($name);
+        Assert::oneOf($subscribed, ['yes', 'no']);
+        Assert::oneOf($upsert, ['yes', 'no']);
+
+        $params = [
+            'address' => $address,
+            'name' => $name,
+            'vars' => $vars,
+            'subscribed' => $subscribed,
+            'upsert' => $upsert,
+        ];
+
+        $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 string $upsert  `yes` to update existing members, `no` (default) to ignore duplicates
+     *
+     * @return UpdateResponse
+     *
+     * @throws \Exception
+     */
+    public function createMultiple($list, array $members, $upsert = 'no')
+    {
+        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)
+            ));
+        }
+
+        Assert::oneOf($upsert, ['yes', 'no']);
+
+        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 'name':
+                        Assert::string($value);
+
+                        break;
+                    case 'vars':
+                        Assert::isArray($value);
+
+                        break;
+                    case 'subscribed':
+                        Assert::oneOf($value, ['yes', 'no']);
+
+                        break;
+                }
+            }
+        }
+
+        $params = [
+            'members' => json_encode($members),
+            'upsert' => $upsert,
+        ];
+
+        $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($list, $address, $parameters = [])
+    {
+        Assert::stringNotEmpty($list);
+        Assert::stringNotEmpty($address);
+        Assert::isArray($parameters);
+
+        foreach ($parameters as $field => $value) {
+            switch ($field) {
+                case 'address':
+                case 'name':
+                    Assert::stringNotEmpty($value);
+
+                    break;
+                case 'vars':
+                    Assert::isArray($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($list, $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/Mailgun/Model/MailingList/CreateResponse.php

@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * 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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class CreateResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $message;
+
+    /**
+     * @var MailingList
+     */
+    private $list;
+
+    /**
+     * @param array $data
+     *
+     * @return self
+     */
+    public static function create(array $data)
+    {
+        $message = isset($data['message']) ? $data['message'] : '';
+        $list = MailingList::create($data['list']);
+
+        return new self($list, $message);
+    }
+
+    private function __construct(MailingList $list, $message)
+    {
+        $this->list = $list;
+        $this->message = $message;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+
+    /**
+     * @return MailingList
+     */
+    public function getList()
+    {
+        return $this->list;
+    }
+}

src/Mailgun/Model/MailingList/DeleteResponse.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * 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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class DeleteResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $message;
+
+    /**
+     * @var string
+     */
+    private $address;
+
+    public static function create(array $data)
+    {
+        $message = isset($data['message']) ? $data['message'] : '';
+        $address = isset($data['address']) ? $data['address'] : '';
+
+        return new self($address, $message);
+    }
+
+    /**
+     * DeleteResponse constructor.
+     *
+     * @param string $address
+     * @param string $message
+     */
+    private function __construct($address, $message)
+    {
+        $this->address = $address;
+        $this->message = $message;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+
+    /**
+     * @return string
+     */
+    public function getAddress()
+    {
+        return $this->address;
+    }
+}

src/Mailgun/Model/MailingList/MailingList.php

@@ -0,0 +1,130 @@
+<?php
+
+/*
+ * 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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class MailingList implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $name;
+
+    /**
+     * @var string
+     */
+    private $address;
+
+    /**
+     * @var string
+     */
+    private $accessLevel;
+
+    /**
+     * @var string
+     */
+    private $description;
+
+    /**
+     * @var int
+     */
+    private $membersCount;
+
+    /**
+     * @var \DateTime
+     */
+    private $createdAt;
+
+    /**
+     * @param array $data
+     *
+     * @return self
+     */
+    public static function create(array $data)
+    {
+        return new self(
+            isset($data['name']) ? $data['name'] : null,
+            isset($data['address']) ? $data['address'] : null,
+            isset($data['access_level']) ? $data['access_level'] : null,
+            isset($data['description']) ? $data['description'] : null,
+            isset($data['members_count']) ? $data['members_count'] : null,
+            isset($data['created_at']) ? new \DateTime($data['created_at']) : null
+        );
+    }
+
+    /**
+     * MailingList constructor.
+     *
+     * @param string    $name
+     * @param string    $address
+     * @param string    $accessLevel
+     * @param string    $description
+     * @param int       $membersCount
+     * @param \DateTime $createdAt
+     */
+    private function __construct($name, $address, $accessLevel, $description, $membersCount, \DateTime $createdAt)
+    {
+        $this->name = $name;
+        $this->address = $address;
+        $this->accessLevel = $accessLevel;
+        $this->description = $description;
+        $this->membersCount = $membersCount;
+        $this->createdAt = $createdAt;
+    }
+
+    /**
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    /**
+     * @return string
+     */
+    public function getAddress()
+    {
+        return $this->address;
+    }
+
+    /**
+     * @return string
+     */
+    public function getAccessLevel()
+    {
+        return $this->accessLevel;
+    }
+
+    /**
+     * @return string
+     */
+    public function getDescription()
+    {
+        return $this->description;
+    }
+
+    /**
+     * @return int
+     */
+    public function getMembersCount()
+    {
+        return $this->membersCount;
+    }
+
+    /**
+     * @return \DateTime
+     */
+    public function getCreatedAt()
+    {
+        return $this->createdAt;
+    }
+}

src/Mailgun/Model/MailingList/Member/CreateResponse.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * 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\MailingList\Member;
+
+use Mailgun\Model\ApiResponse;
+
+final class CreateResponse implements ApiResponse
+{
+    /**
+     * @var Member
+     */
+    private $member;
+
+    /**
+     * @var string
+     */
+    private $message;
+
+    public static function create(array $data)
+    {
+        $member = Member::create($data['member']);
+        $message = isset($data['message']) ? $data['message'] : '';
+
+        return new self($member, $message);
+    }
+
+    /**
+     * CreateMemberResponse constructor.
+     *
+     * @param Member $member
+     * @param string $message
+     */
+    private function __construct(Member $member, $message)
+    {
+        $this->member = $member;
+        $this->message = $message;
+    }
+
+    /**
+     * @return Member
+     */
+    public function getMember()
+    {
+        return $this->member;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+}

src/Mailgun/Model/MailingList/Member/DeleteResponse.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * 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\MailingList\Member;
+
+use Mailgun\Model\ApiResponse;
+
+final class DeleteResponse implements ApiResponse
+{
+    /**
+     * @var Member
+     */
+    private $member;
+
+    /**
+     * @var string
+     */
+    private $message;
+
+    public static function create(array $data)
+    {
+        $member = Member::create($data['member']);
+        $message = isset($data['message']) ? $data['message'] : '';
+
+        return new self($member, $message);
+    }
+
+    /**
+     * DeleteMemberResponse constructor.
+     *
+     * @param Member $member
+     * @param string $message
+     */
+    private function __construct(Member $member, $message)
+    {
+        $this->member = $member;
+        $this->message = $message;
+    }
+
+    /**
+     * @return Member
+     */
+    public function getMember()
+    {
+        return $this->member;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+}

src/Mailgun/Model/MailingList/Member/IndexResponse.php

@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * 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\MailingList\Member;
+
+use Mailgun\Model\PagingProvider;
+use Mailgun\Model\PaginationResponse;
+use Mailgun\Model\ApiResponse;
+
+final class IndexResponse implements ApiResponse, PagingProvider
+{
+    use PaginationResponse;
+
+    /**
+     * @var Member[]
+     */
+    private $items;
+
+    /**
+     * @param array $data
+     *
+     * @return self
+     */
+    public static function create(array $data)
+    {
+        $items = [];
+
+        if (isset($data['items'])) {
+            foreach ($data['items'] as $item) {
+                $items[] = Member::create($item);
+            }
+        }
+
+        return new self($items, $data['paging']);
+    }
+
+    /**
+     * @param Member[] $items
+     * @param array    $paging
+     */
+    private function __construct(array $items, array $paging)
+    {
+        $this->items = $items;
+        $this->paging = $paging;
+    }
+
+    /**
+     * @return Member[]
+     */
+    public function getItems()
+    {
+        return $this->items;
+    }
+}

src/Mailgun/Model/MailingList/Member/Member.php

@@ -0,0 +1,90 @@
+<?php
+
+/*
+ * 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\MailingList\Member;
+
+use Mailgun\Model\ApiResponse;
+
+final class Member implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $name;
+
+    /**
+     * @var string
+     */
+    private $address;
+
+    /**
+     * @var array
+     */
+    private $vars;
+
+    /**
+     * @var bool
+     */
+    private $subscribed;
+
+    /**
+     * @param array $data
+     *
+     * @return self
+     */
+    public static function create(array $data)
+    {
+        return new self(
+            isset($data['name']) ? $data['name'] : null,
+            isset($data['address']) ? $data['address'] : null,
+            isset($data['vars']) ? $data['vars'] : [],
+            isset($data['subscribed']) ? (bool) $data['subscribed'] : null
+        );
+    }
+
+    private function __construct($name, $address, $vars = [], $subscribed = null)
+    {
+        $this->name = $name;
+        $this->address = $address;
+        $this->vars = $vars;
+        $this->subscribed = $subscribed;
+    }
+
+    /**
+     * @return string
+     */
+    public function getName()
+    {
+        return $this->name;
+    }
+
+    /**
+     * @return string
+     */
+    public function getAddress()
+    {
+        return $this->address;
+    }
+
+    /**
+     * @return array
+     */
+    public function getVars()
+    {
+        return $this->vars;
+    }
+
+    /**
+     * @return bool
+     */
+    public function isSubscribed()
+    {
+        return $this->subscribed;
+    }
+}

src/Mailgun/Model/MailingList/Member/ShowResponse.php

@@ -0,0 +1,40 @@
+<?php
+
+/*
+ * 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\MailingList\Member;
+
+use Mailgun\Model\ApiResponse;
+
+final class ShowResponse implements ApiResponse
+{
+    /**
+     * @var Member
+     */
+    private $member;
+
+    public static function create(array $data)
+    {
+        $member = Member::create($data['member']);
+
+        return new self($member);
+    }
+
+    private function __construct(Member $member)
+    {
+        $this->member = $member;
+    }
+
+    /**
+     * @return Member
+     */
+    public function getMember()
+    {
+        return $this->member;
+    }
+}

src/Mailgun/Model/MailingList/Member/UpdateResponse.php

@@ -0,0 +1,61 @@
+<?php
+
+/*
+ * 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\MailingList\Member;
+
+use Mailgun\Model\ApiResponse;
+
+final class UpdateResponse implements ApiResponse
+{
+    /**
+     * @var Member
+     */
+    private $member;
+
+    /**
+     * @var string
+     */
+    private $message;
+
+    public static function create(array $data)
+    {
+        $member = Member::create($data['member']);
+        $message = isset($data['message']) ? $data['message'] : '';
+
+        return new self($member, $message);
+    }
+
+    /**
+     * UpdateMemberResponse constructor.
+     *
+     * @param Member $member
+     * @param string $message
+     */
+    private function __construct(Member $member, $message)
+    {
+        $this->member = $member;
+        $this->message = $message;
+    }
+
+    /**
+     * @return Member
+     */
+    public function getMember()
+    {
+        return $this->member;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+}

src/Mailgun/Model/MailingList/PagesResponse.php

@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * 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\MailingList;
+
+use Mailgun\Model\PagingProvider;
+use Mailgun\Model\PaginationResponse;
+use Mailgun\Model\ApiResponse;
+
+final class PagesResponse implements ApiResponse, PagingProvider
+{
+    use PaginationResponse;
+
+    /**
+     * @var MailingList[]
+     */
+    private $items;
+
+    /**
+     * @param array $data
+     *
+     * @return self
+     */
+    public static function create(array $data)
+    {
+        $items = [];
+
+        if (isset($data['items'])) {
+            foreach ($data['items'] as $item) {
+                $items[] = MailingList::create($item);
+            }
+        }
+
+        return new self($items, $data['paging']);
+    }
+
+    /**
+     * @param MailingList[] $items
+     * @param array         $paging
+     */
+    private function __construct(array $items, array $paging)
+    {
+        $this->items = $items;
+        $this->paging = $paging;
+    }
+
+    /**
+     * @return MailingList[]
+     */
+    public function getLists()
+    {
+        return $this->items;
+    }
+}

src/Mailgun/Model/MailingList/ShowResponse.php

@@ -0,0 +1,40 @@
+<?php
+
+/*
+ * 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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class ShowResponse implements ApiResponse
+{
+    /**
+     * @var MailingList
+     */
+    private $list;
+
+    public static function create(array $data)
+    {
+        $list = MailingList::create($data['list']);
+
+        return new self($list);
+    }
+
+    private function __construct(MailingList $list)
+    {
+        $this->list = $list;
+    }
+
+    /**
+     * @return MailingList
+     */
+    public function getList()
+    {
+        return $this->list;
+    }
+}

src/Mailgun/Model/MailingList/UpdateResponse.php

@@ -0,0 +1,60 @@
+<?php
+
+/*
+ * 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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class UpdateResponse implements ApiResponse
+{
+    /**
+     * @var string
+     */
+    private $message;
+
+    /**
+     * @var MailingList
+     */
+    private $list;
+
+    /**
+     * @param array $data
+     *
+     * @return self
+     */
+    public static function create(array $data)
+    {
+        $message = isset($data['message']) ? $data['message'] : '';
+        $list = MailingList::create($data['list']);
+
+        return new self($list, $message);
+    }
+
+    private function __construct(MailingList $list, $message)
+    {
+        $this->list = $list;
+        $this->message = $message;
+    }
+
+    /**
+     * @return string
+     */
+    public function getMessage()
+    {
+        return $this->message;
+    }
+
+    /**
+     * @return MailingList
+     */
+    public function getList()
+    {
+        return $this->list;
+    }
+}

tests/Api/MailingList/MemberTest.php

@@ -0,0 +1,212 @@
+<?php
+
+/*
+ * 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\Tests\Api\MailingList;
+
+use GuzzleHttp\Psr7\Response;
+use Mailgun\Api\MailingList;
+use Mailgun\Exception\InvalidArgumentException;
+use Mailgun\Tests\Api\TestCase;
+
+class MemberTest extends TestCase
+{
+    public function testIndexAll()
+    {
+        $data = [
+            'limit' => 100,
+            'subscribed' => null,
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpGet')
+            ->with('/v3/lists/address/members/pages', $data)
+            ->willReturn(new Response());
+
+        $api->index('address', 100, null);
+    }
+
+    public function testIndexSubscribed()
+    {
+        $data = [
+            'limit' => 100,
+            'subscribed' => 'yes',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpGet')
+            ->with('/v3/lists/address/members/pages', $data)
+            ->willReturn(new Response());
+
+        $api->index('address', 100, 'yes');
+    }
+
+    public function testIndexUnsubscribed()
+    {
+        $data = [
+            'limit' => 100,
+            'subscribed' => 'no',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpGet')
+            ->with('/v3/lists/address/members/pages', $data)
+            ->willReturn(new Response());
+
+        $api->index('address', 100, 'no');
+    }
+
+    public function testCreate()
+    {
+        $data = [
+            'address' => 'foo@example.com',
+            'name' => 'Foo',
+            'vars' => [],
+            'subscribed' => 'yes',
+            'upsert' => 'no',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpPost')
+            ->with('/v3/lists/address/members', $data)
+            ->willReturn(new Response());
+
+        $api->create($list = 'address', $address = 'foo@example.com', $name = 'Foo', $vars = [], $subscribed = 'yes', $upsert = 'no');
+    }
+
+    public function testCreateInvalidAddress()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $api = $this->getApiMock();
+        $api->create('address', '');
+    }
+
+    public function testCreateInvalidSubscribed()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $api = $this->getApiMock();
+        $api->create('address', 'foo@example.com', null, [], true);
+    }
+
+    public function testCreateMultiple()
+    {
+        $data = [
+            'members' => json_encode([
+                'bob@example.com',
+                'foo@example.com',
+                [
+                    'address' => 'billy@example.com',
+                    'name' => 'Billy',
+                    'subscribed' => 'yes',
+                ],
+            ]),
+            'upsert' => 'no',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpPost')
+            ->with('/v3/lists/address/members.json', $data)
+            ->willReturn(new Response());
+
+        $api->createMultiple($list = 'address', [
+            'bob@example.com',
+            'foo@example.com',
+            [
+                'address' => 'billy@example.com',
+                'name' => 'Billy',
+                'subscribed' => 'yes',
+            ],
+        ], $upsert = 'no');
+    }
+
+    public function testCreateMultipleInvalidMemberArgument()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $data = [
+            'bob@example.com',
+            'foo@example.com',
+            [
+                'address' => 'billy@example.com',
+                'name' => 'Billy',
+                'subscribed' => true,
+            ],
+        ];
+
+        $api = $this->getApiMock();
+        $api->createMultiple('address', $data);
+    }
+
+    public function testCreateMultipleCountMax1000()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $members = range(1, 1001);
+        $members = array_map('strval', $members);
+
+        $api = $this->getApiMock();
+        $api->createMultiple('address', $members);
+    }
+
+    public function testUpdate()
+    {
+        $data = [
+            'vars' => [
+                'foo' => 'bar',
+            ],
+            'subscribed' => 'yes',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpPut')
+            ->with('/v3/lists/address/members/member', $data)
+            ->willReturn(new Response());
+
+        $api->update('address', 'member', $data);
+    }
+
+    public function testUpdateInvalidArgument()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $data = [
+            'vars' => 'foo=bar',
+            'subscribed' => 'yes',
+        ];
+
+        $api = $this->getApiMock();
+        $api->update('address', 'member', $data);
+    }
+
+    public function testDelete()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpDelete')
+            ->with('/v3/lists/address/members/member')
+            ->willReturn(new Response());
+
+        $api->delete('address', 'member');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function getApiClass()
+    {
+        return MailingList\Member::class;
+    }
+}

tests/Api/MailingListTest.php

@@ -0,0 +1,140 @@
+<?php
+
+/*
+ * 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\Tests\Api;
+
+use GuzzleHttp\Psr7\Response;
+use Mailgun\Api\MailingList;
+use Mailgun\Exception\InvalidArgumentException;
+
+class MailingListTest extends TestCase
+{
+    public function testPages()
+    {
+        $data = [
+            'limit' => 10,
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpGet')
+            ->with('/v3/lists/pages', $data)
+            ->willReturn(new Response());
+
+        $api->pages(10);
+    }
+
+    public function testPagesInvalidArgument()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+        $api = $this->getApiMock();
+        $limit = -1;
+
+        $api->pages($limit);
+    }
+
+    public function testCreate()
+    {
+        $data = [
+            'address' => 'foo@example.com',
+            'name' => 'Foo',
+            'description' => 'Description',
+            'access_level' => 'readonly',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpPost')
+            ->with('/v3/lists', $data)
+            ->willReturn(new Response());
+
+        $api->create($address = 'foo@example.com', $name = 'Foo', $description = 'Description', $accessLevel = 'readonly');
+    }
+
+    public function testCreateInvalidAddress()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $api = $this->getApiMock();
+        $api->create($address = '', $name = 'Foo', $description = 'Description', $accessLevel = 'readonly');
+    }
+
+    public function testCreateInvalidAccessLevel()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $api = $this->getApiMock();
+        $api->create($address = '', $name = 'Foo', $description = 'Description', $accessLevel = 'admin');
+    }
+
+    public function testShow()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpGet')
+            ->with('/v3/lists/address')
+            ->willReturn(new Response());
+
+        $api->show('address');
+    }
+
+    public function testShowInvalidAddress()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $api = $this->getApiMock();
+        $api->show('');
+    }
+
+    public function testUpdate()
+    {
+        $data = [
+            'description' => 'desc',
+        ];
+
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpPut')
+            ->with('/v3/lists/address', $data)
+            ->willReturn(new Response());
+
+        $api->update('address', $data);
+    }
+
+    public function testUpdateInvalidArgument()
+    {
+        $this->setExpectedException(InvalidArgumentException::class);
+
+        $data = [
+            'access_level' => 'foo',
+        ];
+
+        $api = $this->getApiMock();
+        $api->update('address', $data);
+    }
+
+    public function testDelete()
+    {
+        $api = $this->getApiMock();
+        $api->expects($this->once())
+            ->method('httpDelete')
+            ->with('/v3/lists/address')
+            ->willReturn(new Response());
+
+        $api->delete('address');
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function getApiClass()
+    {
+        return MailingList::class;
+    }
+}

tests/Model/MailingList/CreateResponseTest.php

@@ -0,0 +1,38 @@
+<?php
+
+/*
+ * 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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\CreateResponse;
+use Mailgun\Model\MailingList\MailingList;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class CreateResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+  "message": "Mailing list has been created",
+  "list": {
+      "created_at": "Tue, 06 Mar 2012 05:44:45 GMT",
+      "address": "dev@samples.mailgun.org",
+      "members_count": 0,
+      "description": "Mailgun developers list",
+      "name": ""
+  }
+}
+JSON;
+        $model = CreateResponse::create(json_decode($json, true));
+        $this->assertEquals('Mailing list has been created', $model->getMessage());
+        $this->assertInstanceOf(MailingList::class, $model->getList());
+        $this->assertEquals(0, $model->getList()->getMembersCount());
+    }
+}

tests/Model/MailingList/DeleteResponseTest.php

@@ -0,0 +1,30 @@
+<?php
+
+/*
+ * 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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\DeleteResponse;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class DeleteResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+  "message": "Mailing list has been deleted",
+  "address": "dev@samples.mailgun.org"
+}
+JSON;
+        $model = DeleteResponse::create(json_decode($json, true));
+        $this->assertEquals('Mailing list has been deleted', $model->getMessage());
+        $this->assertEquals('dev@samples.mailgun.org', $model->getAddress());
+    }
+}

tests/Model/MailingList/Member/CreateResponseTest.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * 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\Tests\Model\MailingList\Member;
+
+use Mailgun\Model\MailingList\Member\CreateResponse;
+use Mailgun\Model\MailingList\Member\Member;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class CreateResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+  "member": {
+      "vars": {
+          "age": 26
+      },
+      "name": "Bob Bar",
+      "subscribed": true,
+      "address": "bar@example.com"
+  },
+  "message": "Mailing list member has been created"
+}
+JSON;
+        $model = CreateResponse::create(json_decode($json, true));
+        $this->assertEquals('Mailing list member has been created', $model->getMessage());
+        $this->assertInstanceOf(Member::class, $model->getMember());
+        $this->assertEquals('Bob Bar', $model->getMember()->getName());
+    }
+}

tests/Model/MailingList/Member/DeleteResponseTest.php

@@ -0,0 +1,35 @@
+<?php
+
+/*
+ * 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\Tests\Model\MailingList\Member;
+
+use Mailgun\Model\MailingList\Member\DeleteResponse;
+use Mailgun\Model\MailingList\Member\Member;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class DeleteResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+  "member": {
+      "address": "bar@example.com"
+  },
+  "message": "Mailing list member has been deleted"
+}
+JSON;
+        $model = DeleteResponse::create(json_decode($json, true));
+        $this->assertEquals('Mailing list member has been deleted', $model->getMessage());
+        $member = $model->getMember();
+        $this->assertInstanceOf(Member::class, $member);
+        $this->assertEquals('bar@example.com', $member->getAddress());
+    }
+}

tests/Model/MailingList/Member/IndexResponseTest.php

@@ -0,0 +1,49 @@
+<?php
+
+/*
+ * 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\Tests\Model\MailingList\Member;
+
+use Mailgun\Model\MailingList\Member\IndexResponse;
+use Mailgun\Model\MailingList\Member\Member;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class IndexResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+  "items": [
+      {
+          "vars": {
+              "age": 26
+          },
+          "name": "Foo Bar",
+          "subscribed": false,
+          "address": "bar@example.com"
+      }
+  ],
+  "paging": {
+    "first": "https://url_to_first_page",
+    "last": "https://url_to_last_page",
+    "next": "http://url_to_next_page",
+    "previous": "http://url_to_previous_page"
+  }
+}
+
+JSON;
+        $model = IndexResponse::create(json_decode($json, true));
+        $members = $model->getItems();
+        $this->assertCount(1, $members);
+        $member = $members[0];
+        $this->assertInstanceOf(Member::class, $member);
+        $this->assertEquals('Foo Bar', $member->getName());
+    }
+}

tests/Model/MailingList/Member/UpdateResponseTest.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * 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\Tests\Model\MailingList\Member;
+
+use Mailgun\Model\MailingList\Member\Member;
+use Mailgun\Model\MailingList\Member\UpdateResponse;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class UpdateResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+  "member": {
+      "vars": {
+          "age": 26
+      },
+      "name": "Foo Bar",
+      "subscribed": false,
+      "address": "bar@example.com"
+  },
+  "message": "Mailing list member has been updated"
+}
+JSON;
+        $model = UpdateResponse::create(json_decode($json, true));
+        $this->assertEquals('Mailing list member has been updated', $model->getMessage());
+        $this->assertInstanceOf(Member::class, $model->getMember());
+        $this->assertEquals('Foo Bar', $model->getMember()->getName());
+    }
+}

tests/Model/MailingList/PagesResponseTest.php

@@ -0,0 +1,55 @@
+<?php
+
+/*
+ * 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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\PagesResponse;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class PagesResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+  "items": [
+    {
+      "access_level": "everyone",
+      "address": "dev@samples.mailgun.org",
+      "created_at": "Tue, 06 Mar 2012 05:44:45 GMT",
+      "description": "Mailgun developers list",
+      "members_count": 1,
+      "name": ""
+    },
+    {
+      "access_level": "readonly",
+      "address": "bar@example.com",
+      "created_at": "Wed, 06 Mar 2013 11:39:51 GMT",
+      "description": "",
+      "members_count": 2,
+      "name": ""
+    }
+  ],
+  "paging": {
+    "first": "https://url_to_next_page",
+    "last": "https://url_to_last_page",
+    "next": "https://url_to_next_page",
+    "previous": "https://url_to_previous_page"
+  }
+}
+JSON;
+        $model = PagesResponse::create(json_decode($json, true));
+        $lists = $model->getLists();
+        $this->assertCount(2, $lists);
+        $list = $lists[0];
+
+        $this->assertEquals('everyone', $list->getAccessLevel());
+    }
+}

tests/Model/MailingList/UpdateResponseTest.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * 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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\CreateResponse;
+use Mailgun\Model\MailingList\MailingList;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class UpdateResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+  "message": "Mailing list has been updated",
+  "list": {
+    "members_count": 7,
+    "description": "My updated test mailing list",
+    "created_at": "Wed, 06 Mar 2013 11:39:51 GMT",
+    "access_level": "readonly",
+    "address": "dev@samples.mailgun.org",
+    "name": "Test List Updated"
+  }
+}
+JSON;
+        $model = CreateResponse::create(json_decode($json, true));
+        $this->assertEquals('Mailing list has been updated', $model->getMessage());
+        $this->assertInstanceOf(MailingList::class, $model->getList());
+        $this->assertEquals(7, $model->getList()->getMembersCount());
+    }
+}