Skip to content

armgit / floci

Public Imported from GitHub
0

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

feat(ses): implement SendEmail ListManagementOptions suppression and unsubscribe (v2) (#1875)

Kenshin Okinakafa9ed9100e30
diff --git a/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/SesListManagementOptionsTest.java b/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/SesListManagementOptionsTest.java
new file mode 100644
index 0000000000..b2c2615f2e
--- /dev/null
+++ b/compatibility-tests/sdk-test-java/src/test/java/com/floci/test/SesListManagementOptionsTest.java
@@ -0,0 +1,119 @@
+package com.floci.test;
+
+import org.junit.jupiter.api.AfterAll;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+import software.amazon.awssdk.services.sesv2.SesV2Client;
+import software.amazon.awssdk.services.sesv2.model.Body;
+import software.amazon.awssdk.services.sesv2.model.Content;
+import software.amazon.awssdk.services.sesv2.model.CreateContactListRequest;
+import software.amazon.awssdk.services.sesv2.model.DeleteContactListRequest;
+import software.amazon.awssdk.services.sesv2.model.Destination;
+import software.amazon.awssdk.services.sesv2.model.EmailContent;
+import software.amazon.awssdk.services.sesv2.model.GetContactRequest;
+import software.amazon.awssdk.services.sesv2.model.GetContactResponse;
+import software.amazon.awssdk.services.sesv2.model.ListManagementOptions;
+import software.amazon.awssdk.services.sesv2.model.Message;
+import software.amazon.awssdk.services.sesv2.model.SendEmailRequest;
+import software.amazon.awssdk.services.sesv2.model.SendEmailResponse;
+import software.amazon.awssdk.services.sesv2.model.SubscriptionStatus;
+import software.amazon.awssdk.services.sesv2.model.Topic;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * SDK compatibility test for {@code SendEmail} with {@code ListManagementOptions} through the AWS
+ * Java SDK v2 {@link SesV2Client}. A real SDK round-trip proves the nested {@code ListManagementOptions}
+ * structure (ContactListName + optional TopicName) marshals as a real client sends it — and that Floci
+ * actually processes it, since an absent recipient is auto-created as a contact on the list (matches AWS).
+ */
+@DisplayName("SES v2 SendEmail ListManagementOptions")
+class SesListManagementOptionsTest {
+
+ private static final String LIST = "compat-lmo-list";
+ private static final String TOPIC = "weekly";
+ private static final String FROM = "[email protected]";
+
+ private static SesV2Client sesV2;
+
+ @BeforeAll
+ static void setup() {
+ sesV2 = TestFixtures.sesV2Client();
+ // Only one contact list may exist per account; clear any leftover, then create ours.
+ sesV2.listContactLists(r -> { }).contactLists().forEach(cl ->
+ sesV2.deleteContactList(DeleteContactListRequest.builder()
+ .contactListName(cl.contactListName()).build()));
+ sesV2.createContactList(CreateContactListRequest.builder()
+ .contactListName(LIST)
+ .topics(Topic.builder()
+ .topicName(TOPIC)
+ .displayName("Weekly")
+ .defaultSubscriptionStatus(SubscriptionStatus.OPT_IN)
+ .description("weekly digest")
+ .build())
+ .build());
+ }
+
+ @AfterAll
+ static void cleanup() {
+ if (sesV2 != null) {
+ try {
+ sesV2.deleteContactList(DeleteContactListRequest.builder().contactListName(LIST).build());
+ } catch (RuntimeException ignored) {
+ // best-effort
+ }
+ sesV2.close();
+ }
+ }
+
+ @Test
+ void sendWithListManagementOptions_roundTripsAndAutoCreatesContact() {
+ String recipient = "lmo-compat-" + TestFixtures.uniqueName() + "@example.com";
+
+ SendEmailResponse response = sesV2.sendEmail(SendEmailRequest.builder()
+ .fromEmailAddress(FROM)
+ .destination(Destination.builder().toAddresses(recipient).build())
+ .content(EmailContent.builder()
+ .simple(Message.builder()
+ .subject(Content.builder().data("compat-lmo").build())
+ .body(Body.builder().text(Content.builder().data("hi").build()).build())
+ .build())
+ .build())
+ .listManagementOptions(ListManagementOptions.builder()
+ .contactListName(LIST)
+ .topicName(TOPIC)
+ .build())
+ .build());
+
+ assertThat(response.messageId()).isNotBlank();
+
+ // The nested ListManagementOptions was actually applied: an absent recipient is auto-created
+ // as a contact on the named list.
+ GetContactResponse contact = sesV2.getContact(GetContactRequest.builder()
+ .contactListName(LIST).emailAddress(recipient).build());
+ assertThat(contact.emailAddress()).isEqualTo(recipient);
+ }
+
+ @Test
+ void sendWithListManagementOptions_topicNameOptional() {
+ String recipient = "lmo-compat-notopic-" + TestFixtures.uniqueName() + "@example.com";
+
+ SendEmailResponse response = sesV2.sendEmail(SendEmailRequest.builder()
+ .fromEmailAddress(FROM)
+ .destination(Destination.builder().toAddresses(recipient).build())
+ .content(EmailContent.builder()
+ .simple(Message.builder()
+ .subject(Content.builder().data("compat-lmo-notopic").build())
+ .body(Body.builder().text(Content.builder().data("hi").build()).build())
+ .build())
+ .build())
+ .listManagementOptions(ListManagementOptions.builder()
+ .contactListName(LIST)
+ .build())
+ .build());
+
+ assertThat(response.messageId()).isNotBlank();
+ }
+}
diff --git a/docs/services/ses.md b/docs/services/ses.md
index a50cc5f8c6..b3695b0282 100644
--- a/docs/services/ses.md
+++ b/docs/services/ses.md
@@ -260,6 +260,10 @@ Suppression list entries are stored per region with `Reason` ∈ {`BOUNCE`, `COM
Suppressed recipients are filtered out of the SMTP relay step (non-suppressed recipients on the same send still reach the relay normally), and the configuration set's event destinations receive a synthetic `Bounce` or `Complaint` event alongside the always-emitted `Send` event. The `SendEmail` API response (`200` + `MessageId`), the stored `SentEmail` visible at `GET /_aws/ses`, and the published event's `mail.destination` all retain the original recipient list — matching the AWS contract that the message is "accepted, just not sent" for suppressed addresses.
+`SendEmail` honors `ListManagementOptions` (`ContactListName`, optional `TopicName`). When present, each recipient is matched against the named contact list and suppressed as a `Bounce` when opted out — reusing the same relay-exclusion and Bounce-event path as suppression-list filtering, matching AWS ("SES will issue a bounce event for a message that is sent to an unsubscribed contact"). A contact is opted out when `UnsubscribeAll` is set; with a `TopicName`, an explicit `OPT_OUT` preference for that topic (or, absent an explicit preference, the topic's `DefaultSubscriptionStatus` being `OPT_OUT`) suppresses; without a `TopicName`, only `UnsubscribeAll` contacts are suppressed. A recipient that is not yet a contact is created on the list automatically (as on AWS) and then evaluated. Referencing a contact list that does not exist fails the send with `NotFoundException`. The topic-default fallback at send time is an intentional deviation — it is not documented by AWS and mirrors the effective-status model AWS uses for `ListContacts`.
+
+For a **single-recipient** list-managed send, Floci injects a functional unsubscribe link (matching AWS, which only does this for one recipient): the `{{amazonSESUnsubscribeUrl}}` body placeholder is replaced (up to twice) and a `List-Unsubscribe` header plus `List-Unsubscribe-Post: List-Unsubscribe=One-Click` are added (applied to the relayed message and shown under `Headers` at `GET /_aws/ses`; a caller-supplied `List-Unsubscribe` is overridden, matching AWS). The `{{amazonSESUnsubscribeUrl}}` placeholder is also preserved through template rendering so a templated body can carry it. On a send without `ListManagementOptions`, the placeholder is left in the body verbatim (neither replaced nor stripped) — this specific behavior is Floci's choice and is not verified against real SES. Unlike AWS's opaque hosted URL, the link points at Floci's own `/_aws/ses/unsubscribe?region=…&contactList=…&address=…&topic=…` endpoint. `GET` (a browser click) only renders a confirmation page and changes nothing — matching AWS's landing-page behavior and avoiding the RFC 8058 hazard where a client or bot that prefetches the link would silently unsubscribe the contact — while `POST` (the one-click request the confirmation form submits) applies the opt-out (a topic → `OPT_OUT` for that topic; no topic → `UnsubscribeAll`), auto-creating the contact if needed. Two deviations from AWS here: the link is carried as readable query parameters rather than an opaque token (so, like the rest of Floci, the endpoint is unauthenticated and only safe on a trusted dev/test network — a `POST` can opt out any contact), and only the one-click URL entry is emitted — its scheme follows Floci's base URL (`http` unless TLS is enabled) — whereas AWS also includes a `mailto:` entry, which Floci can't service since it has no inbound mail endpoint. Raw (MIME) sends do not get link injection yet.
+
Tag operations support these ARN forms: `arn:aws:ses:<region>:<account>:configuration-set/<name>`, `arn:aws:ses:<region>:<account>:template/<name>`, and `arn:aws:ses:<region>:<account>:identity/<email-or-domain>`. Tags supplied to `CreateConfigurationSet`, `CreateEmailTemplate`, and `CreateEmailIdentity` are reachable through `ListTagsForResource`; `UpdateEmailTemplate` does not modify tags. Other resource types return `NotFoundException`.
Identity, identity-policy, template, configuration-set, and sent-message state is shared between the v1 Query API and the v2 REST JSON API, so a template created with `CreateTemplate` resolves through `SendEmail` on v2 (and vice versa), a policy written with `PutIdentityPolicy` (v1) is returned by `GetEmailIdentityPolicies` (v2), a configuration set created with `CreateConfigurationSet` is visible to both `DescribeConfigurationSet` (v1) and `GetConfigurationSet` (v2), and every send appears in the same `GET /_aws/ses` inspection mailbox.
diff --git a/src/main/java/io/github/hectorvent/floci/services/cognito/verification/CognitoMessageDispatcher.java b/src/main/java/io/github/hectorvent/floci/services/cognito/verification/CognitoMessageDispatcher.java
index 774c7897dd..fd65408fb3 100644
--- a/src/main/java/io/github/hectorvent/floci/services/cognito/verification/CognitoMessageDispatcher.java
+++ b/src/main/java/io/github/hectorvent/floci/services/cognito/verification/CognitoMessageDispatcher.java
@@ -57,6 +57,7 @@ public final class CognitoMessageDispatcher {
null, // configurationSetName
List.of(), // emailTags
List.of(), // additionalHeaders
+ null, // listManagement
DEFAULT_REGION
);
} else if ("SMS".equalsIgnoreCase(medium) && phone != null) {
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/SesController.java b/src/main/java/io/github/hectorvent/floci/services/ses/SesController.java
index 9bedca0a62..46ecf7c356 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ses/SesController.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/SesController.java
@@ -18,6 +18,7 @@ import io.github.hectorvent.floci.services.ses.model.DeliveryOptions;
import io.github.hectorvent.floci.services.ses.model.EmailTemplate;
import io.github.hectorvent.floci.services.ses.model.EventDestination;
import io.github.hectorvent.floci.services.ses.model.Identity;
+import io.github.hectorvent.floci.services.ses.model.ListManagementOptions;
import io.github.hectorvent.floci.services.ses.model.MessageHeader;
import io.github.hectorvent.floci.services.ses.model.MessageTag;
import io.github.hectorvent.floci.services.ses.model.SuppressedDestination;
@@ -416,6 +417,8 @@ public class SesController {
List<String> allDestinations = mergeLists(toAddresses, ccAddresses, bccAddresses);
String configurationSetName = request.path("ConfigurationSetName").asText(null);
List<MessageTag> emailTags = parseEmailTagsArray(request.path("EmailTags"), "EmailTags");
+ ListManagementOptions listManagement =
+ parseListManagementOptions(request.path("ListManagementOptions"));
JsonNode content = request.path("Content");
String messageId;
@@ -431,7 +434,7 @@ public class SesController {
"At least one destination address is required.", 400);
}
messageId = sesService.sendRawEmail(fromEmailAddress, allDestinations, rawData,
- configurationSetName, emailTags, region);
+ configurationSetName, emailTags, listManagement, region);
} else if (content.has("Simple")) {
if (fromEmailAddress == null || fromEmailAddress.isBlank()) {
// AWS returns BadRequestException with a null message body here.
@@ -441,10 +444,11 @@ public class SesController {
String subject = simple.path("Subject").path("Data").asText("");
String bodyText = simple.path("Body").path("Text").path("Data").asText(null);
String bodyHtml = simple.path("Body").path("Html").path("Data").asText(null);
- List<MessageHeader> additionalHeaders = parseHeadersArray(simple.path("Headers"));
+ List<MessageHeader> additionalHeaders =
+ parseHeadersArray(simple.path("Headers"), "content.simple.headers");
messageId = sesService.sendEmail(fromEmailAddress, toAddresses, ccAddresses,
bccAddresses, replyToAddresses, subject, bodyText, bodyHtml,
- configurationSetName, emailTags, additionalHeaders, region);
+ configurationSetName, emailTags, additionalHeaders, listManagement, region);
} else if (content.has("Template")) {
if (fromEmailAddress == null || fromEmailAddress.isBlank()) {
throw new AwsException("BadRequestException", "Source cannot be empty", 400);
@@ -466,14 +470,15 @@ public class SesController {
"Content.Template requires TemplateName, TemplateArn, or TemplateContent.", 400);
}
JsonNode templateData = parseTemplateData(template, "TemplateData");
- List<MessageHeader> additionalHeaders = parseHeadersArray(template.path("Headers"));
+ List<MessageHeader> additionalHeaders =
+ parseHeadersArray(template.path("Headers"), "content.template.headers");
if (hasName || hasArn) {
String resolvedName = hasName
? templateName
: SesService.templateNameFromArn(templateArn);
messageId = sesService.sendTemplatedEmail(fromEmailAddress, toAddresses, ccAddresses,
bccAddresses, replyToAddresses, resolvedName, templateData,
- configurationSetName, emailTags, additionalHeaders, region);
+ configurationSetName, emailTags, additionalHeaders, listManagement, region);
} else {
JsonNode inline = template.path("TemplateContent");
String subject = inline.path("Subject").asText(null);
@@ -482,7 +487,7 @@ public class SesController {
messageId = sesService.sendInlineTemplatedEmail(fromEmailAddress, toAddresses,
ccAddresses, bccAddresses, replyToAddresses,
subject, text, html, templateData,
- configurationSetName, emailTags, additionalHeaders, region);
+ configurationSetName, emailTags, additionalHeaders, listManagement, region);
}
} else {
throw new AwsException("BadRequestException",
@@ -563,7 +568,8 @@ public class SesController {
JsonNode defaultTemplateData = parseTemplateData(template, "TemplateData");
List<MessageTag> defaultEmailTags = parseEmailTagsArray(request.path("DefaultEmailTags"), "DefaultEmailTags");
- List<MessageHeader> defaultHeaders = parseHeadersArray(template.path("Headers"));
+ List<MessageHeader> defaultHeaders =
+ parseHeadersArray(template.path("Headers"), "defaultContent.template.headers");
JsonNode bulkEntries = request.path("BulkEmailEntries");
if (!bulkEntries.isArray() || bulkEntries.isEmpty()) {
@@ -572,6 +578,7 @@ public class SesController {
}
List<BulkEmailEntry> entries = new ArrayList<>();
+ int entryIndex = 1;
for (JsonNode node : bulkEntries) {
if (!node.isObject()) {
throw new AwsException("BadRequestException",
@@ -585,8 +592,10 @@ public class SesController {
JsonNode replacementTemplate = requireObjectOrAbsent(replacementContent, "ReplacementTemplate");
JsonNode replacementData = parseTemplateData(replacementTemplate, "ReplacementTemplateData");
List<MessageTag> replacementTags = parseEmailTagsArray(node.path("ReplacementTags"), "ReplacementTags");
- List<MessageHeader> entryReplacementHeaders = parseHeadersArray(node.path("ReplacementHeaders"));
+ List<MessageHeader> entryReplacementHeaders = parseHeadersArray(node.path("ReplacementHeaders"),
+ "bulkEmailEntries." + entryIndex + ".replacementHeaders");
entries.add(new BulkEmailEntry(to, cc, bcc, replacementData, replacementTags, entryReplacementHeaders));
+ entryIndex++;
}
List<BulkEmailEntryResult> results = sesService.sendBulkTemplatedEmail(fromEmailAddress,
@@ -2134,9 +2143,12 @@ public class SesController {
/**
* Parse a V2 SES {@code Content.Simple.Headers} / {@code Content.Template.Headers} array
* (additional message headers, elements use {@code Name}/{@code Value}). Returns an empty
- * list when the node is absent so callers can pass it through unconditionally.
+ * list when the node is absent so callers can pass it through unconditionally. Both members
+ * are required: an entry that omits {@code Name} or {@code Value} is rejected the way AWS
+ * does, with a Smithy constraint message anchored at {@code location} (e.g.
+ * {@code content.simple.headers}) and the offending 1-based index.
*/
- private List<MessageHeader> parseHeadersArray(JsonNode headersNode) {
+ private List<MessageHeader> parseHeadersArray(JsonNode headersNode, String location) {
if (headersNode.isMissingNode() || headersNode.isNull()) {
return List.of();
}
@@ -2144,22 +2156,37 @@ public class SesController {
throw new AwsException("BadRequestException", "Headers must be an array.", 400);
}
List<MessageHeader> out = new ArrayList<>();
+ int index = 1;
for (JsonNode h : headersNode) {
if (!h.isObject()) {
throw new AwsException("BadRequestException",
"Headers entries must be JSON objects.", 400);
}
- String name = h.path("Name").asText(null);
- String value = h.path("Value").asText(null);
- if (name == null || name.isBlank()) {
+ JsonNode nameNode = h.get("Name");
+ JsonNode valueNode = h.get("Value");
+ if (nameNode == null || nameNode.isNull()) {
+ throw missingHeaderMember(location, index, "name");
+ }
+ if (valueNode == null || valueNode.isNull()) {
+ throw missingHeaderMember(location, index, "value");
+ }
+ String name = nameNode.asText();
+ if (name.isBlank()) {
throw new AwsException("BadRequestException",
"The header name must be specified.", 400);
}
- out.add(new MessageHeader(name, value));
+ out.add(new MessageHeader(name, valueNode.asText()));
+ index++;
}
return out;
}
+ private AwsException missingHeaderMember(String location, int index, String member) {
+ return new AwsException("BadRequestException",
+ "1 validation error detected: Value at '" + location + "." + index + ".member." + member
+ + "' failed to satisfy constraint: Member must not be null", 400);
+ }
+
/**
* Parse a V2 SES {@code EmailTags} / {@code DefaultEmailTags} / {@code ReplacementTags}
* array (per-message {@link MessageTag} list whose elements use {@code Name}/{@code Value},
@@ -2170,6 +2197,30 @@ public class SesController {
* The {@code fieldName} parameter is reported in the error message when the node is
* present but not an array.
*/
+ private static ListManagementOptions parseListManagementOptions(JsonNode node) {
+ if (node == null || node.isMissingNode() || node.isNull()) {
+ return null;
+ }
+ if (!node.isObject()) {
+ throw new AwsException("BadRequestException", "ListManagementOptions must be an object.", 400);
+ }
+ JsonNode listNode = node.path("ContactListName");
+ if (!listNode.isTextual() || listNode.textValue().isBlank()) {
+ throw new AwsException("BadRequestException",
+ "ListManagementOptions.ContactListName is required.", 400);
+ }
+ JsonNode topicNode = node.path("TopicName");
+ String topicName = null;
+ if (!topicNode.isMissingNode() && !topicNode.isNull()) {
+ if (!topicNode.isTextual()) {
+ throw new AwsException("BadRequestException",
+ "ListManagementOptions.TopicName must be a string.", 400);
+ }
+ topicName = topicNode.textValue();
+ }
+ return new ListManagementOptions(listNode.textValue(), topicName);
+ }
+
private List<MessageTag> parseEmailTagsArray(JsonNode tagsNode, String fieldName) {
if (tagsNode.isMissingNode() || tagsNode.isNull()) {
return List.of();
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/SesInspectionController.java b/src/main/java/io/github/hectorvent/floci/services/ses/SesInspectionController.java
index 475813d4d6..a30f4a37e3 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ses/SesInspectionController.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/SesInspectionController.java
@@ -94,6 +94,15 @@ public class SesInspectionController {
}
}
+ if (email.getHeaders() != null && !email.getHeaders().isEmpty()) {
+ ArrayNode headers = node.putArray("Headers");
+ email.getHeaders().forEach(h -> {
+ ObjectNode ho = headers.addObject();
+ ho.put("Name", h.name());
+ ho.put("Value", h.value());
+ });
+ }
+
if (email.getSentAt() != null) {
node.put("Timestamp", email.getSentAt().toString());
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/SesQueryHandler.java b/src/main/java/io/github/hectorvent/floci/services/ses/SesQueryHandler.java
index fb46ee36d2..3b665f38b6 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ses/SesQueryHandler.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/SesQueryHandler.java
@@ -199,9 +199,10 @@ public class SesQueryHandler {
String configurationSetName = getParam(params, "ConfigurationSetName");
List<MessageTag> emailTags = extractMessageTags(params, "Tags");
+ // ListManagementOptions is a v2-only SendEmail field; the v1 Query API has no equivalent.
String messageId = sesService.sendEmail(source, toAddresses, ccAddresses, bccAddresses,
replyToAddresses, subject, bodyText, bodyHtml, configurationSetName,
- emailTags, List.of(), region);
+ emailTags, List.of(), null, region);
String result = new XmlBuilder().elem("MessageId", messageId).build();
return Response.ok(AwsQueryResponse.envelope("SendEmail", AwsNamespaces.SES, result)).build();
@@ -219,7 +220,7 @@ public class SesQueryHandler {
List<MessageTag> emailTags = extractMessageTags(params, "Tags");
String messageId = sesService.sendRawEmail(source, destinations, rawMessage,
- configurationSetName, emailTags, region);
+ configurationSetName, emailTags, null, region);
String result = new XmlBuilder().elem("MessageId", messageId).build();
return Response.ok(AwsQueryResponse.envelope("SendRawEmail", AwsNamespaces.SES, result)).build();
@@ -528,7 +529,7 @@ public class SesQueryHandler {
List<MessageTag> emailTags = extractMessageTags(params, "Tags");
String messageId = sesService.sendTemplatedEmail(source, toAddresses, ccAddresses,
bccAddresses, replyToAddresses, resolvedName, templateData,
- configurationSetName, emailTags, List.of(), region);
+ configurationSetName, emailTags, List.of(), null, region);
String result = new XmlBuilder().elem("MessageId", messageId).build();
return Response.ok(AwsQueryResponse.envelope("SendTemplatedEmail", AwsNamespaces.SES, result)).build();
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/SesService.java b/src/main/java/io/github/hectorvent/floci/services/ses/SesService.java
index ca547fcf8a..a5378e333e 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ses/SesService.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/SesService.java
@@ -22,6 +22,7 @@ import io.github.hectorvent.floci.services.ses.model.DeliveryOptions;
import io.github.hectorvent.floci.services.ses.model.EmailTemplate;
import io.github.hectorvent.floci.services.ses.model.EventDestination;
import io.github.hectorvent.floci.services.ses.model.Identity;
+import io.github.hectorvent.floci.services.ses.model.ListManagementOptions;
import io.github.hectorvent.floci.services.ses.model.MessageHeader;
import io.github.hectorvent.floci.services.ses.model.MessageTag;
import io.github.hectorvent.floci.services.ses.model.ReceiptRuleSet;
@@ -41,6 +42,8 @@ import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;
import org.jboss.logging.Logger;
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
import java.security.SecureRandom;
import java.time.Clock;
import java.time.Duration;
@@ -107,6 +110,9 @@ public class SesService {
private final ObjectMapper objectMapper;
private final SesEventPublisher eventPublisher;
private final String defaultAccountId;
+ // Base URL used to build functional list-management unsubscribe links (the {{amazonSESUnsubscribeUrl}}
+ // placeholder and the List-Unsubscribe header) that resolve to Floci's own unsubscribe endpoint.
+ private final String baseUrl;
private final Route53Service route53Service;
private final Clock clock;
private final ConcurrentHashMap<String, DkimLookupCacheEntry> dkimLookupCache = new ConcurrentHashMap<>();
@@ -143,6 +149,7 @@ public class SesService {
this.objectMapper = objectMapper;
this.eventPublisher = eventPublisher;
this.defaultAccountId = config.defaultAccountId();
+ this.baseUrl = config.effectiveBaseUrl();
this.route53Service = route53Service;
this.clock = clock;
}
@@ -199,6 +206,7 @@ public class SesService {
this.objectMapper = objectMapper;
this.eventPublisher = null;
this.defaultAccountId = "000000000000";
+ this.baseUrl = "http://localhost:4566";
this.route53Service = route53Service;
this.clock = clock;
}
@@ -291,7 +299,8 @@ public class SesService {
List<String> bccAddresses, List<String> replyToAddresses,
String subject, String bodyText, String bodyHtml,
String configurationSetName, List<MessageTag> emailTags,
- List<MessageHeader> additionalHeaders, String region) {
+ List<MessageHeader> additionalHeaders, ListManagementOptions listManagement,
+ String region) {
if (source == null || source.isBlank()) {
throw new AwsException("InvalidParameterValue", "Source email is required.", 400);
}
@@ -304,20 +313,47 @@ public class SesService {
String effectiveConfigSet = resolveDefaultConfigurationSet(configurationSetName, source, region);
validateConfigurationSet(effectiveConfigSet, region);
+ // Resolve suppression before recording the message so a bad ListManagementOptions (e.g. an
+ // unknown contact list) fails the whole send without leaving an orphaned SentEmail record.
+ List<String> envelope = allRecipients(toAddresses, ccAddresses, bccAddresses);
+ Map<String, String> suppressedReasons = new LinkedHashMap<>(
+ collectSuppressedReasons(envelope, effectiveConfigSet, region));
+ // putIfAbsent so a suppression-list reason already set for an address (e.g. COMPLAINT) wins
+ // over the list-management BOUNCE and keeps its synthetic event type.
+ collectListManagementOptOuts(envelope, listManagement, region).forEach(suppressedReasons::putIfAbsent);
+
+ // A single-recipient list-managed send gets a functional unsubscribe link: the
+ // {{amazonSESUnsubscribeUrl}} body placeholder is replaced and the List-Unsubscribe headers
+ // are added, matching AWS (which only injects these for a single recipient). The link
+ // resolves to Floci's own /_aws/ses/unsubscribe endpoint.
+ if (hasListManagement(listManagement) && envelope.size() == 1) {
+ String url = buildUnsubscribeUrl(region, listManagement, extractEmailAddress(envelope.get(0)));
+ bodyText = replaceUnsubscribePlaceholder(bodyText, url);
+ bodyHtml = replaceUnsubscribePlaceholder(bodyHtml, url);
+ additionalHeaders = withUnsubscribeHeaders(additionalHeaders, url);
+ }
+
+ // Drop unsafe user-supplied headers (blank name or CR/LF in name/value) once here, so the
+ // stored SentEmail, the SMTP relay, and the published events all reflect the same sanitized
+ // set and no injection payload is retained on any surface.
+ if (additionalHeaders != null) {
+ additionalHeaders = additionalHeaders.stream().filter(MessageHeader::isSafe).toList();
+ }
+
String messageId = UUID.randomUUID().toString();
SentEmail email = new SentEmail(messageId, region, source, toAddresses, ccAddresses,
bccAddresses, replyToAddresses, subject, bodyText, bodyHtml);
+ if (additionalHeaders != null && !additionalHeaders.isEmpty()) {
+ email.setHeaders(additionalHeaders);
+ }
emailStore.put("email::" + region + "::" + messageId, email);
- List<String> envelope = allRecipients(toAddresses, ccAddresses, bccAddresses);
- Map<String, String> suppressedReasons = collectSuppressedReasons(envelope, effectiveConfigSet, region);
-
List<String> relayedTo = filterUnsuppressed(toAddresses, suppressedReasons);
List<String> relayedCc = filterUnsuppressed(ccAddresses, suppressedReasons);
List<String> relayedBcc = filterUnsuppressed(bccAddresses, suppressedReasons);
if (sizeOf(relayedTo) + sizeOf(relayedCc) + sizeOf(relayedBcc) > 0) {
smtpRelay.relay(source, relayedTo, relayedCc, relayedBcc,
- replyToAddresses, subject, bodyText, bodyHtml);
+ replyToAddresses, subject, bodyText, bodyHtml, additionalHeaders);
} else {
LOG.infov("SES email accepted but not relayed (all recipients suppressed): messageId={0}",
messageId);
@@ -333,7 +369,7 @@ public class SesService {
public String sendRawEmail(String source, List<String> destinations, String rawMessage,
String configurationSetName, List<MessageTag> emailTags,
- String region) {
+ ListManagementOptions listManagement, String region) {
if (rawMessage == null || rawMessage.isBlank()) {
throw new AwsException("InvalidParameterValue", "RawMessage.Data is required.", 400);
}
@@ -371,12 +407,19 @@ public class SesService {
throw new AwsException("InvalidParameterValue",
"At least one destination address is required.", 400);
}
+ // Resolve suppression before recording the message so a bad ListManagementOptions (e.g. an
+ // unknown contact list) fails the whole send without leaving an orphaned SentEmail record.
+ Map<String, String> suppressedReasons = new LinkedHashMap<>(
+ collectSuppressedReasons(effectiveDestinations, effectiveConfigSet, region));
+ // putIfAbsent so a suppression-list reason already set for an address (e.g. COMPLAINT) wins
+ // over the list-management BOUNCE and keeps its synthetic event type.
+ collectListManagementOptOuts(effectiveDestinations, listManagement, region)
+ .forEach(suppressedReasons::putIfAbsent);
+
String messageId = UUID.randomUUID().toString();
SentEmail email = new SentEmail(messageId, region, effectiveSource, effectiveDestinations, rawMessage);
emailStore.put("email::" + region + "::" + messageId, email);
- Map<String, String> suppressedReasons = collectSuppressedReasons(effectiveDestinations, effectiveConfigSet, region);
-
List<String> relayedDestinations = filterUnsuppressed(effectiveDestinations, suppressedReasons);
if (!relayedDestinations.isEmpty()) {
smtpRelay.relayRaw(effectiveSource, relayedDestinations, rawMessage);
@@ -2629,6 +2672,247 @@ public class SesService {
return result;
}
+ /**
+ * Resolves the recipients suppressed by SES V2 {@code SendEmail} {@code ListManagementOptions}:
+ * for each envelope recipient that is opted out of the named contact list (or the given topic),
+ * returns a {@code BOUNCE} suppression reason so the shared send path drops the recipient from
+ * the relay and publishes a Bounce event — matching AWS ("SES will issue a bounce event for a
+ * message that is sent to an unsubscribed contact"). Returns an empty map when no
+ * {@code ListManagementOptions} was supplied. Throws when the contact list does not exist, so a
+ * bad reference fails the whole send. A recipient that is not yet a contact is created
+ * automatically (matching AWS), then evaluated like any other contact.
+ */
+ private Map<String, String> collectListManagementOptOuts(Collection<String> addresses,
+ ListManagementOptions listManagement, String region) {
+ if (listManagement == null || listManagement.contactListName() == null
+ || listManagement.contactListName().isBlank() || addresses == null || addresses.isEmpty()) {
+ return Map.of();
+ }
+ ContactList list = getContactList(listManagement.contactListName(), region);
+ String topicName = listManagement.topicName();
+ String effectiveTopic = (topicName == null || topicName.isBlank()) ? null : topicName;
+ // Fail fast on a topic that isn't defined on the list rather than silently skipping
+ // suppression (a typo would otherwise send to everyone). AWS does not document this, so the
+ // exact error is best-effort.
+ if (effectiveTopic != null && defaultTopicStatus(list, effectiveTopic) == null) {
+ throw new AwsException("BadRequestException",
+ "Topic " + effectiveTopic + " does not exist in contact list "
+ + list.getContactListName() + ".", 400);
+ }
+ Map<String, String> optOuts = new LinkedHashMap<>();
+ for (String address : addresses) {
+ if (address == null || address.isBlank() || optOuts.containsKey(address)) {
+ continue;
+ }
+ String email = extractEmailAddress(address);
+ if (email == null || email.isBlank()) {
+ continue;
+ }
+ Contact contact = getOrAutoCreateContact(list, email, region);
+ if (isListManagementOptedOut(contact, list, effectiveTopic)) {
+ optOuts.put(address, "BOUNCE");
+ }
+ }
+ return optOuts;
+ }
+
+ /**
+ * Returns the contact for {@code email} in {@code list}, creating it automatically when absent —
+ * AWS creates a contact on the list when {@code ListManagementOptions} names a recipient that is
+ * not yet a contact. The auto-created contact has no explicit topic preferences (its effective
+ * per-topic status derives from the list topic defaults) and is not unsubscribed. Creation runs
+ * under {@code contactMutationLock} so a concurrent contact-list deletion can't orphan it.
+ */
+ private Contact getOrAutoCreateContact(ContactList list, String email, String region) {
+ String key = contactKey(region, list.getContactListName(), email);
+ Contact existing = contactStore.get(key).orElse(null);
+ if (existing != null) {
+ return existing;
+ }
+ synchronized (contactMutationLock) {
+ Contact raced = contactStore.get(key).orElse(null);
+ if (raced != null) {
+ return raced;
+ }
+ // Re-check the list under the lock so a concurrent deleteContactList (which purges the
+ // list and its contacts under the same lock) can't be followed by this creating an
+ // orphaned contact for a list that no longer exists.
+ getContactList(list.getContactListName(), region);
+ Contact contact = new Contact(email);
+ Instant now = Instant.now(clock);
+ contact.setCreatedTimestamp(now);
+ contact.setLastUpdatedTimestamp(now);
+ contactStore.put(key, contact);
+ LOG.infov("Auto-created SES contact {0} in list {1} on send (region {2})",
+ email, list.getContactListName(), region);
+ return contact;
+ }
+ }
+
+ /**
+ * Whether a contact is opted out for a list-managed send. A contact with {@code UnsubscribeAll}
+ * is opted out of everything. When no topic is given, only {@code UnsubscribeAll} suppresses
+ * (AWS documents suppression of whole-list unsubscribers). When a topic is given, an explicit
+ * {@code OPT_OUT} preference for that topic suppresses; absent an explicit preference, the topic's
+ * {@code DefaultSubscriptionStatus} is used — the default-status fallback at send time is not
+ * documented by AWS but mirrors the effective-status model AWS uses for {@code ListContacts}.
+ */
+ private static boolean isListManagementOptedOut(Contact contact, ContactList list, String topicName) {
+ if (contact.isUnsubscribeAll()) {
+ return true;
+ }
+ if (topicName == null) {
+ return false;
+ }
+ String explicit = explicitTopicStatus(contact, topicName);
+ if (explicit != null) {
+ return "OPT_OUT".equals(explicit);
+ }
+ return "OPT_OUT".equals(defaultTopicStatus(list, topicName));
+ }
+
+ private static String explicitTopicStatus(Contact contact, String topicName) {
+ if (contact.getTopicPreferences() == null) {
+ return null;
+ }
+ for (TopicPreference pref : contact.getTopicPreferences()) {
+ if (topicName.equals(pref.getTopicName())) {
+ return pref.getSubscriptionStatus();
+ }
+ }
+ return null;
+ }
+
+ private static String defaultTopicStatus(ContactList list, String topicName) {
+ if (list.getTopics() == null) {
+ return null;
+ }
+ for (Topic topic : list.getTopics()) {
+ if (topicName.equals(topic.getTopicName())) {
+ return topic.getDefaultSubscriptionStatus();
+ }
+ }
+ return null;
+ }
+
+ private static final String UNSUBSCRIBE_PLACEHOLDER = "{{amazonSESUnsubscribeUrl}}";
+
+ private static boolean hasListManagement(ListManagementOptions listManagement) {
+ return listManagement != null && listManagement.contactListName() != null
+ && !listManagement.contactListName().isBlank();
+ }
+
+ /**
+ * Builds the functional one-click unsubscribe URL served by Floci's {@code /_aws/ses/unsubscribe}
+ * endpoint. Unlike AWS's opaque hosted URL, the list, topic, and address are carried as readable
+ * query parameters so the link is directly usable and testable against the local emulator.
+ */
+ private String buildUnsubscribeUrl(String region, ListManagementOptions listManagement, String address) {
+ String base = baseUrl.endsWith("/") ? baseUrl.substring(0, baseUrl.length() - 1) : baseUrl;
+ StringBuilder sb = new StringBuilder(base)
+ .append("/_aws/ses/unsubscribe?region=").append(urlEncode(region))
+ .append("&contactList=").append(urlEncode(listManagement.contactListName()))
+ .append("&address=").append(urlEncode(address));
+ if (listManagement.topicName() != null && !listManagement.topicName().isBlank()) {
+ sb.append("&topic=").append(urlEncode(listManagement.topicName()));
+ }
+ return sb.toString();
+ }
+
+ private static String urlEncode(String value) {
+ return URLEncoder.encode(value, StandardCharsets.UTF_8);
+ }
+
+ /** Replaces up to the first two {@code {{amazonSESUnsubscribeUrl}}} occurrences, as AWS does. */
+ private static String replaceUnsubscribePlaceholder(String body, String url) {
+ if (body == null || !body.contains(UNSUBSCRIBE_PLACEHOLDER)) {
+ return body;
+ }
+ StringBuilder out = new StringBuilder();
+ int from = 0;
+ int replaced = 0;
+ while (replaced < 2) {
+ int at = body.indexOf(UNSUBSCRIBE_PLACEHOLDER, from);
+ if (at < 0) {
+ break;
+ }
+ out.append(body, from, at).append(url);
+ from = at + UNSUBSCRIBE_PLACEHOLDER.length();
+ replaced++;
+ }
+ out.append(body.substring(from));
+ return out.toString();
+ }
+
+ private static List<MessageHeader> withUnsubscribeHeaders(List<MessageHeader> headers, String url) {
+ List<MessageHeader> out = new ArrayList<>();
+ // Override any caller-supplied unsubscribe headers rather than appending a duplicate, matching
+ // AWS ("SES will override these headers if they are present in the email").
+ if (headers != null) {
+ for (MessageHeader h : headers) {
+ if (!"List-Unsubscribe".equalsIgnoreCase(h.name())
+ && !"List-Unsubscribe-Post".equalsIgnoreCase(h.name())) {
+ out.add(h);
+ }
+ }
+ }
+ out.add(new MessageHeader("List-Unsubscribe", "<" + url + ">"));
+ out.add(new MessageHeader("List-Unsubscribe-Post", "List-Unsubscribe=One-Click"));
+ return out;
+ }
+
+ /**
+ * Applies a list-management unsubscribe (the action behind the {@code /_aws/ses/unsubscribe}
+ * link): with a topic, sets that topic's preference to {@code OPT_OUT}; without a topic,
+ * unsubscribes the contact from the whole list ({@code UnsubscribeAll}). The contact is created
+ * if it does not exist yet, consistent with send-time auto-creation. Runs under
+ * {@code contactMutationLock} so a concurrent contact-list deletion can't orphan it.
+ */
+ public void unsubscribeContact(String listName, String emailAddress, String topicName, String region) {
+ validateEmailAddress(emailAddress);
+ String effectiveTopic = (topicName == null || topicName.isBlank()) ? null : topicName;
+ String key = contactKey(region, listName, emailAddress);
+ synchronized (contactMutationLock) {
+ ContactList list = getContactList(listName, region);
+ if (effectiveTopic != null && defaultTopicStatus(list, effectiveTopic) == null) {
+ throw new AwsException("BadRequestException",
+ "Topic " + effectiveTopic + " does not exist in contact list " + listName + ".", 400);
+ }
+ Contact contact = contactStore.get(key).orElseGet(() -> {
+ Contact created = new Contact(emailAddress);
+ created.setCreatedTimestamp(Instant.now(clock));
+ return created;
+ });
+ if (effectiveTopic == null) {
+ contact.setUnsubscribeAll(true);
+ } else {
+ setTopicPreference(contact, effectiveTopic, "OPT_OUT");
+ }
+ contact.setLastUpdatedTimestamp(Instant.now(clock));
+ contactStore.put(key, contact);
+ }
+ LOG.infov("List-management unsubscribe: {0} from list {1} topic {2} (region {3})",
+ emailAddress, listName, effectiveTopic == null ? "<all>" : effectiveTopic, region);
+ }
+
+ private static void setTopicPreference(Contact contact, String topicName, String status) {
+ // Copy into a fresh mutable list and set it back, so this works even if the contact's
+ // preferences were stored as an unmodifiable list (setTopicPreferences keeps the list as-is).
+ List<TopicPreference> prefs = new ArrayList<>(contact.getTopicPreferences());
+ boolean found = false;
+ for (TopicPreference pref : prefs) {
+ if (topicName.equals(pref.getTopicName())) {
+ pref.setSubscriptionStatus(status);
+ found = true;
+ break;
+ }
+ }
+ if (!found) {
+ prefs.add(new TopicPreference(topicName, status));
+ }
+ contact.setTopicPreferences(prefs);
+ }
+
/**
* Filter out recipients whose effective suppression reason is non-null. Returns a new
* list containing only the addresses that should reach the SMTP relay, mirroring AWS
@@ -2779,12 +3063,13 @@ public class SesService {
List<String> bccAddresses, List<String> replyToAddresses,
String templateName, JsonNode templateData,
String configurationSetName, List<MessageTag> emailTags,
- List<MessageHeader> additionalHeaders, String region) {
+ List<MessageHeader> additionalHeaders,
+ ListManagementOptions listManagement, String region) {
EmailTemplate template = getTemplate(templateName, region);
return sendInlineTemplatedEmail(source, toAddresses, ccAddresses, bccAddresses,
replyToAddresses, template.getSubject(), template.getTextPart(),
template.getHtmlPart(), templateData,
- configurationSetName, emailTags, additionalHeaders, region);
+ configurationSetName, emailTags, additionalHeaders, listManagement, region);
}
public String renderTestTemplate(String templateName, String templateDataRaw, String region) {
@@ -2906,7 +3191,7 @@ public class SesService {
JsonNode templateData,
String configurationSetName, List<MessageTag> emailTags,
List<MessageHeader> additionalHeaders,
- String region) {
+ ListManagementOptions listManagement, String region) {
boolean hasSubject = subject != null && !subject.isBlank();
boolean hasText = textPart != null && !textPart.isBlank();
boolean hasHtml = htmlPart != null && !htmlPart.isBlank();
@@ -2918,7 +3203,7 @@ public class SesService {
applyTemplateData(subject, templateData),
applyTemplateData(textPart, templateData),
applyTemplateData(htmlPart, templateData),
- configurationSetName, emailTags, additionalHeaders, region);
+ configurationSetName, emailTags, additionalHeaders, listManagement, region);
}
public List<BulkEmailEntryResult> sendBulkTemplatedEmail(String source,
@@ -2967,13 +3252,15 @@ public class SesService {
JsonNode merged = mergeTemplateData(defaultTemplateData, entry.replacementTemplateData());
List<MessageTag> mergedTags = mergeEmailTags(defaultEmailTags, entry.replacementEmailTags());
List<MessageHeader> mergedHeaders = mergeHeaders(defaultHeaders, entry.replacementHeaders());
+ // SendBulkEmail has no ListManagementOptions field, so list-managed suppression
+ // does not apply to bulk sends.
String messageId = sendEmail(source,
entry.toAddresses(), entry.ccAddresses(), entry.bccAddresses(),
replyToAddresses,
applyTemplateData(subject, merged),
applyTemplateData(textPart, merged),
applyTemplateData(htmlPart, merged),
- configurationSetName, mergedTags, mergedHeaders, region);
+ configurationSetName, mergedTags, mergedHeaders, null, region);
results.add(BulkEmailEntryResult.success(messageId));
} catch (AwsException e) {
results.add(BulkEmailEntryResult.failure(
@@ -3080,6 +3367,13 @@ public class SesService {
StringBuilder out = new StringBuilder();
while (matcher.find()) {
String key = matcher.group(1);
+ if ("amazonSESUnsubscribeUrl".equals(key)) {
+ // Reserved list-management placeholder: leave it intact for post-render replacement
+ // in the send path, so a templated body can carry {{amazonSESUnsubscribeUrl}} without
+ // failing as a missing rendering attribute.
+ matcher.appendReplacement(out, Matcher.quoteReplacement(matcher.group(0)));
+ continue;
+ }
if (data == null || !data.hasNonNull(key)) {
throw new AwsException("MissingRenderingAttribute",
"Attribute '" + key + "' is not present in the rendering data.", 400);
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/SesUnsubscribeController.java b/src/main/java/io/github/hectorvent/floci/services/ses/SesUnsubscribeController.java
new file mode 100644
index 0000000000..a628b2976e
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/SesUnsubscribeController.java
@@ -0,0 +1,122 @@
+package io.github.hectorvent.floci.services.ses;
+
+import io.github.hectorvent.floci.core.common.AwsException;
+import jakarta.inject.Inject;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.POST;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.Produces;
+import jakarta.ws.rs.QueryParam;
+import jakarta.ws.rs.core.MediaType;
+import jakarta.ws.rs.core.Response;
+
+import java.net.URLEncoder;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Serves the functional list-management unsubscribe link that {@code SendEmail} injects into a
+ * single-recipient {@code ListManagementOptions} message (the {@code List-Unsubscribe} header and the
+ * {@code {{amazonSESUnsubscribeUrl}}} body placeholder). AWS hosts this on an opaque endpoint; Floci
+ * hosts its own so the link actually resolves and updates the contact's subscription.
+ *
+ * <p>{@code GET} handles a browser click and only renders a confirmation page — it does not change any
+ * subscription, matching the AWS landing-page behavior and avoiding the RFC 8058 hazard where mail
+ * clients or link-preview bots that prefetch the URL would otherwise silently opt the contact out.
+ * The actual opt-out runs on {@code POST} (the RFC 8058 one-click request the confirmation form
+ * submits), which opts the contact out of the given topic, or the whole list when no topic is given.
+ *
+ * <p>Unlike AWS's opaque hosted token, this endpoint carries the target in readable query parameters
+ * and — like the rest of Floci — is unauthenticated, so a {@code POST} can opt out any contact.
+ * That is acceptable only because Floci is a local emulator for a trusted dev/test network; it must
+ * not be exposed on an untrusted network.
+ */
+@Path("/_aws/ses/unsubscribe")
+public class SesUnsubscribeController {
+
+ private final SesService sesService;
+
+ @Inject
+ public SesUnsubscribeController(SesService sesService) {
+ this.sesService = sesService;
+ }
+
+ @GET
+ @Produces(MediaType.TEXT_HTML)
+ public Response unsubscribeGet(@QueryParam("region") String region,
+ @QueryParam("contactList") String contactList,
+ @QueryParam("topic") String topic,
+ @QueryParam("address") String address) {
+ Response invalid = validate(region, contactList, address);
+ if (invalid != null) {
+ return invalid;
+ }
+ // A browser click only lands on a confirmation page; the opt-out is performed by the POST that
+ // the form submits, so a client or bot prefetching the link cannot unsubscribe the contact.
+ String html = "<!doctype html>\n"
+ + "<html lang=\"en\"><head><meta charset=\"utf-8\"><title>Unsubscribe</title></head>\n"
+ + "<body>\n"
+ + "<p>Unsubscribe " + htmlEscape(address) + " from " + htmlEscape(scopeLabel(topic))
+ + " on contact list &#39;" + htmlEscape(contactList) + "&#39;?</p>\n"
+ + "<form method=\"post\" action=\""
+ + htmlEscape(formAction(region, contactList, topic, address)) + "\">\n"
+ // RFC 8058 one-click parameter, so the form's POST body matches the advertised
+ // List-Unsubscribe-Post: List-Unsubscribe=One-Click header.
+ + "<input type=\"hidden\" name=\"List-Unsubscribe\" value=\"One-Click\">\n"
+ + "<button type=\"submit\">Unsubscribe</button>\n"
+ + "</form>\n"
+ + "</body></html>\n";
+ return Response.ok(html).build();
+ }
+
+ @POST
+ @Produces(MediaType.TEXT_PLAIN)
+ public Response unsubscribePost(@QueryParam("region") String region,
+ @QueryParam("contactList") String contactList,
+ @QueryParam("topic") String topic,
+ @QueryParam("address") String address) {
+ Response invalid = validate(region, contactList, address);
+ if (invalid != null) {
+ return invalid;
+ }
+ try {
+ sesService.unsubscribeContact(contactList, address, topic, region);
+ } catch (AwsException e) {
+ return Response.status(e.getHttpStatus()).entity(e.getMessage()).build();
+ }
+ return Response.ok(address + " has been unsubscribed from " + scopeLabel(topic)
+ + " on contact list '" + contactList + "'.").build();
+ }
+
+ private Response validate(String region, String contactList, String address) {
+ // The injected unsubscribe link always carries the region, so require it rather than
+ // defaulting — defaulting could opt a contact out in the wrong region.
+ if (region == null || region.isBlank() || contactList == null || contactList.isBlank()
+ || address == null || address.isBlank()) {
+ return Response.status(400).entity("region, contactList and address are required.").build();
+ }
+ return null;
+ }
+
+ private static String scopeLabel(String topic) {
+ return (topic == null || topic.isBlank()) ? "all topics" : "topic '" + topic + "'";
+ }
+
+ private static String formAction(String region, String contactList, String topic, String address) {
+ StringBuilder sb = new StringBuilder("?region=").append(enc(region))
+ .append("&contactList=").append(enc(contactList))
+ .append("&address=").append(enc(address));
+ if (topic != null && !topic.isBlank()) {
+ sb.append("&topic=").append(enc(topic));
+ }
+ return sb.toString();
+ }
+
+ private static String enc(String value) {
+ return URLEncoder.encode(value, StandardCharsets.UTF_8);
+ }
+
+ private static String htmlEscape(String value) {
+ return value.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+ .replace("\"", "&quot;").replace("'", "&#39;");
+ }
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/SmtpRelay.java b/src/main/java/io/github/hectorvent/floci/services/ses/SmtpRelay.java
index c8b61ba442..8801bf8948 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ses/SmtpRelay.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/SmtpRelay.java
@@ -1,6 +1,7 @@
package io.github.hectorvent.floci.services.ses;
import io.github.hectorvent.floci.config.EmulatorConfig;
+import io.github.hectorvent.floci.services.ses.model.MessageHeader;
import io.vertx.ext.mail.MailClient;
import io.vertx.ext.mail.MailConfig;
import io.vertx.ext.mail.MailMessage;
@@ -127,13 +128,14 @@ public class SmtpRelay {
*/
public void relay(String from, List<String> toAddresses, List<String> ccAddresses,
List<String> bccAddresses, List<String> replyToAddresses,
- String subject, String bodyText, String bodyHtml) {
+ String subject, String bodyText, String bodyHtml,
+ List<MessageHeader> additionalHeaders) {
if (!enabled) {
return;
}
try {
relayExecutor.execute(() -> doRelay(from, toAddresses, ccAddresses,
- bccAddresses, replyToAddresses, subject, bodyText, bodyHtml));
+ bccAddresses, replyToAddresses, subject, bodyText, bodyHtml, additionalHeaders));
} catch (java.util.concurrent.RejectedExecutionException e) {
LOG.warnv("SMTP relay skipped (executor shutting down) for from={0}", from);
}
@@ -141,7 +143,8 @@ public class SmtpRelay {
private void doRelay(String from, List<String> toAddresses, List<String> ccAddresses,
List<String> bccAddresses, List<String> replyToAddresses,
- String subject, String bodyText, String bodyHtml) {
+ String subject, String bodyText, String bodyHtml,
+ List<MessageHeader> additionalHeaders) {
try {
MailMessage mail = new MailMessage();
mail.setFrom(from);
@@ -157,6 +160,16 @@ public class SmtpRelay {
if (replyToAddresses != null && !replyToAddresses.isEmpty()) {
mail.addHeader("Reply-To", String.join(", ", replyToAddresses));
}
+ if (additionalHeaders != null) {
+ for (MessageHeader header : additionalHeaders) {
+ if (header.isSafe()) {
+ mail.addHeader(header.name(), header.value());
+ } else {
+ LOG.warnv("SMTP relay: skipping a header with a blank name or CR/LF in its "
+ + "name/value (possible header injection) for from={0}", from);
+ }
+ }
+ }
mail.setSubject(subject != null ? subject : "");
if (bodyText != null) {
mail.setText(bodyText);
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/model/ListManagementOptions.java b/src/main/java/io/github/hectorvent/floci/services/ses/model/ListManagementOptions.java
new file mode 100644
index 0000000000..3dff25b96d
--- /dev/null
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/model/ListManagementOptions.java
@@ -0,0 +1,10 @@
+package io.github.hectorvent.floci.services.ses.model;
+
+/**
+ * The SES V2 {@code SendEmail} {@code ListManagementOptions}: the contact list a send is scoped to
+ * and an optional topic. When present, opted-out contacts on the named list are suppressed from the
+ * send. This is a request-only transport value (never persisted or serialized), so it carries no
+ * Jackson or reflection annotations.
+ */
+public record ListManagementOptions(String contactListName, String topicName) {
+}
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/model/MessageHeader.java b/src/main/java/io/github/hectorvent/floci/services/ses/model/MessageHeader.java
index 5b0406d0cc..e58cc1e85c 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ses/model/MessageHeader.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/model/MessageHeader.java
@@ -12,4 +12,17 @@ import io.quarkus.runtime.annotations.RegisterForReflection;
public record MessageHeader(
@JsonProperty("Name") String name,
@JsonProperty("Value") String value) {
+
+ /**
+ * Whether this header is safe to attach to an outgoing message: its name must be non-blank and
+ * neither name nor value may contain CR/LF, otherwise it could inject additional headers. Used to
+ * filter user-supplied headers consistently across storage, relay, and event publishing.
+ */
+ public boolean isSafe() {
+ return name != null && !name.isBlank() && noCrlf(name) && value != null && noCrlf(value);
+ }
+
+ private static boolean noCrlf(String s) {
+ return s.indexOf('\r') < 0 && s.indexOf('\n') < 0;
+ }
}
diff --git a/src/main/java/io/github/hectorvent/floci/services/ses/model/SentEmail.java b/src/main/java/io/github/hectorvent/floci/services/ses/model/SentEmail.java
index 5ab7faefde..c837183b05 100644
--- a/src/main/java/io/github/hectorvent/floci/services/ses/model/SentEmail.java
+++ b/src/main/java/io/github/hectorvent/floci/services/ses/model/SentEmail.java
@@ -46,6 +46,9 @@ public class SentEmail {
@JsonProperty("RawData")
private String rawData;
+ @JsonProperty("Headers")
+ private List<MessageHeader> headers;
+
@JsonProperty("SentAt")
private Instant sentAt;
@@ -113,6 +116,9 @@ public class SentEmail {
public String getRawData() { return rawData; }
public void setRawData(String rawData) { this.rawData = rawData; }
+ public List<MessageHeader> getHeaders() { return headers; }
+ public void setHeaders(List<MessageHeader> headers) { this.headers = headers; }
+
public boolean isRaw() { return rawData != null; }
public Instant getSentAt() { return sentAt; }
diff --git a/src/test/java/io/github/hectorvent/floci/services/cognito/verification/CognitoMessageDispatcherTest.java b/src/test/java/io/github/hectorvent/floci/services/cognito/verification/CognitoMessageDispatcherTest.java
index db28add75a..ddfff4ab3b 100644
--- a/src/test/java/io/github/hectorvent/floci/services/cognito/verification/CognitoMessageDispatcherTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/cognito/verification/CognitoMessageDispatcherTest.java
@@ -50,7 +50,7 @@ class CognitoMessageDispatcherTest {
eq("Verify your account"),
eq("Hi! Your code is 123456."),
isNull(), isNull(), eq(List.of()), eq(List.of()),
- eq("us-east-1"));
+ isNull(), eq("us-east-1"));
verifyNoInteractions(sns);
}
@@ -105,7 +105,7 @@ class CognitoMessageDispatcherTest {
eq(List.of()), eq(List.of()), eq(List.of()),
eq("Your verification code"),
eq("Your verification code is 111222."),
- isNull(), isNull(), eq(List.of()), eq(List.of()), eq("us-east-1"));
+ isNull(), isNull(), eq(List.of()), eq(List.of()), isNull(), eq("us-east-1"));
}
@Test
@@ -121,7 +121,7 @@ class CognitoMessageDispatcherTest {
eq(List.of()), eq(List.of()), eq(List.of()),
anyString(),
eq("Welcome, please verify.\nCode: 999000"),
- isNull(), isNull(), eq(List.of()), eq(List.of()), eq("us-east-1"));
+ isNull(), isNull(), eq(List.of()), eq(List.of()), isNull(), eq("us-east-1"));
}
@Test
@@ -133,7 +133,7 @@ class CognitoMessageDispatcherTest {
"444555", List.of());
verify(ses).sendEmail(anyString(), eq(List.of("[email protected]")),
- any(), any(), any(), anyString(), anyString(), isNull(), isNull(), any(), any(), anyString());
+ any(), any(), any(), anyString(), anyString(), isNull(), isNull(), any(), any(), isNull(), anyString());
verifyNoInteractions(sns);
}
diff --git a/src/test/java/io/github/hectorvent/floci/services/ses/SesListManagementOptionsV2IntegrationTest.java b/src/test/java/io/github/hectorvent/floci/services/ses/SesListManagementOptionsV2IntegrationTest.java
new file mode 100644
index 0000000000..52334d4051
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/ses/SesListManagementOptionsV2IntegrationTest.java
@@ -0,0 +1,268 @@
+package io.github.hectorvent.floci.services.ses;
+
+import io.quarkus.test.junit.QuarkusTest;
+import org.junit.jupiter.api.MethodOrderer;
+import org.junit.jupiter.api.Order;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestMethodOrder;
+
+import static io.restassured.RestAssured.given;
+import static org.hamcrest.Matchers.equalTo;
+
+/**
+ * Integration tests for the SES V2 {@code SendEmail} {@code ListManagementOptions} wiring through the
+ * REST controller: an absent recipient is auto-created as a contact, an unknown contact list fails
+ * the send, and a malformed {@code ListManagementOptions} is rejected. Uses an isolated region so the
+ * one-contact-list-per-account limit does not collide with other SES tests.
+ */
+@QuarkusTest
+@TestMethodOrder(MethodOrderer.OrderAnnotation.class)
+class SesListManagementOptionsV2IntegrationTest {
+
+ private static final String AUTH =
+ "AWS4-HMAC-SHA256 Credential=AKID/20260101/us-west-2/ses/aws4_request";
+ private static final String LIST = "lmo-newsletter";
+ private static final String FROM = "[email protected]";
+
+ @Test
+ @Order(0)
+ void setup_contactList() {
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "ContactListName": "%s",
+ "Topics": [
+ {"TopicName": "Sports", "DisplayName": "Sports",
+ "DefaultSubscriptionStatus": "OPT_IN", "Description": "d"}
+ ]
+ }
+ """.formatted(LIST))
+ .when().post("/v2/email/contact-lists").then().statusCode(200);
+ }
+
+ @Test
+ @Order(1)
+ void sendWithListManagementOptions_autoCreatesAbsentRecipient() {
+ String recipient = "[email protected]";
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "FromEmailAddress": "%s",
+ "Destination": {"ToAddresses": ["%s"]},
+ "Content": {"Simple": {"Subject": {"Data": "hi"}, "Body": {"Text": {"Data": "b"}}}},
+ "ListManagementOptions": {"ContactListName": "%s"}
+ }
+ """.formatted(FROM, recipient, LIST))
+ .when().post("/v2/email/outbound-emails").then().statusCode(200);
+
+ // AWS auto-creates a contact on the list for a recipient that isn't one yet.
+ given().header("Authorization", AUTH)
+ .when().get("/v2/email/contact-lists/" + LIST + "/contacts/" + recipient)
+ .then().statusCode(200)
+ .body("EmailAddress", equalTo(recipient));
+ }
+
+ @Test
+ @Order(2)
+ void sendWithUnknownContactList_returns404() {
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "FromEmailAddress": "%s",
+ "Destination": {"ToAddresses": ["[email protected]"]},
+ "Content": {"Simple": {"Subject": {"Data": "hi"}, "Body": {"Text": {"Data": "b"}}}},
+ "ListManagementOptions": {"ContactListName": "lmo-ghost-list"}
+ }
+ """.formatted(FROM))
+ .when().post("/v2/email/outbound-emails").then().statusCode(404)
+ .body("__type", equalTo("NotFoundException"));
+ }
+
+ @Test
+ @Order(3)
+ void listManagementOptionsWithoutContactListName_returns400() {
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "FromEmailAddress": "%s",
+ "Destination": {"ToAddresses": ["[email protected]"]},
+ "Content": {"Simple": {"Subject": {"Data": "hi"}, "Body": {"Text": {"Data": "b"}}}},
+ "ListManagementOptions": {"TopicName": "Sports"}
+ }
+ """.formatted(FROM))
+ .when().post("/v2/email/outbound-emails").then().statusCode(400)
+ .body("__type", equalTo("BadRequestException"));
+ }
+
+ @Test
+ @Order(4)
+ void listManagementOptionsWithNonStringTopicName_returns400() {
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "FromEmailAddress": "%s",
+ "Destination": {"ToAddresses": ["[email protected]"]},
+ "Content": {"Simple": {"Subject": {"Data": "hi"}, "Body": {"Text": {"Data": "b"}}}},
+ "ListManagementOptions": {"ContactListName": "%s", "TopicName": 123}
+ }
+ """.formatted(FROM, LIST))
+ .when().post("/v2/email/outbound-emails").then().statusCode(400)
+ .body("__type", equalTo("BadRequestException"));
+ }
+
+ @Test
+ @Order(5)
+ void singleRecipientSend_replacesUnsubscribePlaceholderWithFunctionalUrl() {
+ String recipient = "[email protected]";
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "FromEmailAddress": "%s",
+ "Destination": {"ToAddresses": ["%s"]},
+ "Content": {"Simple": {"Subject": {"Data": "hi"},
+ "Body": {"Html": {"Data": "<p>Unsub: {{amazonSESUnsubscribeUrl}}</p>"}}}},
+ "ListManagementOptions": {"ContactListName": "%s", "TopicName": "Sports"}
+ }
+ """.formatted(FROM, recipient, LIST))
+ .when().post("/v2/email/outbound-emails").then().statusCode(200);
+
+ // The stored message body has the placeholder replaced with a functional Floci unsubscribe URL.
+ given().header("Authorization", AUTH).queryParam("email", recipient)
+ .when().get("/_aws/ses").then().statusCode(200)
+ .body(org.hamcrest.Matchers.containsString("/_aws/ses/unsubscribe?"))
+ .body(org.hamcrest.Matchers.containsString("contactList=" + LIST))
+ .body(org.hamcrest.Matchers.containsString("topic=Sports"))
+ .body(org.hamcrest.Matchers.not(org.hamcrest.Matchers.containsString("amazonSESUnsubscribeUrl")))
+ // the stored message also carries the List-Unsubscribe header
+ .body(org.hamcrest.Matchers.containsString("List-Unsubscribe"));
+ }
+
+ @Test
+ @Order(6)
+ void unsubscribeEndpoint_optsContactOutOfTopic() {
+ String recipient = "[email protected]";
+ given().header("Authorization", AUTH)
+ .queryParam("region", "us-west-2").queryParam("contactList", LIST)
+ .queryParam("topic", "Sports").queryParam("address", recipient)
+ .when().post("/_aws/ses/unsubscribe").then().statusCode(200);
+
+ given().header("Authorization", AUTH)
+ .when().get("/v2/email/contact-lists/" + LIST + "/contacts/" + recipient)
+ .then().statusCode(200)
+ .body("TopicPreferences.find { it.TopicName == 'Sports' }.SubscriptionStatus",
+ equalTo("OPT_OUT"));
+ }
+
+ @Test
+ @Order(7)
+ void unsubscribeEndpoint_missingRegion_returns400() {
+ given().header("Authorization", AUTH)
+ .queryParam("contactList", LIST).queryParam("address", "[email protected]")
+ .when().post("/_aws/ses/unsubscribe").then().statusCode(400);
+ }
+
+ @Test
+ @Order(8)
+ void unsubscribeEndpoint_get_rendersConfirmationWithoutOptingOut() {
+ String recipient = "[email protected]";
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("{\"EmailAddress\":\"" + recipient + "\",\"TopicPreferences\":["
+ + "{\"TopicName\":\"Sports\",\"SubscriptionStatus\":\"OPT_IN\"}]}")
+ .when().post("/v2/email/contact-lists/" + LIST + "/contacts").then().statusCode(200);
+
+ // A browser click (GET) only renders a confirmation form; it must not opt the contact out,
+ // so a client or bot that prefetches the link cannot silently unsubscribe the contact.
+ given().header("Authorization", AUTH)
+ .queryParam("region", "us-west-2").queryParam("contactList", LIST)
+ .queryParam("topic", "Sports").queryParam("address", recipient)
+ .when().get("/_aws/ses/unsubscribe").then().statusCode(200)
+ .body(org.hamcrest.Matchers.containsString("<form method=\"post\""))
+ .body(org.hamcrest.Matchers.containsString("Unsubscribe"))
+ // The form action escapes '&' as '&amp;' for valid HTML, and carries the RFC 8058
+ // one-click parameter so its POST body matches the advertised header.
+ .body(org.hamcrest.Matchers.containsString("&amp;contactList="))
+ .body(org.hamcrest.Matchers.containsString(
+ "<input type=\"hidden\" name=\"List-Unsubscribe\" value=\"One-Click\">"));
+
+ given().header("Authorization", AUTH)
+ .when().get("/v2/email/contact-lists/" + LIST + "/contacts/" + recipient)
+ .then().statusCode(200)
+ .body("TopicPreferences.find { it.TopicName == 'Sports' }.SubscriptionStatus",
+ equalTo("OPT_IN"));
+ }
+
+ @Test
+ @Order(9)
+ void send_unsafeHeader_isDroppedFromStoredMessage() {
+ String recipient = "[email protected]";
+ // A user-supplied header whose value carries CR/LF must not survive on any surface: the SMTP
+ // relay already drops it, and the stored SentEmail (GET /_aws/ses) must not retain it either.
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "FromEmailAddress": "%s",
+ "Destination": {"ToAddresses": ["%s"]},
+ "Content": {"Simple": {"Subject": {"Data": "hi"}, "Body": {"Text": {"Data": "hi"}},
+ "Headers": [
+ {"Name": "X-Safe", "Value": "ok"},
+ {"Name": "X-Evil", "Value": "bad\\r\\nBcc: [email protected]"}
+ ]}}
+ }
+ """.formatted(FROM, recipient))
+ .when().post("/v2/email/outbound-emails").then().statusCode(200);
+
+ given().header("Authorization", AUTH).queryParam("email", recipient)
+ .when().get("/_aws/ses").then().statusCode(200)
+ .body(org.hamcrest.Matchers.containsString("X-Safe"))
+ .body(org.hamcrest.Matchers.not(org.hamcrest.Matchers.containsString("X-Evil")))
+ .body(org.hamcrest.Matchers.not(org.hamcrest.Matchers.containsString("[email protected]")));
+ }
+
+ @Test
+ @Order(10)
+ void send_headerMissingValue_isRejectedLikeAws() {
+ // AWS enforces Content.Simple.Headers[].Value as a required member: a header object that omits
+ // Value is rejected with BadRequestException and a Smithy constraint message, rather than being
+ // silently dropped.
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "FromEmailAddress": "%s",
+ "Destination": {"ToAddresses": ["[email protected]"]},
+ "Content": {"Simple": {"Subject": {"Data": "hi"}, "Body": {"Text": {"Data": "b"}},
+ "Headers": [{"Name": "X-Foo"}]}}
+ }
+ """.formatted(FROM))
+ .when().post("/v2/email/outbound-emails").then().statusCode(400)
+ .body("__type", equalTo("BadRequestException"))
+ .body("message", org.hamcrest.Matchers.containsString(
+ "content.simple.headers.1.member.value"))
+ .body("message", org.hamcrest.Matchers.containsString("Member must not be null"));
+ }
+
+ @Test
+ @Order(11)
+ void send_headerMissingName_isRejectedLikeAws() {
+ given().contentType("application/json").header("Authorization", AUTH)
+ .body("""
+ {
+ "FromEmailAddress": "%s",
+ "Destination": {"ToAddresses": ["[email protected]"]},
+ "Content": {"Simple": {"Subject": {"Data": "hi"}, "Body": {"Text": {"Data": "b"}},
+ "Headers": [{"Value": "bar"}]}}
+ }
+ """.formatted(FROM))
+ .when().post("/v2/email/outbound-emails").then().statusCode(400)
+ .body("__type", equalTo("BadRequestException"))
+ .body("message", org.hamcrest.Matchers.containsString(
+ "content.simple.headers.1.member.name"))
+ .body("message", org.hamcrest.Matchers.containsString("Member must not be null"));
+ }
+
+ @Test
+ @Order(99)
+ void cleanup_deleteContactList() {
+ given().header("Authorization", AUTH)
+ .when().delete("/v2/email/contact-lists/" + LIST).then().statusCode(200);
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/ses/SesServiceListManagementTest.java b/src/test/java/io/github/hectorvent/floci/services/ses/SesServiceListManagementTest.java
new file mode 100644
index 0000000000..b1dc9c9bc4
--- /dev/null
+++ b/src/test/java/io/github/hectorvent/floci/services/ses/SesServiceListManagementTest.java
@@ -0,0 +1,269 @@
+package io.github.hectorvent.floci.services.ses;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import io.github.hectorvent.floci.core.common.AwsException;
+import io.github.hectorvent.floci.core.storage.InMemoryStorage;
+import io.github.hectorvent.floci.services.ses.model.AccountSuppressionAttributes;
+import io.github.hectorvent.floci.services.ses.model.ConfigurationSet;
+import io.github.hectorvent.floci.services.ses.model.Contact;
+import io.github.hectorvent.floci.services.ses.model.ContactList;
+import io.github.hectorvent.floci.services.ses.model.DedicatedIpPool;
+import io.github.hectorvent.floci.services.ses.model.EmailTemplate;
+import io.github.hectorvent.floci.services.ses.model.Identity;
+import io.github.hectorvent.floci.services.ses.model.ListManagementOptions;
+import io.github.hectorvent.floci.services.ses.model.MessageHeader;
+import io.github.hectorvent.floci.services.ses.model.ReceiptRuleSet;
+import io.github.hectorvent.floci.services.ses.model.SentEmail;
+import io.github.hectorvent.floci.services.ses.model.SuppressedDestination;
+import io.github.hectorvent.floci.services.ses.model.Topic;
+import io.github.hectorvent.floci.services.ses.model.TopicPreference;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.ArgumentCaptor;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.time.Clock;
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+
+/**
+ * Unit tests for SES V2 {@code SendEmail} {@code ListManagementOptions} suppression: opted-out
+ * contacts on the named list are dropped from the SMTP relay (surfaced here via the relay mock),
+ * absent recipients are auto-created, and an unknown contact list fails the send. Uses the relay
+ * mock to observe exactly which recipients survive suppression.
+ */
+@ExtendWith(MockitoExtension.class)
+class SesServiceListManagementTest {
+
+ private static final String REGION = "us-east-1";
+ private static final String LIST = "newsletter";
+ private static final String FROM = "[email protected]";
+
+ @Mock SmtpRelay smtpRelay;
+
+ private SesService service;
+ private InMemoryStorage<String, Contact> contactStore;
+
+ @BeforeEach
+ void setUp() {
+ contactStore = new InMemoryStorage<>();
+ service = new SesService(
+ new InMemoryStorage<String, Identity>(),
+ new InMemoryStorage<String, SentEmail>(),
+ new InMemoryStorage<String, Boolean>(),
+ new InMemoryStorage<String, EmailTemplate>(),
+ new InMemoryStorage<String, ConfigurationSet>(),
+ new InMemoryStorage<String, SuppressedDestination>(),
+ new InMemoryStorage<String, AccountSuppressionAttributes>(),
+ new InMemoryStorage<String, DedicatedIpPool>(),
+ new InMemoryStorage<String, ContactList>(),
+ contactStore,
+ new InMemoryStorage<String, String>(),
+ new InMemoryStorage<String, ReceiptRuleSet>(),
+ smtpRelay,
+ new ObjectMapper(),
+ Clock.systemUTC());
+
+ // Sports defaults OPT_IN, Promos defaults OPT_OUT.
+ service.createContactList(LIST, "desc", List.of(
+ new Topic("Sports", "Sports", "OPT_IN", "d"),
+ new Topic("Promos", "Promos", "OPT_OUT", "d")), List.of(), REGION);
+ service.createContact(LIST, "[email protected]", List.of(), true, null, REGION);
+ service.createContact(LIST, "[email protected]",
+ List.of(new TopicPreference("Sports", "OPT_OUT")), false, null, REGION);
+ service.createContact(LIST, "[email protected]",
+ List.of(new TopicPreference("Sports", "OPT_IN")), false, null, REGION);
+ service.createContact(LIST, "[email protected]", List.of(), false, null, REGION);
+ }
+
+ private void send(List<String> to, String topicName) {
+ service.sendEmail(FROM, to, null, null, null, "Subject", "body", null,
+ null, List.of(), List.of(), new ListManagementOptions(LIST, topicName), REGION);
+ }
+
+ @SuppressWarnings("unchecked")
+ private List<String> capturedRelayTo() {
+ ArgumentCaptor<List<String>> captor = ArgumentCaptor.forClass(List.class);
+ verify(smtpRelay).relay(any(), captor.capture(), any(), any(), any(), any(), any(), any(), any());
+ return captor.getValue();
+ }
+
+ @Test
+ void unsubscribeAll_isSuppressed_evenWithNoTopic() {
+ send(List.of("[email protected]", "[email protected]"), null);
+ assertEquals(List.of("[email protected]"), capturedRelayTo());
+ }
+
+ @Test
+ void noTopic_onlyUnsubscribeAllSuppressed_topicOptOutStillSent() {
+ // Without a topic, a contact opted out of a single topic (but not UnsubscribeAll) still gets it.
+ send(List.of("[email protected]", "[email protected]"), null);
+ assertEquals(List.of("[email protected]"), capturedRelayTo());
+ }
+
+ @Test
+ void topicExplicitOptOut_isSuppressed() {
+ send(List.of("[email protected]", "[email protected]"), "Sports");
+ assertEquals(List.of("[email protected]"), capturedRelayTo());
+ }
+
+ @Test
+ void topicDefaultOptOut_suppressesContactWithNoExplicitPreference() {
+ // Promos defaults OPT_OUT and noprefs has no explicit Promos preference -> suppressed.
+ send(List.of("[email protected]"), "Promos");
+ verify(smtpRelay, never()).relay(any(), any(), any(), any(), any(), any(), any(), any(), any());
+ }
+
+ @Test
+ void topicDefaultOptIn_sendsContactWithNoExplicitPreference() {
+ send(List.of("[email protected]"), "Sports");
+ assertEquals(List.of("[email protected]"), capturedRelayTo());
+ }
+
+ @Test
+ void recipientNotAContact_isAutoCreatedAndSent() {
+ send(List.of("[email protected]"), null);
+ assertEquals(List.of("[email protected]"), capturedRelayTo());
+ assertTrue(contactStore.get("contact::" + REGION + "::" + LIST + "::[email protected]").isPresent(),
+ "an absent recipient must be auto-created as a contact on the list");
+ }
+
+ @Test
+ void nonExistentContactList_failsTheSend() {
+ AwsException ex = assertThrows(AwsException.class, () ->
+ service.sendEmail(FROM, List.of("[email protected]"), null, null, null,
+ "Subject", "body", null, null, List.of(), List.of(),
+ new ListManagementOptions("ghost-list", null), REGION));
+ assertEquals(404, ex.getHttpStatus());
+ }
+
+ @Test
+ void unknownTopic_failsTheSend() {
+ // A TopicName not defined on the list is rejected rather than silently skipping suppression.
+ AwsException ex = assertThrows(AwsException.class, () ->
+ service.sendEmail(FROM, List.of("[email protected]"), null, null, null,
+ "Subject", "body", null, null, List.of(), List.of(),
+ new ListManagementOptions(LIST, "GhostTopic"), REGION));
+ assertEquals(400, ex.getHttpStatus());
+ }
+
+ @Test
+ void noListManagementOptions_leavesRecipientsUntouched() {
+ // Without ListManagementOptions the contact list is never consulted: an unsubscribed contact
+ // is not suppressed and no contact is auto-created.
+ service.sendEmail(FROM, List.of("[email protected]"), null, null, null,
+ "Subject", "body", null, null, List.of(), List.of(), null, REGION);
+ assertEquals(List.of("[email protected]"), capturedRelayTo());
+ }
+
+ @Test
+ void singleRecipient_replacesUnsubscribePlaceholder() {
+ // newbie is not a contact (auto-created, Sports defaults OPT_IN) so the send reaches the relay.
+ service.sendEmail(FROM, List.of("[email protected]"), null, null, null,
+ "Subject", "text", "<p>Unsub: {{amazonSESUnsubscribeUrl}}</p>",
+ null, List.of(), List.of(), new ListManagementOptions(LIST, "Sports"), REGION);
+ String html = capturedRelayBodyHtml();
+ assertTrue(html.contains("http://localhost:4566/_aws/ses/unsubscribe?"), html);
+ assertTrue(html.contains("contactList=" + LIST), html);
+ assertTrue(html.contains("topic=Sports"), html);
+ assertFalse(html.contains("{{amazonSESUnsubscribeUrl}}"), "placeholder must be replaced");
+ }
+
+ @Test
+ void multiRecipient_doesNotReplacePlaceholder() {
+ service.sendEmail(FROM, List.of("[email protected]", "[email protected]"), null, null, null,
+ "Subject", "text", "<p>Unsub: {{amazonSESUnsubscribeUrl}}</p>",
+ null, List.of(), List.of(), new ListManagementOptions(LIST, "Sports"), REGION);
+ assertTrue(capturedRelayBodyHtml().contains("{{amazonSESUnsubscribeUrl}}"),
+ "multi-recipient send must not inject the unsubscribe link");
+ }
+
+ @Test
+ void unsubscribeContact_withTopic_setsOptOut() {
+ service.unsubscribeContact(LIST, "[email protected]", "Sports", REGION);
+ Contact c = contact("[email protected]");
+ assertTrue(c.getTopicPreferences().stream()
+ .anyMatch(p -> "Sports".equals(p.getTopicName()) && "OPT_OUT".equals(p.getSubscriptionStatus())));
+ }
+
+ @Test
+ void unsubscribeContact_withoutTopic_setsUnsubscribeAll() {
+ service.unsubscribeContact(LIST, "[email protected]", null, REGION);
+ assertTrue(contact("[email protected]").isUnsubscribeAll());
+ }
+
+ @Test
+ void unsubscribeContact_absentContact_autoCreatesAndOptsOut() {
+ service.unsubscribeContact(LIST, "[email protected]", null, REGION);
+ assertTrue(contact("[email protected]").isUnsubscribeAll());
+ }
+
+ @Test
+ void unsubscribeContact_withImmutablePreferences_addsTopicWithoutThrowing() {
+ Contact c = new Contact("[email protected]");
+ c.setTopicPreferences(List.of(new TopicPreference("Sports", "OPT_IN")));
+ contactStore.put("contact::" + REGION + "::" + LIST + "::[email protected]", c);
+
+ service.unsubscribeContact(LIST, "[email protected]", "Promos", REGION);
+
+ assertTrue(contact("[email protected]").getTopicPreferences().stream()
+ .anyMatch(p -> "Promos".equals(p.getTopicName()) && "OPT_OUT".equals(p.getSubscriptionStatus())));
+ }
+
+ private Contact contact(String email) {
+ return contactStore.get("contact::" + REGION + "::" + LIST + "::" + email).orElseThrow();
+ }
+
+ @SuppressWarnings("unchecked")
+ private String capturedRelayBodyHtml() {
+ ArgumentCaptor<String> captor = ArgumentCaptor.forClass(String.class);
+ verify(smtpRelay).relay(any(), any(), any(), any(), any(), any(), any(), captor.capture(), any());
+ return captor.getValue();
+ }
+
+ @SuppressWarnings("unchecked")
+ private List<MessageHeader> capturedRelayHeaders() {
+ ArgumentCaptor<List<MessageHeader>> captor = ArgumentCaptor.forClass(List.class);
+ verify(smtpRelay).relay(any(), any(), any(), any(), any(), any(), any(), any(), captor.capture());
+ return captor.getValue();
+ }
+
+ @Test
+ void singleRecipient_addsListUnsubscribeHeadersToRelay() {
+ service.sendEmail(FROM, List.of("[email protected]"), null, null, null,
+ "Subject", "text", "<p>x</p>", null, List.of(), List.of(),
+ new ListManagementOptions(LIST, "Sports"), REGION);
+ List<MessageHeader> headers = capturedRelayHeaders();
+ assertTrue(headers.stream().anyMatch(h -> "List-Unsubscribe".equals(h.name())
+ && h.value().contains("/_aws/ses/unsubscribe")), "List-Unsubscribe header must reach the relay");
+ assertTrue(headers.stream().anyMatch(h -> "List-Unsubscribe-Post".equals(h.name())
+ && "List-Unsubscribe=One-Click".equals(h.value())));
+ }
+
+ @Test
+ void callerSuppliedUnsubscribeHeader_isOverriddenNotDuplicated() {
+ service.sendEmail(FROM, List.of("[email protected]"), null, null, null,
+ "Subject", "text", "<p>x</p>", null, List.of(),
+ List.of(new MessageHeader("List-Unsubscribe", "<https://caller.example/u>")),
+ new ListManagementOptions(LIST, "Sports"), REGION);
+ long count = capturedRelayHeaders().stream()
+ .filter(h -> "List-Unsubscribe".equalsIgnoreCase(h.name())).count();
+ assertEquals(1L, count);
+ }
+
+ @Test
+ void applyTemplateData_leavesUnsubscribePlaceholderIntact() {
+ String rendered = SesService.applyTemplateData("<p>{{amazonSESUnsubscribeUrl}} {{name}}</p>",
+ new ObjectMapper().createObjectNode().put("name", "Bob"));
+ assertEquals("<p>{{amazonSESUnsubscribeUrl}} Bob</p>", rendered);
+ }
+}
diff --git a/src/test/java/io/github/hectorvent/floci/services/ses/SesServiceSmtpTest.java b/src/test/java/io/github/hectorvent/floci/services/ses/SesServiceSmtpTest.java
index ee79aace28..78fb9fd620 100644
--- a/src/test/java/io/github/hectorvent/floci/services/ses/SesServiceSmtpTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/ses/SesServiceSmtpTest.java
@@ -60,7 +60,7 @@ class SesServiceSmtpTest {
List.of("[email protected]"),
List.of("[email protected]"),
List.of("[email protected]"),
- "Subject", "text body", "<p>html</p>", null, List.of(), List.of(), "us-east-1");
+ "Subject", "text body", "<p>html</p>", null, List.of(), List.of(), null, "us-east-1");
verify(smtpRelay).relay(
@@ -68,24 +68,24 @@ class SesServiceSmtpTest {
List.of("[email protected]"),
List.of("[email protected]"),
List.of("[email protected]"),
- "Subject", "text body", "<p>html</p>");
+ "Subject", "text body", "<p>html</p>", List.of());
}
@Test
void sendEmail_storesAndRelays() {
String messageId = service.sendEmail("[email protected]",
List.of("[email protected]"), null, null, null,
- "Subject", "text", null, null, List.of(), List.of(), "us-east-1");
+ "Subject", "text", null, null, List.of(), List.of(), null, "us-east-1");
assertNotNull(messageId);
assertFalse(emailStore.scan(k -> true).isEmpty());
- verify(smtpRelay).relay(any(), any(), any(), any(), any(), any(), any(), any());
+ verify(smtpRelay).relay(any(), any(), any(), any(), any(), any(), any(), any(), any());
}
@Test
void sendRawEmail_callsRelayRaw() {
service.sendRawEmail("[email protected]",
- List.of("[email protected]"), "raw MIME", null, List.of(), "us-east-1");
+ List.of("[email protected]"), "raw MIME", null, List.of(), null, "us-east-1");
verify(smtpRelay).relayRaw(
@@ -96,7 +96,7 @@ class SesServiceSmtpTest {
@Test
void sendRawEmail_storesAndRelays() {
String messageId = service.sendRawEmail("[email protected]",
- List.of("[email protected]"), "raw", null, List.of(), "us-east-1");
+ List.of("[email protected]"), "raw", null, List.of(), null, "us-east-1");
assertNotNull(messageId);
assertFalse(emailStore.scan(k -> true).isEmpty());
@@ -108,13 +108,13 @@ class SesServiceSmtpTest {
service.sendEmail("[email protected]",
List.of("[email protected]"),
null, null, null,
- "Subject", null, "<p>html only</p>", null, List.of(), List.of(), "us-east-1");
+ "Subject", null, "<p>html only</p>", null, List.of(), List.of(), null, "us-east-1");
verify(smtpRelay).relay(
List.of("[email protected]"),
null, null, null,
- "Subject", null, "<p>html only</p>");
+ "Subject", null, "<p>html only</p>", List.of());
}
@Test
@@ -126,12 +126,12 @@ class SesServiceSmtpTest {
List.of("[email protected]"),
List.of("[email protected]"),
null, null,
- "Subject", "text body", null, null, List.of(), List.of(), "us-east-1");
+ "Subject", "text body", null, null, List.of(), List.of(), null, "us-east-1");
assertNotNull(messageId);
assertFalse(emailStore.scan(k -> true).isEmpty(),
"stored SentEmail should still record the original recipient list");
- verify(smtpRelay, never()).relay(any(), any(), any(), any(), any(), any(), any(), any());
+ verify(smtpRelay, never()).relay(any(), any(), any(), any(), any(), any(), any(), any(), any());
}
@Test
@@ -143,7 +143,7 @@ class SesServiceSmtpTest {
List.of("[email protected]"),
null, null,
- "Subject", "text body", null, null, List.of(), List.of(), "us-east-1");
+ "Subject", "text body", null, null, List.of(), List.of(), null, "us-east-1");
verify(smtpRelay).relay(
@@ -151,7 +151,7 @@ class SesServiceSmtpTest {
List.of("[email protected]"),
null,
null,
- "Subject", "text body", null);
+ "Subject", "text body", null, List.of());
}
@Test
@@ -159,7 +159,7 @@ class SesServiceSmtpTest {
service.putSuppressedDestination("us-east-1", "[email protected]", "BOUNCE");
String messageId = service.sendRawEmail("[email protected]",
- List.of("[email protected]"), "raw MIME", null, List.of(), "us-east-1");
+ List.of("[email protected]"), "raw MIME", null, List.of(), null, "us-east-1");
assertNotNull(messageId);
assertFalse(emailStore.scan(k -> true).isEmpty());
@@ -172,7 +172,7 @@ class SesServiceSmtpTest {
service.sendRawEmail("[email protected]",
- "raw MIME", null, List.of(), "us-east-1");
+ "raw MIME", null, List.of(), null, "us-east-1");
verify(smtpRelay).relayRaw(
@@ -194,13 +194,13 @@ class SesServiceSmtpTest {
service.sendEmail("[email protected]",
List.of("[email protected]"), null, null, null,
- "Subject", "text body", null, "cs-no-suppression", List.of(), List.of(), "us-east-1");
+ "Subject", "text body", null, "cs-no-suppression", List.of(), List.of(), null, "us-east-1");
verify(smtpRelay).relay(
List.of("[email protected]"),
null, null, null,
- "Subject", "text body", null);
+ "Subject", "text body", null, List.of());
}
@Test
@@ -214,13 +214,13 @@ class SesServiceSmtpTest {
service.sendEmail("[email protected]",
List.of("[email protected]"), null, null, null,
- "Subject", "text body", null, "cs-bounce-only", List.of(), List.of(), "us-east-1");
+ "Subject", "text body", null, "cs-bounce-only", List.of(), List.of(), null, "us-east-1");
verify(smtpRelay).relay(
List.of("[email protected]"),
null, null, null,
- "Subject", "text body", null);
+ "Subject", "text body", null, List.of());
}
@Test
@@ -233,9 +233,9 @@ class SesServiceSmtpTest {
service.sendEmail("[email protected]",
List.of("[email protected]"), null, null, null,
- "Subject", "text body", null, "cs-default", List.of(), List.of(), "us-east-1");
+ "Subject", "text body", null, "cs-default", List.of(), List.of(), null, "us-east-1");
- verify(smtpRelay, never()).relay(any(), any(), any(), any(), any(), any(), any(), any());
+ verify(smtpRelay, never()).relay(any(), any(), any(), any(), any(), any(), any(), any(), any());
}
@Test
@@ -245,7 +245,7 @@ class SesServiceSmtpTest {
service.putConfigurationSetSuppressionOptions("cs-no-suppression-raw", List.of(), "us-east-1");
service.sendRawEmail("[email protected]",
- List.of("[email protected]"), "raw MIME", "cs-no-suppression-raw", List.of(), "us-east-1");
+ List.of("[email protected]"), "raw MIME", "cs-no-suppression-raw", List.of(), null, "us-east-1");
verify(smtpRelay).relayRaw(
diff --git a/src/test/java/io/github/hectorvent/floci/services/ses/SmtpRelayTest.java b/src/test/java/io/github/hectorvent/floci/services/ses/SmtpRelayTest.java
index d6096d90b0..2f6da65d8b 100644
--- a/src/test/java/io/github/hectorvent/floci/services/ses/SmtpRelayTest.java
+++ b/src/test/java/io/github/hectorvent/floci/services/ses/SmtpRelayTest.java
@@ -1,5 +1,6 @@
package io.github.hectorvent.floci.services.ses;
+import io.github.hectorvent.floci.services.ses.model.MessageHeader;
import io.vertx.core.Future;
import io.vertx.ext.mail.MailClient;
import io.vertx.ext.mail.MailMessage;
@@ -33,7 +34,7 @@ class SmtpRelayTest {
assertFalse(relay.isEnabled());
relay.relay("[email protected]", List.of("[email protected]"),
- null, null, null, "Subject", "text", null);
+ null, null, null, "Subject", "text", null, List.of());
verify(mailClient, never()).sendMail(any(MailMessage.class));
}
@@ -49,7 +50,7 @@ class SmtpRelayTest {
List.of("[email protected]"),
"Test Subject",
"plain text",
- "<p>html</p>");
+ "<p>html</p>", List.of());
ArgumentCaptor<MailMessage> captor = ArgumentCaptor.forClass(MailMessage.class);
verify(mailClient).sendMail(captor.capture());
@@ -70,19 +71,43 @@ class SmtpRelayTest {
SmtpRelay relay = enabledRelay();
relay.relay("[email protected]", List.of("[email protected]"),
- null, null, null, "Subject", "text", null);
+ null, null, null, "Subject", "text", null, List.of());
ArgumentCaptor<MailMessage> captor = ArgumentCaptor.forClass(MailMessage.class);
verify(mailClient).sendMail(captor.capture());
assertNull(captor.getValue().getHeaders());
}
+ @Test
+ void relay_dropsHeadersWithCrlfOrBlankName_preventingInjection() {
+ SmtpRelay relay = enabledRelay();
+
+ relay.relay("[email protected]", List.of("[email protected]"),
+ null, null, null, "Subject", "text", null, List.of(
+ new MessageHeader("X-Safe", "ok"),
+ new MessageHeader("X-Evil", "value\r\nBcc: [email protected]"),
+ new MessageHeader("Injected\r\nBcc", "x"),
+ new MessageHeader("", "no-name")));
+
+ ArgumentCaptor<MailMessage> captor = ArgumentCaptor.forClass(MailMessage.class);
+ verify(mailClient).sendMail(captor.capture());
+ MailMessage sent = captor.getValue();
+
+ assertEquals("ok", sent.getHeaders().get("X-Safe"));
+ // The CR/LF-bearing and blank-name headers are dropped entirely, so no smuggled header
+ // (e.g. Bcc) reaches the relayed message and no header name/value carries a line break.
+ assertFalse(sent.getHeaders().contains("X-Evil"));
+ assertNull(sent.getHeaders().get("Bcc"));
+ assertTrue(sent.getHeaders().names().stream()
+ .noneMatch(n -> n.isBlank() || n.indexOf('\r') >= 0 || n.indexOf('\n') >= 0));
+ }
+
@Test
void relay_textOnly_setsTextWithoutHtml() {
SmtpRelay relay = enabledRelay();
relay.relay("[email protected]", List.of("[email protected]"),
- null, null, null, "Subject", "only text", null);
+ null, null, null, "Subject", "only text", null, List.of());
ArgumentCaptor<MailMessage> captor = ArgumentCaptor.forClass(MailMessage.class);
verify(mailClient).sendMail(captor.capture());
@@ -95,7 +120,7 @@ class SmtpRelayTest {
SmtpRelay relay = enabledRelay();
relay.relay("[email protected]", List.of("[email protected]"),
- null, null, null, "Subject", null, "<b>html</b>");
+ null, null, null, "Subject", null, "<b>html</b>", List.of());
ArgumentCaptor<MailMessage> captor = ArgumentCaptor.forClass(MailMessage.class);
verify(mailClient).sendMail(captor.capture());
@@ -110,7 +135,7 @@ class SmtpRelayTest {
.thenReturn(Future.failedFuture(new RuntimeException("SMTP refused")));
assertDoesNotThrow(() -> relay.relay("[email protected]",
- List.of("[email protected]"), null, null, null, "Subject", "text", null));
+ List.of("[email protected]"), null, null, null, "Subject", "text", null, List.of()));
}
// ── Raw relay ──