Domain Keys API Endpoints

README.md

@@ -359,3 +359,6 @@ If you find a bug, please submit the issue in Github directly.
 
 As always, if you need additional assistance, drop us a note through your account at
 [https://app.mailgun.com/support](https://app.mailgun.com/support).
+
+## Examples section
+[Examples section](doc/examples.md) contains examples of how to use the SDK.

doc/examples.md

@@ -0,0 +1,58 @@
+## Domain Keys Example
+
+```php
+<?php
+require 'vendor/autoload.php';
+
+use Mailgun\Mailgun;
+
+$mgClient = Mailgun::create('xxx');
+$domain = "xxx.mailgun.org";
+
+try {
+    $res = $mgClient->domainKeys()->listKeysForDomains();
+    print_r($res);
+} catch (Throwable $t) {
+    print_r($t->getMessage());
+    print_r($t->getTraceAsString());
+}
+
+try {
+    $res = $mgClient->domainKeys()->deleteDomainKey($domain, 'xxx');
+} catch (Throwable $t) {
+    print_r($t->getMessage());
+    print_r($t->getTraceAsString());
+}
+
+try {
+    $res = $mgClient->domainKeys()->listDomainKeys($domain);
+    print_r($res);
+} catch (Throwable $t) {
+    print_r($t->getMessage());
+    print_r($t->getTraceAsString());
+}
+try {
+    $res = $mgClient->domainKeys()->createDomainKey($domain, sprintf('key-%s', time()));
+    print_r($res);
+} catch (Throwable $t) {
+    print_r($t->getMessage());
+    print_r($t->getTraceAsString());
+}
+
+try {
+    $res = $mgClient->domainKeys()->deleteDomainKey($domain, 'key-xxx');
+} catch (Throwable $t) {
+    print_r($t->getMessage());
+    print_r($t->getTraceAsString());
+}
+
+
+try {
+    $res = $mgClient->domainKeys()->createDomainKey($domain, sprintf('key-%s', time()));
+    print_r($res);
+} catch (Throwable $t) {
+    print_r($t->getMessage());
+    print_r($t->getTraceAsString());
+}
+
+```

src/Api/DomainKeys.php

@@ -0,0 +1,142 @@
+<?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 Exception;
+use Mailgun\Assert;
+use Mailgun\Model\Domain\DeleteResponse;
+use Mailgun\Model\Domain\DomainKeyResponse;
+use Mailgun\Model\Domain\IndexResponse;
+use Psr\Http\Client\ClientExceptionInterface;
+use Psr\Http\Message\ResponseInterface;
+
+/**
+ * @see https://documentation.mailgun.com/docs/mailgun/api-reference/openapi-final/tag/Domain-Keys/
+ *
+ */
+class DomainKeys extends HttpApi
+{
+    private const BITS_SIZE = ['1024', '2048'];
+
+    /**
+     * Returns a list of domains on the account.
+     * @param int|null $limit
+     * @param string|null $page
+     * @param string|null $signingDomain
+     * @param string|null $selector
+     * @param array $requestHeaders
+     * @return IndexResponse|array
+     * @throws ClientExceptionInterface
+     * @throws \JsonException
+     * @throws Exception
+     */
+    public function listKeysForDomains(?int $limit = null, ?string $page = null, ?string $signingDomain = null, ?string $selector = null, array $requestHeaders = [])
+    {
+        $params = [];
+        if (isset($limit)) {
+            Assert::range($limit, 1, 1000);
+            $params['limit'] = $limit;
+        }
+
+        if (isset($page)) {
+            Assert::stringNotEmpty($page);
+            $params['page'] = $page;
+        }
+
+        if (isset($signingDomain)) {
+            $params['signing_domain'] = $signingDomain;
+        }
+
+        if (isset($selector)) {
+            $params['selector'] = $signingDomain;
+        }
+
+        $response = $this->httpGet('/v1/dkim/keys', $params, $requestHeaders);
+
+        return $this->hydrateResponse($response, IndexResponse::class);
+    }
+
+    /**
+     * Returns a list of domains on the account.
+     * @param string $authorityName
+     * @param array $requestHeaders
+     * @return IndexResponse|array
+     * @throws ClientExceptionInterface
+     * @throws \JsonException
+     * @throws Exception
+     */
+    public function listDomainKeys(string $authorityName, array $requestHeaders = [])
+    {
+        Assert::stringNotEmpty($authorityName);
+
+        $response = $this->httpGet(sprintf('/v4/domains/%s/keys', $authorityName), [], $requestHeaders);
+
+        return $this->hydrateResponse($response, DomainKeyResponse::class);
+    }
+
+    /**
+     * @param string $signingDomain
+     * @param string $selector
+     * @param string|null $bits
+     * @param array $requestHeaders
+     * @return mixed|ResponseInterface
+     * @throws ClientExceptionInterface
+     * @throws \JsonException
+     * @throws Exception
+     */
+    public function createDomainKey(string $signingDomain, string $selector, ?string $bits = null, array $requestHeaders = [])
+    {
+        Assert::stringNotEmpty($signingDomain);
+        Assert::stringNotEmpty($selector);
+
+        $params = [
+            'signing_domain' => $signingDomain,
+            'selector' => $selector,
+        ];
+
+        if (!empty($bits)) {
+            Assert::oneOf(
+                $bits,
+                self::BITS_SIZE,
+                'Length of your domain’s generated DKIM key must be 1024 or 2048'
+            );
+            $params['bits'] = $bits;
+        }
+
+        $response = $this->httpPost('/v1/dkim/keys', $params, $requestHeaders);
+
+        return $this->hydrateResponse($response, DomainKeyResponse::class);
+    }
+
+    /**
+     * @param string $signingDomain
+     * @param string $selector
+     * @param array $requestHeaders
+     * @return mixed|ResponseInterface
+     * @throws ClientExceptionInterface
+     * @throws \JsonException
+     */
+    public function deleteDomainKey(string $signingDomain, string $selector, array $requestHeaders = [])
+    {
+        Assert::stringNotEmpty($signingDomain);
+        Assert::stringNotEmpty($selector);
+
+        $params = [
+            'signing_domain' => $signingDomain,
+            'selector' => $selector,
+        ];
+
+        $response = $this->httpDelete('/v1/dkim/keys', $params, $requestHeaders);
+
+        return $this->hydrateResponse($response, DeleteResponse::class);
+    }
+}

src/Mailgun.php

@@ -14,6 +14,7 @@
 use Http\Client\Common\PluginClient;
 use Mailgun\Api\Attachment;
 use Mailgun\Api\Domain;
+use Mailgun\Api\DomainKeys;
 use Mailgun\Api\EmailValidation;
 use Mailgun\Api\EmailValidationV4;
 use Mailgun\Api\Event;
@@ -263,4 +264,12 @@ public function metrics(): Metrics
     {
         return new Metrics($this->httpClient, $this->requestBuilder, $this->hydrator);
     }
+
+    /**
+     * @return DomainKeys
+     */
+    public function domainKeys(): Api\DomainKeys
+    {
+        return new Api\DomainKeys($this->httpClient, $this->requestBuilder, $this->hydrator);
+    }
 }

src/Model/Domain/DnsRecord.php

@@ -24,6 +24,7 @@ final class DnsRecord
     private ?string $priority;
     private ?string $valid;
     private array $cached;
+    private bool $isActive;
 
     public static function create(array $data): self
     {
@@ -34,6 +35,7 @@ public static function create(array $data): self
         $model->priority = $data['priority'] ?? null;
         $model->valid = $data['valid'] ?? null;
         $model->cached = $data['cached'] ?? [];
+        $model->isActive = $data['is_active'] ?? false;
 
         return $model;
     }
@@ -95,4 +97,21 @@ public function getCached(): array
     {
         return $this->cached;
     }
+
+    /**
+     * @return bool
+     */
+    public function isActive(): bool
+    {
+        return $this->isActive;
+    }
+
+    /**
+     * @param bool $isActive
+     * @return void
+     */
+    public function setIsActive(bool $isActive): void
+    {
+        $this->isActive = $isActive;
+    }
 }

src/Model/Domain/DomainKeyResponse.php

@@ -0,0 +1,123 @@
+<?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;
+
+final class DomainKeyResponse implements ApiResponse
+{
+    private array $items = [];
+    private string $signingDomain;
+    private string $selector;
+    private DnsRecord $dnsRecord;
+
+    /**
+     * @param array $data
+     * @return self
+     */
+    public static function create(array $data): self
+    {
+        if (isset($data['items'])) {
+            $object = new self();
+            $items = [];
+            foreach ($data['items'] as $item) {
+                $model = new self();
+                $model->setSelector($item['selector'] ?? '');
+                $model->setSigningDomain($item['signing_domain'] ?? '');
+                if (!empty($item['dns_record'])) {
+                    $model->setDnsRecord(DnsRecord::create($item['dns_record']));
+                }
+
+                $items[] = $model;
+            }
+            $object->setItems($items);
+
+            return $object;
+        }
+
+        $model = new self();
+        $model->setSelector($data['selector'] ?? '');
+        $model->setDnsRecord(DnsRecord::create($data));
+        $model->setSigningDomain($data['signing_domain'] ?? '');
+
+        return $model;
+    }
+
+    /**
+     * @return string
+     */
+    public function getSigningDomain(): string
+    {
+        return $this->signingDomain;
+    }
+
+    /**
+     * @param string $signingDomain
+     */
+    public function setSigningDomain(string $signingDomain): void
+    {
+        $this->signingDomain = $signingDomain;
+    }
+
+    /**
+     * @return string
+     */
+    public function getSelector(): string
+    {
+        return $this->selector;
+    }
+
+    /**
+     * @param string $selector
+     */
+    public function setSelector(string $selector): void
+    {
+        $this->selector = $selector;
+    }
+
+    /**
+     * @return DnsRecord
+     */
+    public function getDnsRecord(): DnsRecord
+    {
+        return $this->dnsRecord;
+    }
+
+    /**
+     * @param DnsRecord $dnsRecord
+     */
+    public function setDnsRecord(DnsRecord $dnsRecord): void
+    {
+        $this->dnsRecord = $dnsRecord;
+    }
+
+    /**
+     * @return array
+     */
+    public function getItems(): array
+    {
+        return $this->items;
+    }
+
+    /**
+     * @param array $items
+     * @return void
+     */
+    public function setItems(array $items): void
+    {
+        $this->items = $items;
+    }
+
+    private function __construct()
+    {
+    }
+}