From b28633086bfd305c51ca0615ca8c0ba3f76d7185 Mon Sep 17 00:00:00 2001 From: Jake Barnby Date: Wed, 3 Jun 2026 03:09:45 +1200 Subject: [PATCH] feat(messaging): add Amazon SES email provider Wire the Amazon SES adapter shipped in utopia-php/messaging 1.0.0 into the messaging service, mirroring the existing Sendgrid/Mailgun providers. - Bump utopia-php/messaging 0.22.* -> 1.0.* (the 1.0.0 src is byte-identical to 0.22.3 apart from the new SES adapter, so the bump is non-breaking) - Add POST/PATCH /v1/messaging/providers/ses routes (createSesProvider / updateSesProvider), storing accessKey/secretKey/region under credentials and fromName/fromEmail/replyToName/replyToEmail under options, with the same enable-guard and sparse-update semantics as the other email providers - Map the 'ses' provider to the SES adapter in the messaging worker - Add SES reference docs and isolated e2e create/update/delete coverage Co-Authored-By: Claude Opus 4.8 (1M context) --- app/controllers/api/messaging.php | 207 ++++++++++++++++++ composer.json | 2 +- composer.lock | 14 +- .../messaging/create-ses-provider.md | 1 + .../messaging/update-ses-provider.md | 1 + src/Appwrite/Platform/Workers/Messaging.php | 7 + .../e2e/Services/Messaging/MessagingBase.php | 81 +++++++ 7 files changed, 305 insertions(+), 8 deletions(-) create mode 100644 docs/references/messaging/create-ses-provider.md create mode 100644 docs/references/messaging/update-ses-provider.md diff --git a/app/controllers/api/messaging.php b/app/controllers/api/messaging.php index 26f6bf21c4..b1adf60c33 100644 --- a/app/controllers/api/messaging.php +++ b/app/controllers/api/messaging.php @@ -236,6 +236,100 @@ Http::post('/v1/messaging/providers/sendgrid') ->dynamic($provider, Response::MODEL_PROVIDER); }); +Http::post('/v1/messaging/providers/ses') + ->desc('Create Amazon SES provider') + ->groups(['api', 'messaging']) + ->label('audits.event', 'provider.create') + ->label('audits.resource', 'provider/{response.$id}') + ->label('event', 'providers.[providerId].create') + ->label('scope', 'providers.write') + ->label('resourceType', RESOURCE_TYPE_PROVIDERS) + ->label('sdk', new Method( + namespace: 'messaging', + group: 'providers', + name: 'createSesProvider', + description: '/docs/references/messaging/create-ses-provider.md', + auth: [AuthType::ADMIN, AuthType::KEY], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_CREATED, + model: Response::MODEL_PROVIDER, + ) + ] + )) + ->param('providerId', '', fn (Database $dbForProject) => new CustomId(false, $dbForProject->getAdapter()->getMaxUIDLength()), 'Provider ID. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can\'t start with a special char. Max length is 36 chars.', false, ['dbForProject']) + ->param('name', '', new Text(128), 'Provider name.') + ->param('accessKey', '', new Text(0), 'AWS access key ID.', true) + ->param('secretKey', '', new Text(0), 'AWS secret access key.', true) + ->param('region', '', new Text(128), 'AWS region, for example us-east-1.', true) + ->param('fromName', '', new Text(128, 0), 'Sender Name.', true) + ->param('fromEmail', '', new Email(), 'Sender email address.', true) + ->param('replyToName', '', new Text(128, 0), 'Name set in the reply to field for the mail. Default value is sender name.', true) + ->param('replyToEmail', '', new Email(), 'Email set in the reply to field for the mail. Default value is sender email.', true) + ->param('enabled', null, new Nullable(new Boolean()), 'Set as enabled.', true) + ->inject('queueForEvents') + ->inject('dbForProject') + ->inject('response') + ->action(function (string $providerId, string $name, string $accessKey, string $secretKey, string $region, string $fromName, string $fromEmail, string $replyToName, string $replyToEmail, ?bool $enabled, Event $queueForEvents, Database $dbForProject, Response $response) { + $providerId = $providerId == 'unique()' ? ID::unique() : $providerId; + + $credentials = []; + + if (!empty($accessKey)) { + $credentials['accessKey'] = $accessKey; + } + + if (!empty($secretKey)) { + $credentials['secretKey'] = $secretKey; + } + + if (!empty($region)) { + $credentials['region'] = $region; + } + + $options = [ + 'fromName' => $fromName, + 'fromEmail' => $fromEmail, + 'replyToName' => $replyToName, + 'replyToEmail' => $replyToEmail, + ]; + + if ( + $enabled === true + && !empty($fromEmail) + && \array_key_exists('accessKey', $credentials) + && \array_key_exists('secretKey', $credentials) + && \array_key_exists('region', $credentials) + ) { + $enabled = true; + } else { + $enabled = false; + } + + $provider = new Document([ + '$id' => $providerId, + 'name' => $name, + 'provider' => 'ses', + 'type' => MESSAGE_TYPE_EMAIL, + 'enabled' => $enabled, + 'credentials' => $credentials, + 'options' => $options, + ]); + + try { + $provider = $dbForProject->createDocument('providers', $provider); + } catch (DuplicateException) { + throw new Exception(Exception::PROVIDER_ALREADY_EXISTS); + } + + $queueForEvents + ->setParam('providerId', $provider->getId()); + + $response + ->setStatusCode(Response::STATUS_CODE_CREATED) + ->dynamic($provider, Response::MODEL_PROVIDER); + }); + Http::post('/v1/messaging/providers/resend') ->desc('Create Resend provider') ->groups(['api', 'messaging']) @@ -1458,6 +1552,119 @@ Http::patch('/v1/messaging/providers/sendgrid/:providerId') ->dynamic($provider, Response::MODEL_PROVIDER); }); +Http::patch('/v1/messaging/providers/ses/:providerId') + ->desc('Update Amazon SES provider') + ->groups(['api', 'messaging']) + ->label('audits.event', 'provider.update') + ->label('audits.resource', 'provider/{response.$id}') + ->label('event', 'providers.[providerId].update') + ->label('scope', 'providers.write') + ->label('resourceType', RESOURCE_TYPE_PROVIDERS) + ->label('sdk', new Method( + namespace: 'messaging', + group: 'providers', + name: 'updateSesProvider', + description: '/docs/references/messaging/update-ses-provider.md', + auth: [AuthType::ADMIN, AuthType::KEY], + responses: [ + new SDKResponse( + code: Response::STATUS_CODE_OK, + model: Response::MODEL_PROVIDER, + ) + ] + )) + ->param('providerId', '', fn (Database $dbForProject) => new UID($dbForProject->getAdapter()->getMaxUIDLength()), 'Provider ID.', false, ['dbForProject']) + ->param('name', '', new Text(128), 'Provider name.', true) + ->param('enabled', null, new Nullable(new Boolean()), 'Set as enabled.', true) + ->param('accessKey', '', new Text(0), 'AWS access key ID.', true) + ->param('secretKey', '', new Text(0), 'AWS secret access key.', true) + ->param('region', '', new Text(128), 'AWS region, for example us-east-1.', true) + ->param('fromName', '', new Text(128), 'Sender Name.', true) + ->param('fromEmail', '', new Email(), 'Sender email address.', true) + ->param('replyToName', '', new Text(128), 'Name set in the Reply To field for the mail. Default value is Sender Name.', true) + ->param('replyToEmail', '', new Text(128), 'Email set in the Reply To field for the mail. Default value is Sender Email.', true) + ->inject('queueForEvents') + ->inject('dbForProject') + ->inject('response') + ->action(function (string $providerId, string $name, ?bool $enabled, string $accessKey, string $secretKey, string $region, string $fromName, string $fromEmail, string $replyToName, string $replyToEmail, Event $queueForEvents, Database $dbForProject, Response $response) { + $provider = $dbForProject->getDocument('providers', $providerId); + + if ($provider->isEmpty()) { + throw new Exception(Exception::PROVIDER_NOT_FOUND); + } + + $providerAttr = $provider->getAttribute('provider'); + + if ($providerAttr !== 'ses') { + throw new Exception(Exception::PROVIDER_INCORRECT_TYPE); + } + + if (!empty($name)) { + $provider->setAttribute('name', $name); + } + + $options = $provider->getAttribute('options'); + + if (!empty($fromName)) { + $options['fromName'] = $fromName; + } + + if (!empty($fromEmail)) { + $options['fromEmail'] = $fromEmail; + } + + if (!empty($replyToName)) { + $options['replyToName'] = $replyToName; + } + + if (!empty($replyToEmail)) { + $options['replyToEmail'] = $replyToEmail; + } + + $provider->setAttribute('options', $options); + + $credentials = $provider->getAttribute('credentials'); + + if (!empty($accessKey)) { + $credentials['accessKey'] = $accessKey; + } + + if (!empty($secretKey)) { + $credentials['secretKey'] = $secretKey; + } + + if (!empty($region)) { + $credentials['region'] = $region; + } + + $provider->setAttribute('credentials', $credentials); + + if (!\is_null($enabled)) { + if ($enabled) { + if ( + \array_key_exists('accessKey', $credentials) && + \array_key_exists('secretKey', $credentials) && + \array_key_exists('region', $credentials) && + \array_key_exists('fromEmail', $options) + ) { + $provider->setAttribute('enabled', true); + } else { + throw new Exception(Exception::PROVIDER_MISSING_CREDENTIALS); + } + } else { + $provider->setAttribute('enabled', false); + } + } + + $provider = $dbForProject->updateDocument('providers', $provider->getId(), $provider); + + $queueForEvents + ->setParam('providerId', $provider->getId()); + + $response + ->dynamic($provider, Response::MODEL_PROVIDER); + }); + Http::patch('/v1/messaging/providers/resend/:providerId') ->desc('Update Resend provider') ->groups(['api', 'messaging']) diff --git a/composer.json b/composer.json index ad18771699..1e3ce344b8 100644 --- a/composer.json +++ b/composer.json @@ -74,7 +74,7 @@ "utopia-php/locale": "0.8.*", "utopia-php/lock": "0.2.*", "utopia-php/logger": "0.8.*", - "utopia-php/messaging": "0.22.*", + "utopia-php/messaging": "1.0.*", "utopia-php/migration": "1.*", "utopia-php/platform": "1.0.0-rc3", "utopia-php/pools": "1.*", diff --git a/composer.lock b/composer.lock index 70c843efe4..11711529ba 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "ec80b1465e57bc223903fa102249f216", + "content-hash": "551924e300a646e6f433ea0a0f3d6c9f", "packages": [ { "name": "adhocore/jwt", @@ -4606,16 +4606,16 @@ }, { "name": "utopia-php/messaging", - "version": "0.22.3", + "version": "1.0.0", "source": { "type": "git", "url": "https://github.com/utopia-php/messaging.git", - "reference": "67366d5f45cc92efe7adb6aab5d6dcd2342f2f9e" + "reference": "1aca8968c3bf3c78c428a399dfe97cbe9b366ec4" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/utopia-php/messaging/zipball/67366d5f45cc92efe7adb6aab5d6dcd2342f2f9e", - "reference": "67366d5f45cc92efe7adb6aab5d6dcd2342f2f9e", + "url": "https://api.github.com/repos/utopia-php/messaging/zipball/1aca8968c3bf3c78c428a399dfe97cbe9b366ec4", + "reference": "1aca8968c3bf3c78c428a399dfe97cbe9b366ec4", "shasum": "" }, "require": { @@ -4651,9 +4651,9 @@ ], "support": { "issues": "https://github.com/utopia-php/messaging/issues", - "source": "https://github.com/utopia-php/messaging/tree/0.22.3" + "source": "https://github.com/utopia-php/messaging/tree/1.0.0" }, - "time": "2026-05-19T05:31:20+00:00" + "time": "2026-06-02T14:54:22+00:00" }, { "name": "utopia-php/migration", diff --git a/docs/references/messaging/create-ses-provider.md b/docs/references/messaging/create-ses-provider.md new file mode 100644 index 0000000000..c612414f99 --- /dev/null +++ b/docs/references/messaging/create-ses-provider.md @@ -0,0 +1 @@ +Create a new Amazon SES provider. \ No newline at end of file diff --git a/docs/references/messaging/update-ses-provider.md b/docs/references/messaging/update-ses-provider.md new file mode 100644 index 0000000000..79947186e8 --- /dev/null +++ b/docs/references/messaging/update-ses-provider.md @@ -0,0 +1 @@ +Update an Amazon SES provider by its unique ID. \ No newline at end of file diff --git a/src/Appwrite/Platform/Workers/Messaging.php b/src/Appwrite/Platform/Workers/Messaging.php index 7af079e914..759d78f81e 100644 --- a/src/Appwrite/Platform/Workers/Messaging.php +++ b/src/Appwrite/Platform/Workers/Messaging.php @@ -21,6 +21,7 @@ use Utopia\Messaging\Adapter\Email as EmailAdapter; use Utopia\Messaging\Adapter\Email\Mailgun; use Utopia\Messaging\Adapter\Email\Resend; use Utopia\Messaging\Adapter\Email\Sendgrid; +use Utopia\Messaging\Adapter\Email\SES; use Utopia\Messaging\Adapter\Email\SMTP; use Utopia\Messaging\Adapter\Push\APNS; use Utopia\Messaging\Adapter\Push as PushAdapter; @@ -537,6 +538,12 @@ class Messaging extends Action ), 'sendgrid' => new Sendgrid($apiKey), 'resend' => new Resend($apiKey), + 'ses' => new SES( + $credentials['accessKey'] ?? '', + $credentials['secretKey'] ?? '', + $credentials['region'] ?? '', + $credentials['sessionToken'] ?? null, + ), default => null }; } diff --git a/tests/e2e/Services/Messaging/MessagingBase.php b/tests/e2e/Services/Messaging/MessagingBase.php index 43dc58d44c..a18fecf5d2 100644 --- a/tests/e2e/Services/Messaging/MessagingBase.php +++ b/tests/e2e/Services/Messaging/MessagingBase.php @@ -1047,6 +1047,87 @@ trait MessagingBase } } + public function testSesProvider(): void + { + $headers = [ + 'content-type' => 'application/json', + 'x-appwrite-project' => $this->getProject()['$id'], + 'x-appwrite-key' => $this->getProject()['apiKey'], + ]; + + // Create disabled: missing fromEmail and partial credentials. + $response = $this->client->call(Client::METHOD_POST, '/messaging/providers/ses', $headers, [ + 'providerId' => ID::unique(), + 'name' => 'SES1', + 'accessKey' => 'my-access-key', + 'secretKey' => 'my-secret-key', + 'region' => 'us-east-1', + ]); + + $this->assertEquals(201, $response['headers']['status-code']); + $this->assertEquals('SES1', $response['body']['name']); + $this->assertEquals('ses', $response['body']['provider']); + $this->assertEquals('email', $response['body']['type']); + $this->assertEquals(false, $response['body']['enabled']); + $this->assertEquals('my-access-key', $response['body']['credentials']['accessKey']); + $this->assertEquals('my-secret-key', $response['body']['credentials']['secretKey']); + $this->assertEquals('us-east-1', $response['body']['credentials']['region']); + $this->assertArrayHasKey('fromEmail', $response['body']['options']); + $this->assertArrayNotHasKey('accessKey', $response['body']['options']); + + $providerId = $response['body']['$id']; + + // Create enabled: all credentials plus fromEmail present. + $enabledResponse = $this->client->call(Client::METHOD_POST, '/messaging/providers/ses', $headers, [ + 'providerId' => ID::unique(), + 'name' => 'SES-enabled', + 'accessKey' => 'my-access-key', + 'secretKey' => 'my-secret-key', + 'region' => 'us-east-1', + 'fromName' => 'Sender Name', + 'fromEmail' => 'sender-email@my-domain.com', + 'enabled' => true, + ]); + + $this->assertEquals(201, $enabledResponse['headers']['status-code']); + $this->assertEquals(true, $enabledResponse['body']['enabled']); + $this->assertEquals('sender-email@my-domain.com', $enabledResponse['body']['options']['fromEmail']); + + // Sparse update: change only the region, credentials must be preserved. + $updateResponse = $this->client->call(Client::METHOD_PATCH, '/messaging/providers/ses/' . $providerId, $headers, [ + 'name' => 'SES2', + 'region' => 'eu-west-1', + ]); + + $this->assertEquals(200, $updateResponse['headers']['status-code']); + $this->assertEquals('SES2', $updateResponse['body']['name']); + $this->assertEquals('eu-west-1', $updateResponse['body']['credentials']['region']); + $this->assertEquals('my-access-key', $updateResponse['body']['credentials']['accessKey']); + $this->assertEquals('my-secret-key', $updateResponse['body']['credentials']['secretKey']); + + // Enable the first provider once fromEmail is supplied. + $enableResponse = $this->client->call(Client::METHOD_PATCH, '/messaging/providers/ses/' . $providerId, $headers, [ + 'fromEmail' => 'sender-email@my-domain.com', + 'enabled' => true, + ]); + + $this->assertEquals(200, $enableResponse['headers']['status-code']); + $this->assertEquals(true, $enableResponse['body']['enabled']); + + // Updating an SES provider through a different provider route is rejected. + $wrongTypeResponse = $this->client->call(Client::METHOD_PATCH, '/messaging/providers/sendgrid/' . $providerId, $headers, [ + 'name' => 'Wrong', + ]); + + $this->assertEquals(400, $wrongTypeResponse['headers']['status-code']); + + $deleteResponse = $this->client->call(Client::METHOD_DELETE, '/messaging/providers/' . $providerId, $headers); + $this->assertEquals(204, $deleteResponse['headers']['status-code']); + + $deleteEnabledResponse = $this->client->call(Client::METHOD_DELETE, '/messaging/providers/' . $enabledResponse['body']['$id'], $headers); + $this->assertEquals(204, $deleteEnabledResponse['headers']['status-code']); + } + public function testCreateTopic(): void { $response1 = $this->client->call(Client::METHOD_POST, '/messaging/topics', [