Add SESv2 suppressed destination deletion and retrieval methods (#1834)

manifest.json

@@ -592,6 +592,8 @@
             "example": "https://raw.githubusercontent.com/aws/aws-sdk-php/${LATEST}/src/data/email/2010-12-01/examples-1.json",
             "api-reference": "https://docs.aws.amazon.com/ses/latest/APIReference-V2",
             "methods": [
+                "DeleteSuppressedDestination",
+                "GetSuppressedDestination",
                 "SendEmail"
             ],
             "alternative-names": [

src/Service/Ses/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## NOT RELEASED
 
+### Added
+
+- Added support for `getSuppressedDestination` and `deleteSuppressedDestination` to manage SESv2 suppression list entries.
+
 ## 1.10.0
 
 ### Added

src/Service/Ses/composer.json

@@ -27,7 +27,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.10-dev"
+            "dev-master": "1.11-dev"
         }
     }
 }

src/Service/Ses/src/Enum/SuppressionListReason.php

@@ -0,0 +1,26 @@
+<?php
+
+namespace AsyncAws\Ses\Enum;
+
+/**
+ * The reason that the address was added to the suppression list for your account. The value can be one of the
+ * following:
+ *
+ * - `COMPLAINT` – Amazon SES added an email address to the suppression list for your account because a message sent
+ *   to that address results in a complaint.
+ * - `BOUNCE` – Amazon SES added an email address to the suppression list for your account because a message sent to
+ *   that address results in a hard bounce.
+ */
+final class SuppressionListReason
+{
+    public const BOUNCE = 'BOUNCE';
+    public const COMPLAINT = 'COMPLAINT';
+
+    public static function exists(string $value): bool
+    {
+        return isset([
+            self::BOUNCE => true,
+            self::COMPLAINT => true,
+        ][$value]);
+    }
+}

src/Service/Ses/src/Input/DeleteSuppressedDestinationRequest.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace AsyncAws\Ses\Input;
+
+use AsyncAws\Core\Exception\InvalidArgument;
+use AsyncAws\Core\Input;
+use AsyncAws\Core\Request;
+use AsyncAws\Core\Stream\StreamFactory;
+
+/**
+ * A request to remove an email address from the suppression list for your account.
+ */
+final class DeleteSuppressedDestinationRequest extends Input
+{
+    /**
+     * The suppressed email destination to remove from the account suppression list.
+     *
+     * @required
+     *
+     * @var string|null
+     */
+    private $emailAddress;
+
+    /**
+     * @param array{
+     *   EmailAddress?: string,
+     *   '@region'?: string|null,
+     * } $input
+     */
+    public function __construct(array $input = [])
+    {
+        $this->emailAddress = $input['EmailAddress'] ?? null;
+        parent::__construct($input);
+    }
+
+    /**
+     * @param array{
+     *   EmailAddress?: string,
+     *   '@region'?: string|null,
+     * }|DeleteSuppressedDestinationRequest $input
+     */
+    public static function create($input): self
+    {
+        return $input instanceof self ? $input : new self($input);
+    }
+
+    public function getEmailAddress(): ?string
+    {
+        return $this->emailAddress;
+    }
+
+    /**
+     * @internal
+     */
+    public function request(): Request
+    {
+        // Prepare headers
+        $headers = [
+            'Content-Type' => 'application/json',
+            'Accept' => 'application/json',
+        ];
+
+        // Prepare query
+        $query = [];
+
+        // Prepare URI
+        $uri = [];
+        if (null === $v = $this->emailAddress) {
+            throw new InvalidArgument(\sprintf('Missing parameter "EmailAddress" for "%s". The value cannot be null.', __CLASS__));
+        }
+        $uri['EmailAddress'] = $v;
+        $uriString = '/v2/email/suppression/addresses/' . rawurlencode($uri['EmailAddress']);
+
+        // Prepare Body
+        $body = '';
+
+        // Return the Request
+        return new Request('DELETE', $uriString, $query, $headers, StreamFactory::create($body));
+    }
+
+    public function setEmailAddress(?string $value): self
+    {
+        $this->emailAddress = $value;
+
+        return $this;
+    }
+}

src/Service/Ses/src/Input/GetSuppressedDestinationRequest.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace AsyncAws\Ses\Input;
+
+use AsyncAws\Core\Exception\InvalidArgument;
+use AsyncAws\Core\Input;
+use AsyncAws\Core\Request;
+use AsyncAws\Core\Stream\StreamFactory;
+
+/**
+ * A request to retrieve information about an email address that's on the suppression list for your account.
+ */
+final class GetSuppressedDestinationRequest extends Input
+{
+    /**
+     * The email address that's on the account suppression list.
+     *
+     * @required
+     *
+     * @var string|null
+     */
+    private $emailAddress;
+
+    /**
+     * @param array{
+     *   EmailAddress?: string,
+     *   '@region'?: string|null,
+     * } $input
+     */
+    public function __construct(array $input = [])
+    {
+        $this->emailAddress = $input['EmailAddress'] ?? null;
+        parent::__construct($input);
+    }
+
+    /**
+     * @param array{
+     *   EmailAddress?: string,
+     *   '@region'?: string|null,
+     * }|GetSuppressedDestinationRequest $input
+     */
+    public static function create($input): self
+    {
+        return $input instanceof self ? $input : new self($input);
+    }
+
+    public function getEmailAddress(): ?string
+    {
+        return $this->emailAddress;
+    }
+
+    /**
+     * @internal
+     */
+    public function request(): Request
+    {
+        // Prepare headers
+        $headers = [
+            'Content-Type' => 'application/json',
+            'Accept' => 'application/json',
+        ];
+
+        // Prepare query
+        $query = [];
+
+        // Prepare URI
+        $uri = [];
+        if (null === $v = $this->emailAddress) {
+            throw new InvalidArgument(\sprintf('Missing parameter "EmailAddress" for "%s". The value cannot be null.', __CLASS__));
+        }
+        $uri['EmailAddress'] = $v;
+        $uriString = '/v2/email/suppression/addresses/' . rawurlencode($uri['EmailAddress']);
+
+        // Prepare Body
+        $body = '';
+
+        // Return the Request
+        return new Request('GET', $uriString, $query, $headers, StreamFactory::create($body));
+    }
+
+    public function setEmailAddress(?string $value): self
+    {
+        $this->emailAddress = $value;
+
+        return $this;
+    }
+}

src/Service/Ses/src/Result/DeleteSuppressedDestinationResponse.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace AsyncAws\Ses\Result;
+
+use AsyncAws\Core\Result;
+
+/**
+ * An HTTP 200 response if the request succeeds, or an error message if the request fails.
+ */
+class DeleteSuppressedDestinationResponse extends Result
+{
+}

src/Service/Ses/src/Result/GetSuppressedDestinationResponse.php

@@ -0,0 +1,53 @@
+<?php
+
+namespace AsyncAws\Ses\Result;
+
+use AsyncAws\Core\Response;
+use AsyncAws\Core\Result;
+use AsyncAws\Ses\ValueObject\SuppressedDestination;
+use AsyncAws\Ses\ValueObject\SuppressedDestinationAttributes;
+
+/**
+ * Information about the suppressed email address.
+ */
+class GetSuppressedDestinationResponse extends Result
+{
+    /**
+     * An object containing information about the suppressed email address.
+     *
+     * @var SuppressedDestination
+     */
+    private $suppressedDestination;
+
+    public function getSuppressedDestination(): SuppressedDestination
+    {
+        $this->initialize();
+
+        return $this->suppressedDestination;
+    }
+
+    protected function populateResult(Response $response): void
+    {
+        $data = $response->toArray();
+
+        $this->suppressedDestination = $this->populateResultSuppressedDestination($data['SuppressedDestination']);
+    }
+
+    private function populateResultSuppressedDestination(array $json): SuppressedDestination
+    {
+        return new SuppressedDestination([
+            'EmailAddress' => (string) $json['EmailAddress'],
+            'Reason' => (string) $json['Reason'],
+            'LastUpdateTime' => /** @var \DateTimeImmutable $d */ $d = \DateTimeImmutable::createFromFormat('U.u', \sprintf('%.6F', $json['LastUpdateTime'])),
+            'Attributes' => empty($json['Attributes']) ? null : $this->populateResultSuppressedDestinationAttributes($json['Attributes']),
+        ]);
+    }
+
+    private function populateResultSuppressedDestinationAttributes(array $json): SuppressedDestinationAttributes
+    {
+        return new SuppressedDestinationAttributes([
+            'MessageId' => isset($json['MessageId']) ? (string) $json['MessageId'] : null,
+            'FeedbackId' => isset($json['FeedbackId']) ? (string) $json['FeedbackId'] : null,
+        ]);
+    }
+}

src/Service/Ses/src/SesClient.php

@@ -15,7 +15,11 @@
 use AsyncAws\Ses\Exception\NotFoundException;
 use AsyncAws\Ses\Exception\SendingPausedException;
 use AsyncAws\Ses\Exception\TooManyRequestsException;
+use AsyncAws\Ses\Input\DeleteSuppressedDestinationRequest;
+use AsyncAws\Ses\Input\GetSuppressedDestinationRequest;
 use AsyncAws\Ses\Input\SendEmailRequest;
+use AsyncAws\Ses\Result\DeleteSuppressedDestinationResponse;
+use AsyncAws\Ses\Result\GetSuppressedDestinationResponse;
 use AsyncAws\Ses\Result\SendEmailResponse;
 use AsyncAws\Ses\ValueObject\Destination;
 use AsyncAws\Ses\ValueObject\EmailContent;
@@ -24,6 +28,60 @@
 
 class SesClient extends AbstractApi
 {
+    /**
+     * Removes an email address from the suppression list for your account.
+     *
+     * @see https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_DeleteSuppressedDestination.html
+     * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2019-09-27.html#deletesuppresseddestination
+     *
+     * @param array{
+     *   EmailAddress: string,
+     *   '@region'?: string|null,
+     * }|DeleteSuppressedDestinationRequest $input
+     *
+     * @throws NotFoundException
+     * @throws BadRequestException
+     * @throws TooManyRequestsException
+     */
+    public function deleteSuppressedDestination($input): DeleteSuppressedDestinationResponse
+    {
+        $input = DeleteSuppressedDestinationRequest::create($input);
+        $response = $this->getResponse($input->request(), new RequestContext(['operation' => 'DeleteSuppressedDestination', 'region' => $input->getRegion(), 'exceptionMapping' => [
+            'NotFoundException' => NotFoundException::class,
+            'BadRequestException' => BadRequestException::class,
+            'TooManyRequestsException' => TooManyRequestsException::class,
+        ]]));
+
+        return new DeleteSuppressedDestinationResponse($response);
+    }
+
+    /**
+     * Retrieves information about a specific email address that's on the suppression list for your account.
+     *
+     * @see https://docs.aws.amazon.com/ses/latest/APIReference-V2/API_GetSuppressedDestination.html
+     * @see https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-email-2019-09-27.html#getsuppresseddestination
+     *
+     * @param array{
+     *   EmailAddress: string,
+     *   '@region'?: string|null,
+     * }|GetSuppressedDestinationRequest $input
+     *
+     * @throws BadRequestException
+     * @throws TooManyRequestsException
+     * @throws NotFoundException
+     */
+    public function getSuppressedDestination($input): GetSuppressedDestinationResponse
+    {
+        $input = GetSuppressedDestinationRequest::create($input);
+        $response = $this->getResponse($input->request(), new RequestContext(['operation' => 'GetSuppressedDestination', 'region' => $input->getRegion(), 'exceptionMapping' => [
+            'BadRequestException' => BadRequestException::class,
+            'TooManyRequestsException' => TooManyRequestsException::class,
+            'NotFoundException' => NotFoundException::class,
+        ]]));
+
+        return new GetSuppressedDestinationResponse($response);
+    }
+
     /**
      * Sends an email message. You can use the Amazon SES API v2 to send the following types of messages:
      *