Improve Attachment Model (Clear Separation of Regular vs. Inline Attachments)

[daniel-muhra-cw]

Feature description

Summary

Micronaut Email currently exposes attachments through a very low-level, MIME-centric model. Inline attachments and regular attachments are treated identically, and developers must manually work with MIME content dispositions (e.g., "inline", "attachment"). This leaks implementation details and forces API users to deal with concepts that should be abstracted away.

I would like to propose a more expressive, type-safe attachment model with a clear distinction between regular attachments and inline attachments, without requiring the user to manage MIME content dispositions directly.

---

Problem Description

Micronaut Email exposes attachments using a universal Attachment type. This type:

• does not distinguish between regular and inline attachments,
• requires developers to manually set Content-Disposition,
• exposes string-based MIME values without helpers or constants,
• requires users to know that "inline" is a special MIME disposition needed for embedding images in HTML emails.

This is problematic because:

1. It leaks MIME implementation details
   Users of Micronaut Email should not have to know the MIME specification or specific keywords like "inline".

2. It increases the risk of user error
   Developers may forget to set the correct content disposition or set it incorrectly.

3. The API is not expressive
   A single universal attachment type does not convey intent. Inline content and file attachments serve different purposes.

4. It lacks type-safety and convenience helpers
   Everything relies on raw strings, which makes the API fragile.

---

Proposed Solution

Introduce a more expressive attachment model with clear semantics. For example:

// Factory methods (static or provided via a builder)
EmailAttachment inline(String contentId, byte[] data, MediaType mediaType);
EmailAttachment attachment(String filename, byte[] data, MediaType mediaType);

Next steps would be to discuss how to ensure backwards compatibility while also encouraging to migrate to the new approach (probably by deprecating existing methods).

[Vin-it-9]

I’m working on this issue and will open a PR soon, ensuring backward compatibility and introducing a clean separation of concerns between inline and regular attachments.