Fix email tags, settings, and batch idempotency

Author: bjarn

src/main/java/co/lettermint/client/LettermintClient.java

@@ -92,7 +92,11 @@ public <T> T post(String path, Object payload, Class<T> responseClass, Map<Strin
     }
 
     public <T> T post(String path, Object payload, TypeReference<T> responseType) {
-        return request("POST", url(path, null), payload, null, responseType, null);
+        return post(path, payload, responseType, null);
+    }
+
+    public <T> T post(String path, Object payload, TypeReference<T> responseType, Map<String, String> headers) {
+        return request("POST", url(path, null), payload, null, responseType, headers);
     }
 
     public <T> T get(String path, Class<T> responseClass) {

src/main/java/co/lettermint/endpoints/EmailEndpoint.java

@@ -26,7 +26,8 @@ public class EmailEndpoint extends Endpoint {
     private List<Attachment> attachments;
     private String route;
     private Map<String, Object> metadata;
-    private List<String> tags;
+    private String tag;
+    private Map<String, Object> settings;
     private String idempotencyKey;
 
     public EmailEndpoint(LettermintClient client) {
@@ -50,7 +51,8 @@ private void reset() {
         this.attachments = new ArrayList<>();
         this.route = null;
         this.metadata = new LinkedHashMap<>();
-        this.tags = new ArrayList<>();
+        this.tag = null;
+        this.settings = null;
         this.idempotencyKey = null;
     }
 
@@ -196,10 +198,18 @@ public EmailEndpoint metadata(String key, Object value) {
     }
 
     /**
-     * Add tags to the email.
+     * Set the email tag.
      */
-    public EmailEndpoint tag(String... tags) {
-        this.tags.addAll(Arrays.asList(tags));
+    public EmailEndpoint tag(String tag) {
+        this.tag = tag;
+        return this;
+    }
+
+    /**
+     * Set per-email settings that override the selected route.
+     */
+    public EmailEndpoint settings(Map<String, Object> settings) {
+        this.settings = new LinkedHashMap<>(settings);
         return this;
     }
 
@@ -231,7 +241,17 @@ public SendEmailResponse send() {
     }
 
     public List<SendMailResponse> sendBatch(List<SendMailRequest> payloads) {
-        return client.post("/send/batch", payloads, new TypeReference<List<SendMailResponse>>() {});
+        Map<String, String> requestHeaders = null;
+
+        if (idempotencyKey != null && !idempotencyKey.isEmpty()) {
+            requestHeaders = Collections.singletonMap("Idempotency-Key", idempotencyKey);
+        }
+
+        try {
+            return client.post("/send/batch", payloads, new TypeReference<List<SendMailResponse>>() {}, requestHeaders);
+        } finally {
+            reset();
+        }
     }
 
     public String ping() {
@@ -289,8 +309,12 @@ private Map<String, Object> buildPayload() {
             payload.put("metadata", metadata);
         }
 
-        if (!tags.isEmpty()) {
-            payload.put("tags", tags);
+        if (tag != null) {
+            payload.put("tag", tag);
+        }
+
+        if (settings != null) {
+            payload.put("settings", settings);
         }
 
         return payload;

src/test/java/co/lettermint/ApiClientTest.java

@@ -84,11 +84,13 @@ void sendsBatchEmailsWithTypedPayloads() throws Exception {
 
             List<SendMailResponse> response = Lettermint
                     .email("sending-token", server.url("/v1").toString())
+                    .idempotencyKey("batch-key")
                     .sendBatch(Collections.singletonList(payload));
 
             RecordedRequest request = server.takeRequest();
             assertEquals("/v1/send/batch", request.getPath());
             assertEquals("sending-token", request.getHeader("x-lettermint-token"));
+            assertEquals("batch-key", request.getHeader("Idempotency-Key"));
             assertEquals("msg_123", response.get(0).messageId);
         }
     }

src/test/java/co/lettermint/EmailEndpointTest.java

@@ -63,12 +63,18 @@ void testEmailWithAllOptions() throws Exception {
                 .setHeader("Content-Type", "application/json"));
 
         Map<String, String> headers = new HashMap<>();
-        headers.put("X-Custom-Header", "custom-value");
+        headers.put("Message-ID", "<ticket-123@example.com>");
+        headers.put("X-LM-Preserve-Message-ID", "true");
 
         Map<String, Object> metadata = new HashMap<>();
         metadata.put("userId", "user_123");
         metadata.put("campaign", "welcome");
 
+        Map<String, Object> settings = new HashMap<>();
+        settings.put("track_opens", false);
+        settings.put("track_clicks", true);
+        settings.put("tls", "enforced");
+
         SendEmailResponse response = lettermint.email()
                 .from("John Doe <sender@example.com>")
                 .to("recipient1@example.com", "recipient2@example.com")
@@ -84,7 +90,8 @@ void testEmailWithAllOptions() throws Exception {
                 .attach("invite.ics", "base64icalFile", null, "text/calendar; method=REQUEST")
                 .route("route-slug-123")
                 .metadata(metadata)
-                .tag("welcome", "onboarding")
+                .tag("welcome")
+                .settings(settings)
                 .idempotencyKey("unique-key-123")
                 .send();
 
@@ -103,7 +110,13 @@ void testEmailWithAllOptions() throws Exception {
         assertTrue(body.contains("\"html\":\"<p>Hello <b>World</b></p>\""));
         assertTrue(body.contains("\"text\":\"Hello World\""));
         assertTrue(body.contains("\"route\":\"route-slug-123\""));
-        assertTrue(body.contains("\"tags\":[\"welcome\",\"onboarding\"]"));
+        assertTrue(body.contains("\"tag\":\"welcome\""));
+        assertTrue(body.contains("\"settings\":"));
+        assertTrue(body.contains("\"track_opens\":false"));
+        assertTrue(body.contains("\"track_clicks\":true"));
+        assertTrue(body.contains("\"tls\":\"enforced\""));
+        assertTrue(body.contains("\"Message-ID\":\"<ticket-123@example.com>\""));
+        assertTrue(body.contains("\"X-LM-Preserve-Message-ID\":\"true\""));
         assertTrue(body.contains("{\"filename\":\"document.pdf\",\"content\":\"base64content\"}"));
         assertTrue(body.contains("{\"filename\":\"logo.png\",\"content\":\"base64logo\",\"content_id\":\"logo-cid\"}"));
         assertTrue(body.contains("{\"filename\":\"invite.ics\",\"content\":\"base64icalFile\",\"content_type\":\"text/calendar; method=REQUEST\"}"));