feat: Improve Attachment Model with FileAttachment and InlineAttachment (#554)

email/src/main/java/io/micronaut/email/Attachment.java

@@ -15,11 +15,9 @@
  */
 package io.micronaut.email;
 
-import io.micronaut.core.annotation.Creator;
 import io.micronaut.core.annotation.Introspected;
-import org.jspecify.annotations.NonNull;
-import org.jspecify.annotations.Nullable;
-
+import io.micronaut.core.annotation.NonNull;
+import io.micronaut.core.annotation.Nullable;
 import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.NotNull;
 import java.io.DataInputStream;
@@ -56,6 +54,8 @@ public class Attachment {
     @Nullable
     private final String disposition;
 
+    public static final String INLINE = "inline";
+
     /**
      *
      * @param filename filename to show up in email
@@ -131,6 +131,16 @@ public String getId() {
     public String getDisposition() {
         return this.disposition;
     }
+
+    /**
+     * Checks whether this attachment should be treated as inline.
+     *
+     * @return {@code true} if the disposition is {@code "inline"}
+     * @since 3.0.0
+     */
+    public boolean isInline() {
+        return INLINE.equals(disposition);
+    }
 
     /**
      * Attachment's builder.

email/src/main/java/io/micronaut/email/ContentId.java

@@ -0,0 +1,50 @@
+/*
+ * Copyright 2017-2025 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.micronaut.email;
+
+import io.micronaut.core.annotation.NonNull;
+
+import java.util.Objects;
+
+/**
+ * Value type for an RFC 2392 Content-ID, used for inline email attachments.
+ *
+ * Instances represent the identifier part of a Content-ID header (without
+ * surrounding angle brackets). Use {@link #toHeaderValue()} to obtain a header-safe
+ * representation (with < and >).
+ *
+ * @since 3.0.0
+ */
+public record ContentId(@NonNull String value) {
+
+    public ContentId {
+        Objects.requireNonNull(value, "ContentId value must not be null");
+    }
+
+    /**
+     * Returns the formatted header value suitable for use in a Content-ID header.
+     *
+     * For example, a value of {@code "img-1"} will be returned as {@code "<img-1>"}.
+     *
+     * @return the header formatted content id, never {@code null}
+     */
+    @NonNull
+    public String toHeaderValue() {
+        return "<" + value + ">";
+    }
+}
+

email/src/main/java/io/micronaut/email/Email.java

@@ -412,6 +412,45 @@ public Email.Builder attachment(@NonNull Consumer<Attachment.Builder> attachment
             attachment.accept(builder);
             return attachment(builder.build());
         }
+        /**
+         * Attach a FileAttachment in a type-safe way, mapped to Attachment internally.
+         * @param fileAttachment FileAttachment to attach
+         * @return Email Builder
+         */
+        @NonNull
+        public Email.Builder attachment(@NonNull FileAttachment fileAttachment) {
+            if (fileAttachment == null) {
+                throw new IllegalArgumentException("fileAttachment cannot be null");
+            }
+            Attachment attachment = new Attachment(
+                fileAttachment.getFilename(),
+                fileAttachment.getContentType(),
+                fileAttachment.getContent(),
+                null,
+                null
+            );
+            return attachment(attachment);
+        }
+
+        /**
+         * Attach an InlineAttachment in a type-safe way, mapped to Attachment internally.
+         * @param inlineAttachment InlineAttachment to attach
+         * @return Email Builder
+         */
+        @NonNull
+        public Email.Builder attachment(@NonNull InlineAttachment inlineAttachment) {
+            if (inlineAttachment == null) {
+                throw new IllegalArgumentException("inlineAttachment cannot be null");
+            }
+            Attachment attachment = new Attachment(
+                inlineAttachment.getFilename(),
+                inlineAttachment.getContentType(),
+                inlineAttachment.getContent(),
+                inlineAttachment.getContentId() != null ? inlineAttachment.getContentId().value() : null,
+                "inline"
+            );
+            return attachment(attachment);
+        }
 
         /**
          *

email/src/main/java/io/micronaut/email/EmailAttachment.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright 2017-2025 original authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.micronaut.email;
+
+import io.micronaut.core.annotation.NonNull;
+
+/**
+ * Strongly typed email attachment. Use {@link FileAttachment} for regular files,
+ * or {@link InlineAttachment} for embedded inline content.
+ *
+ * @author Vinit Shinde
+ * @since 3.0.0
+ */
+public sealed interface EmailAttachment
+    permits FileAttachment, InlineAttachment {
+
+    /**
+     * The filename as shown in the client's download/save dialogs.
+     *
+     * @return the filename
+     */
+    @NonNull
+    String getFilename();
+
+    /**
+     * The attachment's content as bytes.
+     *
+     * @return the content bytes
+     */
+    @NonNull
+    byte[] getContent();
+
+    /**
+     * The MIME type for the content.
+     *
+     * @return the MIME type
+     */
+    @NonNull
+    String getContentType();
+}
+