add inline attachment support

Author: J0nasMayr

readme.md

@@ -20,6 +20,29 @@ Add the mailer service to the classpath by adding the following maven dependency
 If you want to use attachments, you will have to create a bean implementing this interface: [AttachmentDataSource.java](src%2Fmain%2Fjava%2Fit%2Faboutbits%2Fspringboot%2Femailservice%2Flib%2FAttachmentDataSource.java)  
 This step is optional.
 
+#### Inline (CID) attachments
+
+To embed an attachment inline, set a `contentId` on the attachment and reference it in the `htmlBody` via the `cid:` scheme.
+This is the equivalent of `MimeMessageHelper.addInline(...)` and renders in all major email clients.
+
+```java
+// @formatter:off
+EmailParameter.Email.builder()
+        // ...
+        .htmlBody("<img src=\"cid:header-logo\"><h1>Hello!</h1>")
+        .attachment(EmailParameter.Email.Attachment.builder()
+                .contentId("header-logo")
+                .fileName("logo.png")
+                .contentType("image/png")
+                .payload(new ClassPathResource("/templates/mail/images/logo.png").getInputStream())
+                .build())
+        .build();
+// @formatter:on
+```
+
+Attachments without a `contentId` are added as regular attachments. Each `contentId` must be referenced in the
+`htmlBody` as `cid:contentId`, otherwise validation fails.
+
 ## Usage
 
 ### Sending an Email

src/main/java/it/aboutbits/springboot/emailservice/lib/EmailAttachmentDto.java

@@ -2,6 +2,7 @@
 
 import it.aboutbits.springboot.emailservice.lib.model.Email;
 import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
 
 @NullMarked
 public record EmailAttachmentDto(
@@ -13,6 +14,9 @@ public record EmailAttachmentDto(
 
         String contentType,
 
+        @Nullable
+        String contentId,
+
         long fileReference
 ) {
 }

src/main/java/it/aboutbits/springboot/emailservice/lib/application/EmailParameter.java

@@ -1,5 +1,7 @@
 package it.aboutbits.springboot.emailservice.lib.application;
 
+import jakarta.validation.Valid;
+import jakarta.validation.constraints.AssertTrue;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotEmpty;
 import lombok.Builder;
@@ -10,12 +12,14 @@
 import java.io.InputStream;
 import java.time.OffsetDateTime;
 import java.util.List;
+import java.util.Objects;
 import java.util.Set;
 
 @Builder
 @NullMarked
 public record EmailParameter(
         OffsetDateTime scheduledAt,
+        @Valid
         Email email
 ) {
     @Builder
@@ -41,15 +45,27 @@ public record Email(
             String replyToName,
 
             @Singular
+            @Valid
             Set<Attachment> attachments
     ) {
+        @AssertTrue(message = "each inline attachment contentId must be referenced in the htmlBody as cid:contentId")
+        public boolean isInlineAttachmentsValid() {
+            return attachments.stream()
+                    .map(Attachment::contentId)
+                    .filter(Objects::nonNull)
+                    .allMatch(contentId -> htmlBody.contains("cid:" + contentId));
+        }
+
         @Builder
         public record Attachment(
                 InputStream payload,
                 @NotBlank
                 String fileName,
                 @NotBlank
-                String contentType
+                String contentType,
+                // if set, the attachment is embedded inline and can be referenced in the htmlBody as "cid:contentId"
+                @Nullable
+                String contentId
         ) {
         }
     }

src/main/java/it/aboutbits/springboot/emailservice/lib/application/EmailServiceMigrator.java

@@ -76,6 +76,8 @@ updated_at           timestamp with time zone default now()           not null,
 
                  alter table email_service_emails add column if not exists cleanup_start_time timestamp with time zone;
 
+                 alter table email_service_email_attachments add column if not exists content_id text;
+
                  update email_service_emails
                     set execution_end_time = sent_at
                   where sent_at is not null

src/main/java/it/aboutbits/springboot/emailservice/lib/application/ManageEmail.java

@@ -209,9 +209,17 @@ private void sendMail(
         }
 
         for (var attachment : attachments) {
-            var payload = attachmentDataSource.getAttachmentPayload(attachment.getFileReference());
-            helper.addAttachment(attachment.getFileName(), new ByteArrayResource(payload.readAllBytes()));
-            payload.close();
+            ByteArrayResource resource;
+            try (var payload = attachmentDataSource.getAttachmentPayload(attachment.getFileReference())) {
+                resource = new ByteArrayResource(payload.readAllBytes());
+            }
+
+            var contentId = attachment.getContentId();
+            if (contentId != null) {
+                helper.addInline(contentId, resource, attachment.getContentType());
+            } else {
+                helper.addAttachment(attachment.getFileName(), resource);
+            }
         }
 
         mailSender.send(message);
@@ -241,6 +249,7 @@ private Email fromParameter(EmailParameter parameter) throws AttachmentException
             var emailAttachment = new EmailAttachment();
             emailAttachment.setEmail(email);
             emailAttachment.setContentType(attachment.contentType());
+            emailAttachment.setContentId(attachment.contentId());
             emailAttachment.setFileName(attachment.fileName());
             emailAttachment.setFileReference(reference);
 

src/main/java/it/aboutbits/springboot/emailservice/lib/model/EmailAttachment.java

@@ -29,5 +29,7 @@ public class EmailAttachment {
 
     private String contentType;
 
+    private String contentId;
+
     private long fileReference;
 }