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) <noreply@anthropic.com>
This commit is contained in:
Jake BarnbyandClaude Opus 4.8 committed 2026-06-03 03:09:45 +12:00
1 parent 69b49c7228
commit b28633086b
7 files changed
+305 -8

No files matched your search

+207
View File
@@ -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'])
+1 -1
View File
@@ -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.*",
Generated
+7 -7
View File
@@ -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",
@@ -0,0 +1 @@
Create a new Amazon SES provider.
@@ -0,0 +1 @@
Update an Amazon SES provider by its unique ID.
@@ -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
};
}
@@ -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', [