Skip to content

armgit / floci

Public Imported from GitHub
0

Light, fluffy, and always free - The AWS Local Emulator alternative

docs: add SES documentation (#181)

Cyril Schumacherfe2480e5962d
diff --git a/docs/index.md b/docs/index.md
index af025b06bf..5261572fb0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -17,6 +17,7 @@ Floci is a fast, free, and open-source local AWS service emulator built for deve
| SSM Parameter Store | JSON 1.1 |
| SQS | Query / JSON |
| SNS | Query / JSON |
+| SES | Query |
| S3 | REST XML |
| DynamoDB + Streams | JSON 1.1 |
| Lambda | REST JSON |
diff --git a/docs/services/index.md b/docs/services/index.md
index 4db52f435a..3198ad4b5f 100644
--- a/docs/services/index.md
+++ b/docs/services/index.md
@@ -9,6 +9,7 @@ Floci emulates 25 AWS services on a single port (`4566`). All services use the r
| [SSM](ssm.md) | `POST /` + `X-Amz-Target: AmazonSSM.*` | JSON 1.1 | 12 |
| [SQS](sqs.md) | `POST /` with `Action=` param | Query / JSON | 20 |
| [SNS](sns.md) | `POST /` with `Action=` param | Query / JSON | 17 |
+| [SES](ses.md) | `POST /` with `Action=` param | Query | 16 |
| [S3](s3.md) | `/{bucket}/{key}` | REST XML | 50+ |
| [DynamoDB](dynamodb.md) | `POST /` + `X-Amz-Target: DynamoDB_20120810.*` | JSON 1.1 | 19 |
| [DynamoDB Streams](dynamodb.md#streams) | `POST /` + `X-Amz-Target: DynamoDBStreams_20120810.*` | JSON 1.1 | 4 |
diff --git a/docs/services/ses.md b/docs/services/ses.md
new file mode 100644
index 0000000000..9b0eeb57ea
--- /dev/null
+++ b/docs/services/ses.md
@@ -0,0 +1,95 @@
+# SES
+
+**Protocol:** Query (XML) with `Action=` parameter
+**Endpoint:** `POST http://localhost:4566/`
+
+Floci exposes the classic Amazon SES Query API used by `aws ses ...` commands and SDKs targeting SES v1.
+
+## Supported Actions
+
+| Action | Description |
+|-------------------------------------|-----------------------------------------------------------|
+| `VerifyEmailIdentity` | Mark an email address as verified |
+| `VerifyEmailAddress` | Legacy alias for email verification |
+| `VerifyDomainIdentity` | Mark a domain as verified and return a verification token |
+| `DeleteIdentity` | Delete an email or domain identity |
+| `ListIdentities` | List verified identities |
+| `GetIdentityVerificationAttributes` | Get verification status for one or more identities |
+| `SendEmail` | Send a structured email with text or HTML body |
+| `SendRawEmail` | Send a raw MIME payload |
+| `GetSendQuota` | Return local send quota counters |
+| `GetSendStatistics` | Return aggregate delivery stats for sent messages |
+| `GetAccountSendingEnabled` | Report whether sending is enabled |
+| `ListVerifiedEmailAddresses` | List verified email identities |
+| `DeleteVerifiedEmailAddress` | Delete a verified email identity |
+| `SetIdentityNotificationTopic` | Store SNS notification topic ARNs for an identity |
+| `GetIdentityNotificationAttributes` | Read stored notification topic settings |
+| `GetIdentityDkimAttributes` | Return DKIM status for identities |
+
+## Configuration
+
+```yaml
+floci:
+ services:
+ ses:
+ enabled: true
+```
+
+## Examples
+
+```bash
+export AWS_ENDPOINT=http://localhost:4566
+
+# Verify sender and recipient identities
+aws ses verify-email-identity \
+ --email-address [email protected] \
+ --endpoint-url $AWS_ENDPOINT
+
+aws ses verify-email-identity \
+ --email-address [email protected] \
+ --endpoint-url $AWS_ENDPOINT
+
+# Verify a domain
+aws ses verify-domain-identity \
+ --domain example.com \
+ --endpoint-url $AWS_ENDPOINT
+
+# List all identities
+aws ses list-identities \
+ --endpoint-url $AWS_ENDPOINT
+
+# Send a plain-text email
+aws ses send-email \
+ --destination [email protected] \
+ --message "Subject={Data=Hello},Body={Text={Data=Sent from Floci SES}}" \
+ --endpoint-url $AWS_ENDPOINT
+
+# Send a raw MIME email
+aws ses send-raw-email \
+ --raw-message Data="$(printf 'Subject: Raw test\r\n\r\nHello from raw SES')" \
+ --source [email protected] \
+ --destinations [email protected] \
+ --endpoint-url $AWS_ENDPOINT
+
+# Inspect locally captured messages
+curl $AWS_ENDPOINT/_aws/ses
+```
+
+## Local Inspection Endpoint
+
+For test assertions and debugging, Floci exposes a LocalStack-compatible mailbox endpoint:
+
+- `GET /_aws/ses` lists captured messages
+- `GET /_aws/ses?id=<message-id>` returns a specific captured message
+- `DELETE /_aws/ses` clears the captured mailbox
+
+Messages are stored locally by Floci and can be persisted when SES storage is backed by persistent or hybrid storage.
+
+## Current Behavior
+
+- Identity verification succeeds immediately; no real DNS or inbox verification flow is required.
+- `SendEmail` stores the text body or the HTML body as the captured message body.
+- `SetIdentityNotificationTopic` stores SNS topic ARNs and returns them via `GetIdentityNotificationAttributes`.
+- Notification topics are configuration metadata only; SES delivery, bounce, or complaint events are not emitted automatically.
+- SES currently exposes the Query API only; SMTP and SES v2 REST APIs are not implemented.
diff --git a/mkdocs.yml b/mkdocs.yml
index f9adc5e2a1..aacea05edd 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -70,6 +70,7 @@ nav:
- SSM Parameter Store: services/ssm.md
- SQS: services/sqs.md
- SNS: services/sns.md
+ - SES: services/ses.md
- S3: services/s3.md
- DynamoDB: services/dynamodb.md
- Lambda: services/lambda.md