mailing list validation

src/Api/MailingList.php

@@ -13,11 +13,14 @@ namespace Mailgun\Api;
 
 use Mailgun\Api\MailingList\Member;
 use Mailgun\Assert;
+use Mailgun\Model\EmailValidation\ValidateResponse;
 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;
+use Mailgun\Model\MailingList\ValidationCancelResponse;
+use Mailgun\Model\MailingList\ValidationStatusResponse;
 
 /**
  * @see https://documentation.mailgun.com/en/latest/api-mailinglists.html
@@ -154,4 +157,58 @@ class MailingList extends HttpApi
 
         return $this->hydrateResponse($response, DeleteResponse::class);
     }
+
+    /**
+     * Validates mailing list.
+     *
+     * @param string $address Address of the mailing list
+     *
+     * @return ValidateResponse
+     *
+     * @throws \Exception
+     */
+    public function validate(string $address)
+    {
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpPost(sprintf('/v3/lists/%s/validate', $address));
+
+        return $this->hydrateResponse($response, ValidateResponse::class);
+    }
+
+    /**
+     * Get mailing list validation status.
+     *
+     * @param string $address Address of the mailing list
+     *
+     * @return ValidationStatusResponse
+     *
+     * @throws \Exception
+     */
+    public function getValidationStatus(string $address)
+    {
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpGet(sprintf('/v3/lists/%s/validate', $address));
+
+        return $this->hydrateResponse($response, ValidationStatusResponse::class);
+    }
+
+    /**
+     * Cancel mailing list validation.
+     *
+     * @param string $address Address of the mailing list
+     *
+     * @return ValidationCancelResponse
+     *
+     * @throws \Exception
+     */
+    public function cancelValidation(string $address)
+    {
+        Assert::stringNotEmpty($address);
+
+        $response = $this->httpDelete(sprintf('/v3/lists/%s/validate', $address));
+
+        return $this->hydrateResponse($response, ValidationCancelResponse::class);
+    }
 }

src/Model/MailingList/ValidateResponse.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\Model\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class ValidateResponse implements ApiResponse
+{
+    private $id;
+    private $message;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->id = $data['id'] ?? '';
+        $model->message = $data['message'] ?? '';
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getMessage(): string
+    {
+        return $this->message;
+    }
+
+    public function getId(): string
+    {
+        return $this->id;
+    }
+}

src/Model/MailingList/ValidationCancelResponse.php

@@ -0,0 +1,36 @@
+<?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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class ValidationCancelResponse 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/MailingList/ValidationStatusDownloadUrl.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\Model\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class ValidationStatusDownloadUrl implements ApiResponse
+{
+    private $csv;
+    private $json;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->csv = $data['csv'] ?? '';
+        $model->json = $data['json'] ?? '';
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getCsv(): string
+    {
+        return $this->csv;
+    }
+
+    public function getJson(): string
+    {
+        return $this->json;
+    }
+}

src/Model/MailingList/ValidationStatusResponse.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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class ValidationStatusResponse implements ApiResponse
+{
+    private $createdAt;
+    private $downloadUrl;
+    private $id;
+    private $quantity;
+    private $recordsProcessed;
+    private $status;
+    private $summary;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->id = $data['id'] ?? '';
+        $model->createdAt = $data['created_at'] ?? null;
+        $model->downloadUrl = ValidationStatusDownloadUrl::create($data['download_url']);
+        $model->id = $data['id'] ?? '';
+        $model->quantity = $data['quantity'] ?? 0;
+        $model->recordsProcessed = $data['records_processed'] ?? 0;
+        $model->status = $data['status'] ?? '';
+        $model->summary = ValidationStatusSummary::create($data['summary'] ?? []);
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getCreatedAt(): string
+    {
+        return $this->createdAt;
+    }
+
+    public function getDownloadUrl(): ValidationStatusDownloadUrl
+    {
+        return $this->downloadUrl;
+    }
+
+    public function getId(): string
+    {
+        return $this->id;
+    }
+
+    public function getQuantity(): int
+    {
+        return $this->quantity;
+    }
+
+    public function getRecordsProcessed(): int
+    {
+        return $this->recordsProcessed;
+    }
+
+    public function getStatus(): string
+    {
+        return $this->status;
+    }
+
+    public function getSummary(): ValidationStatusSummary
+    {
+        return $this->summary;
+    }
+}

src/Model/MailingList/ValidationStatusSummary.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\Model\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class ValidationStatusSummary implements ApiResponse
+{
+    private $result;
+    private $risk;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->result = ValidationStatusSummaryResult::create($data['result'] ?? []);
+        $model->risk = ValidationStatusSummaryRisk::create($data['risk'] ?? []);
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getResult(): ValidationStatusSummaryResult
+    {
+        return $this->result;
+    }
+
+    public function getRisk(): ValidationStatusSummaryRisk
+    {
+        return $this->risk;
+    }
+}

src/Model/MailingList/ValidationStatusSummaryResult.php

@@ -0,0 +1,57 @@
+<?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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class ValidationStatusSummaryResult implements ApiResponse
+{
+    private $deliverable;
+    private $doNotSend;
+    private $undeliverable;
+    private $unknown;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->deliverable = $data['deliverable'] ?? null;
+        $model->doNotSend = $data['do_not_send'] ?? null;
+        $model->undeliverable = $data['undeliverable'] ?? null;
+        $model->unknown = $data['unknown'] ?? null;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getDeliverable(): ?int
+    {
+        return $this->deliverable;
+    }
+
+    public function getDoNotSend(): ?int
+    {
+        return $this->doNotSend;
+    }
+
+    public function getUndeliverable(): ?int
+    {
+        return $this->undeliverable;
+    }
+
+    public function getUnknown(): ?int
+    {
+        return $this->unknown;
+    }
+}

src/Model/MailingList/ValidationStatusSummaryRisk.php

@@ -0,0 +1,57 @@
+<?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\MailingList;
+
+use Mailgun\Model\ApiResponse;
+
+final class ValidationStatusSummaryRisk implements ApiResponse
+{
+    private $high;
+    private $low;
+    private $medium;
+    private $unknown;
+
+    public static function create(array $data): self
+    {
+        $model = new self();
+        $model->high = $data['high'] ?? null;
+        $model->low = $data['low'] ?? null;
+        $model->medium = $data['medium'] ?? null;
+        $model->unknown = $data['unknown'] ?? null;
+
+        return $model;
+    }
+
+    private function __construct()
+    {
+    }
+
+    public function getHigh(): ?int
+    {
+        return $this->high;
+    }
+
+    public function getLow(): ?int
+    {
+        return $this->low;
+    }
+
+    public function getMedium(): ?int
+    {
+        return $this->medium;
+    }
+
+    public function getUnknown(): ?int
+    {
+        return $this->unknown;
+    }
+}

tests/Api/MailingListTest.php

@@ -14,6 +14,9 @@ namespace Mailgun\Tests\Api;
 use GuzzleHttp\Psr7\Response;
 use Mailgun\Api\MailingList;
 use Mailgun\Exception\InvalidArgumentException;
+use Mailgun\Model\EmailValidation\ValidateResponse;
+use Mailgun\Model\MailingList\ValidationCancelResponse;
+use Mailgun\Model\MailingList\ValidationStatusResponse;
 
 class MailingListTest extends TestCase
 {
@@ -133,6 +136,36 @@ class MailingListTest extends TestCase
         $api->delete('address');
     }
 
+    public function testValidate()
+    {
+        $this->setRequestMethod('POST');
+        $this->setRequestUri('/v3/lists/address@domain/validate');
+        $this->setHydrateClass(ValidateResponse::class);
+
+        $api = $this->getApiInstance();
+        $api->validate('address@domain');
+    }
+
+    public function testValidationStatus()
+    {
+        $this->setRequestMethod('GET');
+        $this->setRequestUri('/v3/lists/address@domain/validate');
+        $this->setHydrateClass(ValidationStatusResponse::class);
+
+        $api = $this->getApiInstance();
+        $api->getValidationStatus('address@domain');
+    }
+
+    public function testCancelValidate()
+    {
+        $this->setRequestMethod('DELETE');
+        $this->setRequestUri('/v3/lists/address@domain/validate');
+        $this->setHydrateClass(ValidationCancelResponse::class);
+
+        $api = $this->getApiInstance();
+        $api->cancelValidation('address@domain');
+    }
+
     /**
      * {@inheritdoc}
      */

tests/Model/MailingList/ValidateResponseTest.php

@@ -0,0 +1,32 @@
+<?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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\ValidateResponse;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class ValidateResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+    "id": "listname@yourdomain.com",
+    "message": "The validation job was submitted."
+}
+JSON;
+        $model = ValidateResponse::create(json_decode($json, true));
+        $this->assertEquals('The validation job was submitted.', $model->getMessage());
+        $this->assertEquals('listname@yourdomain.com', $model->getId());
+    }
+}

tests/Model/MailingList/ValidationCancelResponseTest.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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\ValidationCancelResponse;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class ValidationCancelResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+            <<<'JSON'
+{
+    "message": "Validation job canceled."
+}
+JSON;
+        $model = ValidationCancelResponse::create(json_decode($json, true));
+        $this->assertEquals('Validation job canceled.', $model->getMessage());
+    }
+}

tests/Model/MailingList/ValidationStatusDownloadUrlTest.php

@@ -0,0 +1,32 @@
+<?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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\ValidationStatusDownloadUrl;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class ValidationStatusDownloadUrlTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+            <<<'JSON'
+{
+    "csv": "http://example.com/filname.csv",
+    "json": "http://example.com/filname.json"
+}
+JSON;
+        $model = ValidationStatusDownloadUrl::create(json_decode($json, true));
+        $this->assertEquals('http://example.com/filname.csv', $model->getCsv());
+        $this->assertEquals('http://example.com/filname.json', $model->getJson());
+    }
+}

tests/Model/MailingList/ValidationStatusResponseTest.php

@@ -0,0 +1,74 @@
+<?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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\ValidationStatusDownloadUrl;
+use Mailgun\Model\MailingList\ValidationStatusResponse;
+use Mailgun\Model\MailingList\ValidationStatusSummary;
+use Mailgun\Model\MailingList\ValidationStatusSummaryResult;
+use Mailgun\Model\MailingList\ValidationStatusSummaryRisk;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class ValidationStatusResponseTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+<<<'JSON'
+{
+    "created_at": "Tue, 26 Feb 2019 21:30:03 GMT",
+    "download_url": {
+        "csv": "http://example.com/filname.csv",
+        "json": "http://example.com/filname.json"
+    },
+    "id": "listname@mydomain.sandbox.mailgun.org",
+    "quantity": 207665,
+    "records_processed": 207665,
+    "status": "uploaded",
+    "summary": {
+        "result": {
+            "deliverable": 184199,
+            "do_not_send": 5647,
+            "undeliverable": 12116,
+            "unknown": 5613
+        },
+        "risk": {
+            "high": 17763,
+            "low": 142547,
+            "medium": 41652,
+            "unknown": 5614
+        }
+    }
+}
+JSON;
+        $model = ValidationStatusResponse::create(json_decode($json, true));
+        $this->assertEquals('Tue, 26 Feb 2019 21:30:03 GMT', $model->getCreatedAt());
+        $this->assertInstanceOf(ValidationStatusDownloadUrl::class, $model->getDownloadUrl());
+        $this->assertEquals('http://example.com/filname.csv', $model->getDownloadUrl()->getCsv());
+        $this->assertEquals('http://example.com/filname.json', $model->getDownloadUrl()->getJson());
+        $this->assertEquals('listname@mydomain.sandbox.mailgun.org', $model->getId());
+        $this->assertEquals(207665, $model->getQuantity());
+        $this->assertEquals(207665, $model->getRecordsProcessed());
+        $this->assertEquals('uploaded', $model->getStatus());
+        $this->assertInstanceOf(ValidationStatusSummary::class, $model->getSummary());
+        $this->assertInstanceOf(ValidationStatusSummaryResult::class, $model->getSummary()->getResult());
+        $this->assertEquals(184199, $model->getSummary()->getResult()->getDeliverable());
+        $this->assertEquals(5647, $model->getSummary()->getResult()->getDoNotSend());
+        $this->assertEquals(12116, $model->getSummary()->getResult()->getUndeliverable());
+        $this->assertEquals(5613, $model->getSummary()->getResult()->getUnknown());
+        $this->assertInstanceOf(ValidationStatusSummaryRisk::class, $model->getSummary()->getRisk());
+        $this->assertEquals(17763, $model->getSummary()->getRisk()->getHigh());
+        $this->assertEquals(142547, $model->getSummary()->getRisk()->getLow());
+        $this->assertEquals(41652, $model->getSummary()->getRisk()->getMedium());
+        $this->assertEquals(5614, $model->getSummary()->getRisk()->getUnknown());
+    }
+}

tests/Model/MailingList/ValidationStatusSummaryResultTest.php

@@ -0,0 +1,36 @@
+<?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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\ValidationStatusSummaryResult;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class ValidationStatusSummaryResultTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+            <<<'JSON'
+{
+    "deliverable": 184199,
+    "do_not_send": 5647,
+    "undeliverable": 12116,
+    "unknown": 5613
+}
+JSON;
+        $model = ValidationStatusSummaryResult::create(json_decode($json, true));
+        $this->assertEquals(184199, $model->getDeliverable());
+        $this->assertEquals(5647, $model->getDoNotSend());
+        $this->assertEquals(12116, $model->getUndeliverable());
+        $this->assertEquals(5613, $model->getUnknown());
+    }
+}

tests/Model/MailingList/ValidationStatusSummaryRiskTest.php

@@ -0,0 +1,36 @@
+<?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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\ValidationStatusSummaryRisk;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class ValidationStatusSummaryRiskTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+            <<<'JSON'
+{
+    "high": 17763,
+    "low": 142547,
+    "medium": 41652,
+    "unknown": 5614
+}
+JSON;
+        $model = ValidationStatusSummaryRisk::create(json_decode($json, true));
+        $this->assertEquals(17763, $model->getHigh());
+        $this->assertEquals(142547, $model->getLow());
+        $this->assertEquals(41652, $model->getMedium());
+        $this->assertEquals(5614, $model->getUnknown());
+    }
+}

tests/Model/MailingList/ValidationStatusSummaryTest.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\Tests\Model\MailingList;
+
+use Mailgun\Model\MailingList\ValidationStatusSummary;
+use Mailgun\Model\MailingList\ValidationStatusSummaryResult;
+use Mailgun\Model\MailingList\ValidationStatusSummaryRisk;
+use Mailgun\Tests\Model\BaseModelTest;
+
+class ValidationStatusSummaryTest extends BaseModelTest
+{
+    public function testCreate()
+    {
+        $json =
+            <<<'JSON'
+{
+    "result": {
+        "deliverable": 184199,
+        "do_not_send": 5647,
+        "undeliverable": 12116,
+        "unknown": 5613
+    },
+    "risk": {
+        "high": 17763,
+        "low": 142547,
+        "medium": 41652,
+        "unknown": 5614
+    }
+}
+JSON;
+        $model = ValidationStatusSummary::create(json_decode($json, true));
+        $this->assertInstanceOf(ValidationStatusSummaryResult::class, $model->getResult());
+        $this->assertEquals(184199, $model->getResult()->getDeliverable());
+        $this->assertEquals(5647, $model->getResult()->getDoNotSend());
+        $this->assertEquals(12116, $model->getResult()->getUndeliverable());
+        $this->assertEquals(5613, $model->getResult()->getUnknown());
+
+        $this->assertInstanceOf(ValidationStatusSummaryRisk::class, $model->getRisk());
+        $this->assertEquals(17763, $model->getRisk()->getHigh());
+        $this->assertEquals(142547, $model->getRisk()->getLow());
+        $this->assertEquals(41652, $model->getRisk()->getMedium());
+        $this->assertEquals(5614, $model->getRisk()->getUnknown());
+    }
+}