The SES module uses AWS SDK for Java v2’s sesv2 client. It provisions local resources, submits simple and raw messages, and reads message insights. These operations use the selected emulator’s endpoint, credentials, and validated TLS connection.
Start With The Runnable Example
./gradlew -p examples/ses integrationTest --configuration-cache
./gradlew -p examples/ses integrationTest --configuration-cache
The example provisions an email identity, a stored template, a configuration set, and an SNS event destination backed by SQS. It sends simple and raw messages, checks SDK acceptance and metadata, and receives simulated send/bounce notifications. Repeated runs reuse the configuration cache and recreate the managed resources. Containers are removed after success or ordinary task failure.
Provision And Send
import io.github.gregwhitaker.awsemulator.aws.ses.*
plugins {
java
id("io.github.gregwhitaker.aws-emulator") version "0.3.0"
}
val sender = tasks.register<CreateSesEmailIdentityTask>("createMailSender") {
emailIdentity.set("sender@example.test")
}
val send = tasks.register<SendSesEmailTask>("sendWelcome") {
dependsOn(sender)
fromAddress.set("sender@example.test")
toAddresses.add("success@simulator.amazonses.com")
subject.set("Welcome")
textBody.set("Thanks for signing up.")
htmlBody.set("<p>Thanks for signing up.</p>")
}
val inspect = tasks.register<GetSesMessageInsightsTask>("inspectWelcome") {
dependsOn(send)
messageId.set(providers.fileContents(send.flatMap { it.messageIdFile }).asText.map { it.trim() })
outputFile.set(layout.buildDirectory.file("email/insights.json"))
}
val tests = tasks.named<Test>("test") { dependsOn(inspect) }
awsEmulator { useWith(tests) }
The sender, send, inspection, and tests share one managed runtime. SendSesEmailTask writes the accepted message ID, not the message body. GetSesMessageInsightsTask writes messageId, fromEmailAddress, subject, emailTags, and insights entries containing destination, isp, and event type/timestamp. Fields unavailable from SES can be null. It does not export event details or email bodies.
Groovy DSL uses the same properties:
import io.github.gregwhitaker.awsemulator.aws.ses.*
def sender = tasks.register('createMailSender', CreateSesEmailIdentityTask) {
emailIdentity.set('sender@example.test')
}
tasks.register('sendWelcome', SendSesEmailTask) {
dependsOn(sender)
fromAddress.set('sender@example.test')
toAddresses.add('success@simulator.amazonses.com')
subject.set('Welcome')
textBody.set('Thanks for signing up.')
}
Tasks And Properties
All classes below are in io.github.gregwhitaker.awsemulator.aws.ses.
| Task type | Properties and behavior |
|---|---|
|
|
|
Lists names and verification status across all result pages. |
|
|
|
|
|
|
|
|
|
Lists configuration-set names across all result pages. |
|
|
|
|
|
|
|
|
Template, configuration-set, and destination names accept 1–64 letters, digits, underscores, or hyphens. Send properties accept bare ASCII addresses, without display names. Output files are replaced atomically where supported, use owner-only permissions on POSIX filesystems, and must differ from raw-message input files. Bodies and template values are omitted from task logs and SDK error summaries.
Use lazy file providers for body/template fixtures:
tasks.register<PutSesEmailTemplateTask>("putWelcomeTemplate") {
templateName.set("welcome")
subject.set("Welcome {{name}}")
htmlBody.set(providers.fileContents(layout.projectDirectory.file("fixtures/welcome.html")).asText)
}
Lifetimes And Spring Boot
Custom tasks inherit awsEmulator.defaultMode, initially MANAGED. All live SES tasks execute each time and are excluded from up-to-date skipping and the build cache; configuration-cache reuse is supported. Send tasks submit a new message on each invocation. Their message IDs are valid only within the runtime that accepted them.
The module registers development convenience tasks listSesEmailIdentities, deleteSesEmailIdentity, deleteSesEmailTemplate, listSesConfigurationSets, deleteSesConfigurationSet, sendSesEmail, and getSesMessageInsights. Use --mode=MANAGED to override their mode. The delete tasks accept --emailIdentity, --templateName, or --configurationSetName, as appropriate. The send command accepts --fromAddress, comma-separated --toAddresses, --subject, --textBody, and --configurationSetName. Inspection accepts --messageId.
./gradlew -p examples/ses provisionSes -Pdevelopment=true
./gradlew -p examples/ses listSesEmailIdentities listSesConfigurationSets
./gradlew -p examples/ses sendSesEmail --fromAddress=sender@example.test --toAddresses=success@simulator.amazonses.com --subject=Hello --textBody=Welcome
./gradlew -p examples/ses stopAwsEmulator
Identity, template, configuration-set, and event-destination provisioning tasks carry @AwsEmulatorSetupTask, so Spring Boot local runs discover them automatically. Sending and inspection require explicit dependencies. Declare dependencies between setup tasks, including the event destination’s configuration set and SNS topic. You can also use these tasks in resource sets shared by tests and development scenarios.
Observe Sends Through SNS And SQS
Create a standard SNS topic and SQS subscription using CreateSnsTopicWithSqsEndpointTask, then register PutSesSnsEventDestinationTask with its topic ARN. The SNS topic must permit SES publication in workflows that enforce topic policies. Configure the application’s SES SendEmail requests with the same configurationSetName; the send task has the same property.
The runnable example verifies simulated Send and Bounce notifications for bounce@simulator.amazonses.com through SNS to SQS. These events include the message ID and common headers, and can exercise application bounce handling. A simulated Delivery event does not mean any external inbox received email. Message insights in the pinned emulator report acceptance (SEND); use the configured event destination to observe simulated bounce/delivery outcomes.
MailHog, Mailpit, And SMTP
AWS Emulator 1.0.385 records SES messages internally and does not relay them to an SMTP server. There is no SMTP_HOST or MailHog/Mailpit relay setting in this plugin. This is based on the pinned release’s SendEmail implementation and message state. Stored message bodies are not available through GetMessageInsights.
For a browser inbox showing HTML, MIME, and attachments, configure your application’s local SMTP mail sender to use MailHog or Mailpit, usually at localhost:1025. For example, an application using Spring Boot’s mail starter and JavaMailSender can select a local profile with:
spring.mail.host=localhost
spring.mail.port=1025
spring.mail.properties.mail.smtp.auth=false
spring.mail.properties.mail.smtp.starttls.enable=false
This configures an SMTP client only. It does not redirect an SES SDK client: the SES client speaks HTTPS, whereas MailHog/Mailpit expects SMTP. An application using the SES API needs a local SMTP implementation of its mail-sending abstraction, or a separate SES-to-SMTP adapter, to use those inboxes. This plugin does not implement that adapter or manage SMTP containers.
Pinned Emulator Coverage
The example and Docker tests verify AWS Emulator 1.0.385 with AWS SDK for Java v2 2.39.6. Supported workflows here include email-identity verification, template create/get/update/delete, configuration-set and SNS-destination setup, simple/raw sends, and message insights. Local email identities settle to verified without clicking an email verification link. Domain verification behavior depends on the emulator’s domain handling; a domain that never becomes verified causes the identity task to time out.
SES v2 ListEmailTemplates, TestRenderEmailTemplate, and SendEmail with template content return 501 NotImplemented in this release. No template-listing, rendering, or templated-send task is registered. Provisioning a template does not imply it can be rendered or sent by this emulator. The plugin does not advertise SMTP forwarding, inbound email receipt, or full SES parity. Check AWS Emulator fidelity when changing versions.