lots of improvements

shared/lib/Mail/Object/Address.php

@@ -0,0 +1,127 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+/**
+ * Address Implementation
+ * 
+ * @since 2025.05.01
+ */
+class Address implements AddressInterface {
+
+    /**
+     * @param string $address Email address
+     * @param string|null $name Display name
+     */
+    public function __construct(
+        private string $address = '',
+        private ?string $name = null,
+    ) {}
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return array_filter([
+            self::JSON_PROPERTY_ADDRESS => $this->address,
+            self::JSON_PROPERTY_LABEL => $this->name,
+        ], fn($v) => $v !== null && $v !== '');
+    }
+
+    /**
+     * Creates an Address from a formatted string
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $value Formatted as "Name <address>" or just "address"
+     * 
+     * @return self
+     */
+    public static function fromString(string $value): self {
+        $value = trim($value);
+        
+        // Match "Name <address>" format
+        if (preg_match('/^(.+?)\s*<([^>]+)>$/', $value, $matches)) {
+            return new self(trim($matches[2]), trim($matches[1], ' "\''));
+        }
+        
+        // Match "<address>" format
+        if (preg_match('/^<([^>]+)>$/', $value, $matches)) {
+            return new self(trim($matches[1]));
+        }
+        
+        // Assume plain address
+        return new self($value);
+    }
+
+    /**
+     * Creates an Address from an array
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data Array with 'address' and optional 'name' keys
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        return new self(
+            $data[self::JSON_PROPERTY_ADDRESS] ?? $data['address'] ?? '',
+            $data[self::JSON_PROPERTY_LABEL] ?? $data['name'] ?? null,
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getAddress(): string {
+        return $this->address;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setAddress(string $address): static {
+        $this->address = $address;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getLabel(): ?string {
+        return $this->name;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setLabel(?string $label): static {
+        $this->name = $label;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function toString(): string {
+        if ($this->name !== null && $this->name !== '') {
+            return sprintf('"%s" <%s>', $this->name, $this->address);
+        }
+        return $this->address;
+    }
+
+    /**
+     * String representation
+     */
+    public function __toString(): string {
+        return $this->toString();
+    }
+
+}

shared/lib/Mail/Object/AddressInterface.php

@@ -0,0 +1,63 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+use KTXF\Json\JsonSerializable;
+
+/**
+ * Address Interface
+ * 
+ * Represents an email address with optional display name.
+ * 
+ * @since 2025.05.01
+ */
+interface AddressInterface extends JsonSerializable {
+
+    public const JSON_PROPERTY_ADDRESS = 'address';
+    public const JSON_PROPERTY_LABEL = 'label';
+
+    /**
+     * Gets the email address
+     *
+     * @since 2025.05.01
+     */
+    public function getAddress(): string;
+
+    /**
+     * Sets the email address
+     *
+     * @since 2025.05.01
+     */
+    public function setAddress(string $value): static;
+
+    /**
+     * Gets the display name
+     *
+     * @since 2025.05.01
+     */
+    public function getLabel(): ?string;
+
+    /**
+     * Sets the display name
+     *
+     * @since 2025.05.01
+     */
+    public function setLabel(?string $value): static;
+
+    /**
+     * Gets the formatted address string
+     *
+     * @since 2025.05.01
+     *
+     * @return string Formatted as "Name <address>" or just "address" if no name
+     */
+    public function toString(): string;
+
+}

shared/lib/Mail/Object/Attachment.php

@@ -0,0 +1,194 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+/**
+ * Attachment Implementation
+ * 
+ * @since 2025.05.01
+ */
+class Attachment implements AttachmentInterface {
+
+    /**
+     * @param string $name File name
+     * @param string $mimeType MIME type
+     * @param string $content Binary content
+     * @param string|null $id Attachment ID
+     * @param int|null $size Size in bytes
+     * @param string|null $contentId Content-ID for inline attachments
+     * @param bool $inline Whether inline attachment
+     */
+    public function __construct(
+        private string $name,
+        private string $mimeType,
+        private string $content,
+        private ?string $id = null,
+        private ?int $size = null,
+        private ?string $contentId = null,
+        private bool $inline = false,
+    ) {
+        if ($this->size === null) {
+            $this->size = strlen($this->content);
+        }
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return array_filter([
+            self::JSON_PROPERTY_ID => $this->id,
+            self::JSON_PROPERTY_NAME => $this->name,
+            self::JSON_PROPERTY_MIME_TYPE => $this->mimeType,
+            self::JSON_PROPERTY_SIZE => $this->size,
+            self::JSON_PROPERTY_CONTENT_ID => $this->contentId,
+            self::JSON_PROPERTY_INLINE => $this->inline ?: null,
+            'contentBase64' => $this->getContentBase64(),
+        ], fn($v) => $v !== null);
+    }
+
+    
+    /**
+     * Creates an attachment from a file path
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $path File path
+     * @param string|null $name Override file name
+     * @param string|null $mimeType Override MIME type
+     * 
+     * @return self
+     */
+    public static function fromFile(string $path, ?string $name = null, ?string $mimeType = null): self {
+        $content = file_get_contents($path);
+        $name = $name ?? basename($path);
+        $mimeType = $mimeType ?? mime_content_type($path) ?: 'application/octet-stream';
+        
+        return new self($name, $mimeType, $content);
+    }
+
+    /**
+     * Creates an attachment from base64 encoded content
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $name File name
+     * @param string $mimeType MIME type
+     * @param string $base64Content Base64 encoded content
+     * 
+     * @return self
+     */
+    public static function fromBase64(string $name, string $mimeType, string $base64Content): self {
+        return new self($name, $mimeType, base64_decode($base64Content));
+    }
+
+    /**
+     * Creates an inline attachment for embedding in HTML
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $name File name
+     * @param string $mimeType MIME type
+     * @param string $content Binary content
+     * @param string $contentId Content-ID (without cid: prefix)
+     * 
+     * @return self
+     */
+    public static function inline(string $name, string $mimeType, string $content, string $contentId): self {
+        return new self($name, $mimeType, $content, null, null, $contentId, true);
+    }
+
+    /**
+     * Creates from array data
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        $content = $data['content'] ?? '';
+        if (isset($data['contentBase64'])) {
+            $content = base64_decode($data['contentBase64']);
+        }
+        
+        return new self(
+            $data[self::JSON_PROPERTY_NAME] ?? $data['name'] ?? '',
+            $data[self::JSON_PROPERTY_MIME_TYPE] ?? $data['mimeType'] ?? 'application/octet-stream',
+            $content,
+            $data[self::JSON_PROPERTY_ID] ?? $data['id'] ?? null,
+            $data[self::JSON_PROPERTY_SIZE] ?? $data['size'] ?? null,
+            $data[self::JSON_PROPERTY_CONTENT_ID] ?? $data['contentId'] ?? null,
+            $data[self::JSON_PROPERTY_INLINE] ?? $data['inline'] ?? false,
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getId(): ?string {
+        return $this->id;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getName(): string {
+        return $this->name;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getMimeType(): string {
+        return $this->mimeType;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getSize(): ?int {
+        return $this->size;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getContentId(): ?string {
+        return $this->contentId;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function isInline(): bool {
+        return $this->inline;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getContent(): string {
+        return $this->content;
+    }
+
+    /**
+     * Gets the content as base64 encoded string
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getContentBase64(): string {
+        return base64_encode($this->content);
+    }
+
+}

shared/lib/Mail/Object/AttachmentInterface.php

@@ -0,0 +1,93 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+use KTXF\Json\JsonSerializable;
+
+/**
+ * Attachment Interface
+ * 
+ * Represents a file attachment on a mail message.
+ * 
+ * @since 2025.05.01
+ */
+interface AttachmentInterface extends JsonSerializable {
+
+    public const JSON_PROPERTY_ID = 'id';
+    public const JSON_PROPERTY_NAME = 'name';
+    public const JSON_PROPERTY_MIME_TYPE = 'mimeType';
+    public const JSON_PROPERTY_SIZE = 'size';
+    public const JSON_PROPERTY_CONTENT_ID = 'contentId';
+    public const JSON_PROPERTY_INLINE = 'inline';
+
+    /**
+     * Gets the attachment identifier
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null Attachment ID or null for new attachments
+     */
+    public function getId(): ?string;
+
+    /**
+     * Gets the file name
+     *
+     * @since 2025.05.01
+     *
+     * @return string File name (e.g., "document.pdf")
+     */
+    public function getName(): string;
+
+    /**
+     * Gets the MIME type
+     *
+     * @since 2025.05.01
+     *
+     * @return string MIME type (e.g., "application/pdf")
+     */
+    public function getMimeType(): string;
+
+    /**
+     * Gets the file size in bytes
+     *
+     * @since 2025.05.01
+     *
+     * @return int|null Size in bytes or null if unknown
+     */
+    public function getSize(): ?int;
+
+    /**
+     * Gets the Content-ID for inline attachments
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null Content-ID for referencing in HTML body (e.g., "cid:image1")
+     */
+    public function getContentId(): ?string;
+
+    /**
+     * Checks if this is an inline attachment (embedded in body)
+     *
+     * @since 2025.05.01
+     *
+     * @return bool True if inline, false if regular attachment
+     */
+    public function isInline(): bool;
+
+    /**
+     * Gets the attachment content
+     *
+     * @since 2025.05.01
+     *
+     * @return string Binary content of the attachment
+     */
+    public function getContent(): string;
+
+}

shared/lib/Mail/Object/MessagePartBaseAbstract.php

@@ -0,0 +1,122 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+/**
+ * Abstract Message Part Base Class
+ * 
+ * Provides common implementation for message parts (read-only)
+ * 
+ * @since 2025.05.01
+ */
+abstract class MessagePartBaseAbstract implements MessagePartInterface {
+
+    /**
+     * Internal data storage
+     */
+    protected array $data = [];
+
+    /**
+     * Sub-parts storage
+     * @var array<int,MessagePartInterface>
+     */
+    protected array $parts = [];
+
+    /**
+     * Constructor
+     * 
+     * @param array &$data Reference to data array
+     */
+    public function __construct(array &$data = null) {
+        if ($data === null) {
+            $data = [];
+        }
+        $this->data = &$data;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBlobId(): ?string {
+        return $this->data['blobId'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getId(): ?string {
+        return $this->data['partId'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getType(): ?string {
+        return $this->data['type'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getDisposition(): ?string {
+        return $this->data['disposition'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getName(): ?string {
+        return $this->data['name'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getCharset(): ?string {
+        return $this->data['charset'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getLanguage(): ?string {
+        return $this->data['language'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getLocation(): ?string {
+        return $this->data['location'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getParts(): array {
+        return $this->parts;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        $result = $this->data;
+        
+        if (!empty($this->parts)) {
+            $result['subParts'] = [];
+            foreach ($this->parts as $part) {
+                $result['subParts'][] = $part->jsonSerialize();
+            }
+        }
+        
+        return $result;
+    }
+}

shared/lib/Mail/Object/MessagePartInterface.php

@@ -0,0 +1,104 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+use KTXF\Json\JsonSerializable;
+
+/**
+ * Message Part Interface
+ * 
+ * Represents a MIME part of a message (body, attachment, etc.)
+ * 
+ * @since 2025.05.01
+ */
+interface MessagePartInterface extends JsonSerializable {
+
+    /**
+     * Gets the blob identifier
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getBlobId(): ?string;
+
+    /**
+     * Gets the part identifier
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getId(): ?string;
+
+    /**
+     * Gets the MIME type
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getType(): ?string;
+
+    /**
+     * Gets the content disposition (inline, attachment)
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getDisposition(): ?string;
+
+    /**
+     * Gets the part name
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getName(): ?string;
+
+    /**
+     * Gets the character set
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getCharset(): ?string;
+
+    /**
+     * Gets the language
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getLanguage(): ?string;
+
+    /**
+     * Gets the location
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getLocation(): ?string;
+
+    /**
+     * Gets the sub-parts
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int,MessagePartInterface>
+     */
+    public function getParts(): array;
+
+}

shared/lib/Mail/Object/MessagePartMutableAbstract.php

@@ -0,0 +1,146 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+/**
+ * Abstract Message Part Mutable Class
+ * 
+ * Provides common implementation for mutable message parts
+ * 
+ * @since 2025.05.01
+ */
+abstract class MessagePartMutableAbstract extends MessagePartBaseAbstract {
+
+    /**
+     * Sets the blob identifier
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setBlobId(string $value): static {
+        $this->data['blobId'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the part identifier
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setId(string $value): static {
+        $this->data['partId'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the MIME type
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setType(string $value): static {
+        $this->data['type'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the content disposition
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setDisposition(string $value): static {
+        $this->data['disposition'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the part name
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setName(string $value): static {
+        $this->data['name'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the character set
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setCharset(string $value): static {
+        $this->data['charset'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the language
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setLanguage(string $value): static {
+        $this->data['language'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the location
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setLocation(string $value): static {
+        $this->data['location'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the sub-parts
+     *
+     * @since 2025.05.01
+     *
+     * @param MessagePartInterface ...$value
+     *
+     * @return static
+     */
+    public function setParts(MessagePartInterface ...$value): static {
+        $this->parts = $value;
+        return $this;
+    }
+}

shared/lib/Mail/Object/MessagePropertiesBaseAbstract.php

@@ -0,0 +1,400 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+use DateTimeImmutable;
+use KTXF\Resource\Provider\Node\NodePropertiesBaseAbstract;
+
+/**
+ * Abstract Message Properties Base Class
+ * 
+ * Provides common implementation for message properties (read-only)
+ * 
+ * @since 2025.05.01
+ */
+abstract class MessagePropertiesBaseAbstract extends NodePropertiesBaseAbstract implements MessagePropertiesBaseInterface {
+
+    public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
+
+    /**
+     * @inheritDoc
+     */
+    public function version(): int {
+        return $this->data['version'] ?? 1;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getHeaders(): array {
+        return $this->data['headers'] ?? [];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getHeader(string $name): string|array|null {
+        return $this->data['headers'][$name] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getUrid(): ?string {
+        return $this->data['urid'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getCreated(): ?DateTimeImmutable {
+        return $this->data['created'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getModified(): ?DateTimeImmutable {
+        return $this->data['modified'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getDate(): ?DateTimeImmutable {
+        return $this->data['date'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getReceived(): ?DateTimeImmutable {
+        return $this->data['received'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getSize(): ?int {
+        return $this->data['size'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getSender(): ?AddressInterface {
+        return $this->data['sender'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getFrom(): ?AddressInterface {
+        return $this->data['from'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getReplyTo(): array {
+        return $this->data['replyTo'] ?? [];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getTo(): array {
+        return $this->data['to'] ?? [];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getCc(): array {
+        return $this->data['cc'] ?? [];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBcc(): array {
+        return $this->data['bcc'] ?? [];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getInReplyTo(): ?string {
+        return $this->data['inReplyTo'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getReferences(): array {
+        return $this->data['references'] ?? [];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getSubject(): string {
+        return $this->data['subject'] ?? '';
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getSnippet(): ?string {
+        return $this->data['snippet'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBodyText(): ?string {
+        return $this->data['bodyText'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBodyTextCharset(): ?string {
+        return $this->data['bodyTextCharset'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBodyTextSize(): ?int {
+        return $this->data['bodyTextSize'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBodyHtml(): ?string {
+        return $this->data['bodyHtml'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBodyHtmlCharset(): ?string {
+        return $this->data['bodyHtmlCharset'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBodyHtmlSize(): ?int {
+        return $this->data['bodyHtmlSize'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getAttachments(): array {
+        return $this->data['attachments'] ?? [];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getFlags(): array {
+        return $this->data['flags'] ?? [
+            'read' => false,
+            'starred' => false,
+            'important' => false,
+            'answered' => false,
+            'forwarded' => false,
+            'draft' => false,
+            'deleted' => false,
+            'flagged' => false,
+        ];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getFlag(string $name): bool {
+        return $this->data['flags'][$name] ?? false;
+    }
+
+    /**
+     * Gets message labels
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int, string>
+     */
+    public function getLabels(): array {
+        return $this->data['labels'] ?? [];
+    }
+
+    /**
+     * Gets message tags
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int, string>
+     */
+    public function getTags(): array {
+        return $this->data['tags'] ?? [];
+    }
+
+    /**
+     * Gets message priority
+     *
+     * @since 2025.05.01
+     *
+     * @return string
+     */
+    public function getPriority(): string {
+        return $this->data['priority'] ?? 'normal';
+    }
+
+    /**
+     * Gets message sensitivity
+     *
+     * @since 2025.05.01
+     *
+     * @return string
+     */
+    public function getSensitivity(): string {
+        return $this->data['sensitivity'] ?? 'normal';
+    }
+
+    /**
+     * Gets encryption information
+     *
+     * @since 2025.05.01
+     *
+     * @return array{method: string|null, signed: bool, encrypted: bool}
+     */
+    public function getEncryption(): array {
+        return $this->data['encryption'] ?? [
+            'method' => null,
+            'signed' => false,
+            'encrypted' => false,
+        ];
+    }
+
+    /**
+     * Checks if delivery receipt is requested
+     *
+     * @since 2025.05.01
+     *
+     * @return bool
+     */
+    public function isDeliveryReceipt(): bool {
+        return $this->data['deliveryReceipt'] ?? false;
+    }
+
+    /**
+     * Checks if read receipt is requested
+     *
+     * @since 2025.05.01
+     *
+     * @return bool
+     */
+    public function isReadReceipt(): bool {
+        return $this->data['readReceipt'] ?? false;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function hasRecipients(): bool {
+        return !empty($this->data['to']) || !empty($this->data['cc']) || !empty($this->data['bcc']);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function hasBody(): bool {
+        return ($this->data['bodyText'] !== null && $this->data['bodyText'] !== '') 
+            || ($this->data['bodyHtml'] !== null && $this->data['bodyHtml'] !== '');
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBody(): ?MessagePartInterface {
+        return $this->data['body'] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        $data = [
+            self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
+            self::JSON_PROPERTY_VERSION => $this->data['version'] ?? 1,
+        ];
+        
+        if (!empty($this->data['headers'])) {
+            $data[self::JSON_PROPERTY_HEADERS] = $this->data['headers'];
+        }
+        if (isset($this->data['urid']) && $this->data['urid'] !== null) {
+            $data[self::JSON_PROPERTY_URID] = $this->data['urid'];
+        }
+        if (isset($this->data['date']) && $this->data['date'] !== null) {
+            $data[self::JSON_PROPERTY_DATE] = $this->data['date'] instanceof DateTimeImmutable 
+                ? $this->data['date']->format('c') 
+                : $this->data['date'];
+        }
+        if (isset($this->data['received']) && $this->data['received'] !== null) {
+            $data[self::JSON_PROPERTY_RECEIVED] = $this->data['received'] instanceof DateTimeImmutable 
+                ? $this->data['received']->format('c') 
+                : $this->data['received'];
+        }
+        if (isset($this->data['size']) && $this->data['size'] !== null) {
+            $data[self::JSON_PROPERTY_SIZE] = $this->data['size'];
+        }
+        if (isset($this->data['sender']) && $this->data['sender'] !== null) {
+            $data[self::JSON_PROPERTY_SENDER] = $this->data['sender'];
+        }
+        if (isset($this->data['from']) && $this->data['from'] !== null) {
+            $data[self::JSON_PROPERTY_FROM] = $this->data['from'];
+        }
+        if (!empty($this->data['replyTo'])) {
+            $data[self::JSON_PROPERTY_REPLY_TO] = $this->data['replyTo'];
+        }
+        if (!empty($this->data['to'])) {
+            $data[self::JSON_PROPERTY_TO] = $this->data['to'];
+        }
+        if (!empty($this->data['cc'])) {
+            $data[self::JSON_PROPERTY_CC] = $this->data['cc'];
+        }
+        if (!empty($this->data['bcc'])) {
+            $data[self::JSON_PROPERTY_BCC] = $this->data['bcc'];
+        }
+        if (isset($this->data['inReplyTo']) && $this->data['inReplyTo'] !== null) {
+            $data[self::JSON_PROPERTY_IN_REPLY_TO] = $this->data['inReplyTo'];
+        }
+        if (!empty($this->data['references'])) {
+            $data[self::JSON_PROPERTY_REFERENCES] = $this->data['references'];
+        }
+        
+        if (isset($this->data['snippet']) && $this->data['snippet'] !== null) {
+            $data[self::JSON_PROPERTY_SNIPPET] = $this->data['snippet'];
+        }
+        
+        if (!empty($this->data['attachments'])) {
+            $data[self::JSON_PROPERTY_ATTACHMENTS] = $this->data['attachments'];
+        }
+
+        $data[self::JSON_PROPERTY_SUBJECT] = $this->data['subject'] ?? null;
+        $data[self::JSON_PROPERTY_BODY] = $this->data['body'] ?? null;
+        
+        return $data;
+    }
+}

shared/lib/Mail/Object/MessagePropertiesBaseInterface.php

@@ -0,0 +1,252 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+use DateTimeImmutable;
+use KTXF\Resource\Provider\Node\NodePropertiesBaseInterface;
+
+/**
+ * Message Properties Base Interface
+ * 
+ * @since 2025.05.01
+ */
+interface MessagePropertiesBaseInterface extends NodePropertiesBaseInterface {
+
+    public const JSON_TYPE = 'mail.message';
+    public const JSON_PROPERTY_HEADERS = 'headers';
+    public const JSON_PROPERTY_URID = 'urid';
+    public const JSON_PROPERTY_DATE = 'date';
+    public const JSON_PROPERTY_RECEIVED = 'received';
+    public const JSON_PROPERTY_SIZE = 'size';
+    public const JSON_PROPERTY_SENDER = 'sender';
+    public const JSON_PROPERTY_FROM = 'from';
+    public const JSON_PROPERTY_REPLY_TO = 'replyTo';
+    public const JSON_PROPERTY_TO = 'to';
+    public const JSON_PROPERTY_CC = 'cc';
+    public const JSON_PROPERTY_BCC = 'bcc';
+    public const JSON_PROPERTY_IN_REPLY_TO = 'inReplyTo';
+    public const JSON_PROPERTY_REFERENCES = 'references';
+    public const JSON_PROPERTY_SUBJECT = 'subject';
+    public const JSON_PROPERTY_SNIPPET = 'snippet';
+    public const JSON_PROPERTY_BODY = 'body';
+    public const JSON_PROPERTY_ATTACHMENTS = 'attachments';
+    public const JSON_PROPERTY_TAGS = 'tags';
+
+    /**
+     * Gets custom headers
+     *
+     * @since 2025.05.01
+     *
+     * @return array<string,string> Header name => value
+     */
+    public function getHeaders(): array;
+
+    /**
+     * Gets a specific header value
+     *
+     * @since 2025.05.01
+     *
+     * @param string $name Header name
+     *
+     * @return string|array<int,string>|null Header value(s) or null if not set
+     */
+    public function getHeader(string $name): string|array|null;
+
+    /**
+     * Gets the universal resource identifier (URN)
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getUrid(): ?string;
+
+    /**
+     * Gets the message date
+     *
+     * @since 2025.05.01
+     *
+     * @return DateTimeImmutable|null
+     */
+    public function getDate(): ?DateTimeImmutable;
+
+    /**
+     * Gets the received date
+     *
+     * @since 2025.05.01
+     *
+     * @return DateTimeImmutable|null
+     */
+    public function getReceived(): ?DateTimeImmutable;
+
+    /**
+     * Gets the message size in bytes
+     *
+     * @since 2025.05.01
+     *
+     * @return int|null
+     */
+    public function getSize(): ?int;
+
+    /**
+     * Gets the sender address (actual sender, may differ from From)
+     *
+     * @since 2025.05.01
+     *
+     * @return AddressInterface|null
+     */
+    public function getSender(): ?AddressInterface;
+
+    /**
+     * Gets the sender address
+     *
+     * @since 2025.05.01
+     *
+     * @return AddressInterface|null
+     */
+    public function getFrom(): ?AddressInterface;
+    /**
+     * Gets the reply-to addresses
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int,AddressInterface>
+     */
+    public function getReplyTo(): array;
+
+    /**
+     * Gets the primary recipients (To)
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int,AddressInterface>
+     */
+    public function getTo(): array;
+
+    /**
+     * Gets the carbon copy recipients (CC)
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int,AddressInterface>
+     */
+    public function getCc(): array;
+
+    /**
+     * Gets the blind carbon copy recipients (BCC)
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int,AddressInterface>
+     */
+    public function getBcc(): array;
+
+    /**
+     * Gets the message ID this is replying to
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getInReplyTo(): ?string;
+
+    /**
+     * Gets the references (message IDs in thread)
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int,string>
+     */
+    public function getReferences(): array;
+
+    /**
+     * Gets the message subject
+     *
+     * @since 2025.05.01
+     *
+     * @return string
+     */
+    public function getSubject(): string;
+
+    /**
+     * Gets the message snippet/preview
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getSnippet(): ?string;
+
+    /**
+     * Checks if the message has any body content
+     *
+     * @since 2025.05.01
+     *
+     * @return bool True if text or HTML body is set
+     */
+    public function hasBody(): bool;
+
+    /**
+     * Gets the message body structure
+     *
+     * @since 2025.05.01
+     *
+     * @return MessagePartInterface|null The body structure or null if no body
+     */
+    public function getBody(): ?MessagePartInterface;
+
+    /**
+     * Gets the plain text body content
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getBodyText(): ?string;
+
+    /**
+     * Gets the HTML body content
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getBodyHtml(): ?string;
+
+    /**
+     * Gets the attachments
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int,AttachmentInterface>
+     */
+    public function getAttachments(): array;
+
+    /**
+     * Gets message flags
+     *
+     * @since 2025.05.01
+     *
+     * @return array{read:bool,starred:bool,important:bool,answered:bool,forwarded:bool,draft:bool,deleted:bool,flagged:bool}
+     */
+    public function getFlags(): array;
+
+    /**
+     * Gets a specific flag value
+     *
+     * @since 2025.05.01
+     *
+     * @param string $name Flag name (read, starred, important, answered, forwarded, draft, deleted, flagged)
+     *
+     * @return bool
+     */
+    public function getFlag(string $name): bool;
+
+}

shared/lib/Mail/Object/MessagePropertiesMutableAbstract.php

@@ -0,0 +1,455 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+use DateTimeImmutable;
+
+/**
+ * Abstract Message Properties Mutable Class
+ * 
+ * Provides common implementation for mutable message properties
+ * 
+ * @since 2025.05.01
+ */
+abstract class MessagePropertiesMutableAbstract extends MessagePropertiesBaseAbstract implements MessagePropertiesMutableInterface {
+
+    public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
+    
+    /**
+     * @inheritDoc
+     */
+    public function setHeaders(array $value): static {
+        $this->data['headers'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setHeader(string $name, string|array $value): static {
+        $this->data['headers'][$name] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setUrid(?string $value): static {
+        $this->data['urid'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setCreated(DateTimeImmutable $value): static {
+        $this->data['created'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setModified(DateTimeImmutable $value): static {
+        $this->data['modified'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setDate(DateTimeImmutable $value): static {
+        $this->data['date'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setReceived(?DateTimeImmutable $value): static {
+        $this->data['received'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setSize(?int $value): static {
+        $this->data['size'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setSender(?AddressInterface $value): static {
+        $this->data['sender'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setFrom(AddressInterface $value): static {
+        $this->data['from'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setReplyTo(AddressInterface ...$value): static {
+        $this->data['replyTo'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setTo(AddressInterface ...$value): static {
+        $this->data['to'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setCc(AddressInterface ...$value): static {
+        $this->data['cc'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setBcc(AddressInterface ...$value): static {
+        $this->data['bcc'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setInReplyTo(?string $value): static {
+        $this->data['inReplyTo'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setReferences(string ...$value): static {
+        $this->data['references'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setSubject(string $value): static {
+        $this->data['subject'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setSnippet(?string $value): static {
+        $this->data['snippet'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setBodyText(?string $value): static {
+        $this->data['bodyText'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the plain text body charset
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setBodyTextCharset(string $value): static {
+        $this->data['bodyTextCharset'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the plain text body size
+     *
+     * @since 2025.05.01
+     *
+     * @param int $value
+     *
+     * @return static
+     */
+    public function setBodyTextSize(int $value): static {
+        $this->data['bodyTextSize'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setBodyHtml(?string $value): static {
+        $this->data['bodyHtml'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the HTML body charset
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setBodyHtmlCharset(string $value): static {
+        $this->data['bodyHtmlCharset'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets the HTML body size
+     *
+     * @since 2025.05.01
+     *
+     * @param int $value
+     *
+     * @return static
+     */
+    public function setBodyHtmlSize(int $value): static {
+        $this->data['bodyHtmlSize'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setAttachments(AttachmentInterface ...$value): static {
+        $this->data['attachments'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function addAttachment(AttachmentInterface $value): static {
+        $this->data['attachments'][] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets message flags
+     *
+     * @since 2025.05.01
+     *
+     * @param array $value
+     *
+     * @return static
+     */
+    public function setFlags(array $value): static {
+        if (!isset($this->data['flags'])) {
+            $this->data['flags'] = [
+                'read' => false,
+                'starred' => false,
+                'important' => false,
+                'answered' => false,
+                'forwarded' => false,
+                'draft' => false,
+                'deleted' => false,
+                'flagged' => false,
+            ];
+        }
+        $this->data['flags'] = array_merge($this->data['flags'], $value);
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setFlag(string $name, bool $value): static {
+        if (!isset($this->data['flags'])) {
+            $this->data['flags'] = [
+                'read' => false,
+                'starred' => false,
+                'important' => false,
+                'answered' => false,
+                'forwarded' => false,
+                'draft' => false,
+                'deleted' => false,
+                'flagged' => false,
+            ];
+        }
+        if (array_key_exists($name, $this->data['flags'])) {
+            $this->data['flags'][$name] = $value;
+        }
+        return $this;
+    }
+
+    /**
+     * Sets message labels
+     *
+     * @since 2025.05.01
+     *
+     * @param string ...$value
+     *
+     * @return static
+     */
+    public function setLabels(string ...$value): static {
+        $this->data['labels'] = $value;
+        return $this;
+    }
+
+    /**
+     * Adds a message label
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function addLabel(string $value): static {
+        $this->data['labels'][] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets message tags
+     *
+     * @since 2025.05.01
+     *
+     * @param string ...$value
+     *
+     * @return static
+     */
+    public function setTags(string ...$value): static {
+        $this->data['tags'] = $value;
+        return $this;
+    }
+
+    /**
+     * Adds a message tag
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function addTag(string $value): static {
+        $this->data['tags'][] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets message priority
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setPriority(string $value): static {
+        $this->data['priority'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets message sensitivity
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return static
+     */
+    public function setSensitivity(string $value): static {
+        $this->data['sensitivity'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets encryption information
+     *
+     * @since 2025.05.01
+     *
+     * @param array $value
+     *
+     * @return static
+     */
+    public function setEncryption(array $value): static {
+        if (!isset($this->data['encryption'])) {
+            $this->data['encryption'] = [
+                'method' => null,
+                'signed' => false,
+                'encrypted' => false,
+            ];
+        }
+        $this->data['encryption'] = array_merge($this->data['encryption'], $value);
+        return $this;
+    }
+
+    /**
+     * Sets delivery receipt flag
+     *
+     * @since 2025.05.01
+     *
+     * @param bool $value
+     *
+     * @return static
+     */
+    public function setDeliveryReceipt(bool $value): static {
+        $this->data['deliveryReceipt'] = $value;
+        return $this;
+    }
+
+    /**
+     * Sets read receipt flag
+     *
+     * @since 2025.05.01
+     *
+     * @param bool $value
+     *
+     * @return static
+     */
+    public function setReadReceipt(bool $value): static {
+        $this->data['readReceipt'] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonDeserialize(array|string $data): static {
+        if (is_string($data)) {
+            $data = json_decode($data, true);
+        }
+
+        // Merge deserialized data into internal storage
+        foreach ($data as $key => $value) {
+            if (!in_array($key, ['collection', 'identifier', 'signature', 'created', 'modified'])) {
+                $this->data[$key] = $value;
+            }
+        }
+
+        return $this;
+    }
+}

shared/lib/Mail/Object/MessagePropertiesMutableInterface.php

@@ -0,0 +1,255 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Object;
+
+use DateTimeImmutable;
+use KTXF\Resource\Provider\Node\NodePropertiesMutableInterface;
+
+/**
+ * Message Properties Mutable Interface
+ * 
+ * @since 2025.05.01
+ */
+interface MessagePropertiesMutableInterface extends MessagePropertiesBaseInterface, NodePropertiesMutableInterface {
+
+    public const JSON_TYPE = MessagePropertiesBaseInterface::JSON_TYPE;
+    
+    /**
+     * Sets custom headers
+     *
+     * @since 2025.05.01
+     *
+     * @param array<string,string|array<int,string>> $value Header name => value
+     *
+     * @return self
+     */
+    public function setHeaders(array $value): static;
+
+    /**
+     * Sets a specific header value
+     *
+     * @since 2025.05.01
+     *
+     * @param string $name Header name
+     * @param string|array<int,string> $value Header value(s)
+     *
+     * @return self
+     */
+    public function setHeader(string $name, string|array $value): static;
+
+    /**
+     * Sets the universal resource identifier (URN)
+     *
+     * @since 2025.05.01
+     *
+     * @param string|null $value
+     *
+     * @return self
+     */
+    public function setUrid(?string $value): static;
+
+    /**
+     * Sets the message date
+     *
+     * @since 2025.05.01
+     *
+     * @param DateTimeImmutable $value
+     *
+     * @return self
+     */
+    public function setDate(DateTimeImmutable $value): static;
+
+    /**
+     * Sets the received date
+     *
+     * @since 2025.05.01
+     *
+     * @param DateTimeImmutable|null $value
+     *
+     * @return self
+     */
+    public function setReceived(?DateTimeImmutable $value): static;
+
+    /**
+     * Sets the message size in bytes
+     *
+     * @since 2025.05.01
+     *
+     * @param int|null $value
+     *
+     * @return self
+     */
+    public function setSize(?int $value): static;
+
+    /**
+     * Sets the sender address (actual sender, may differ from From)
+     *
+     * @since 2025.05.01
+     *
+     * @param AddressInterface|null $value
+     *
+     * @return self
+     */
+    public function setSender(?AddressInterface $value): static;
+
+    /**
+     * Sets the sender address
+     *
+     * @since 2025.05.01
+     *
+     * @param AddressInterface $value
+     *
+     * @return self
+     */
+    public function setFrom(AddressInterface $value): static;
+
+    /**
+     * Sets the reply-to addresses
+     *
+     * @since 2025.05.01
+     *
+     * @param AddressInterface ...$value
+     *
+     * @return self
+     */
+    public function setReplyTo(AddressInterface ...$value): static;
+
+    /**
+     * Sets the primary recipients (To)
+     *
+     * @since 2025.05.01
+     *
+     * @param AddressInterface ...$value
+     *
+     * @return self
+     */
+    public function setTo(AddressInterface ...$value): static;
+
+    /**
+     * Sets the carbon copy recipients (CC)
+     *
+     * @since 2025.05.01
+     *
+     * @param AddressInterface ...$value
+     *
+     * @return self
+     */
+    public function setCc(AddressInterface ...$value): static;
+
+    /**
+     * Sets the blind carbon copy recipients (BCC)
+     *
+     * @since 2025.05.01
+     *
+     * @param AddressInterface ...$value
+     *
+     * @return self
+     */
+    public function setBcc(AddressInterface ...$value): static;
+
+    /**
+     * Sets the message ID this is replying to
+     *
+     * @since 2025.05.01
+     *
+     * @param string|null $value
+     *
+     * @return self
+     */
+    public function setInReplyTo(?string $value): static;
+
+    /**
+     * Sets the references (message IDs in thread)
+     *
+     * @since 2025.05.01
+     *
+     * @param string ...$value
+     *
+     * @return self
+     */
+    public function setReferences(string ...$value): static;
+
+    /**
+     * Sets the message subject
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value
+     *
+     * @return self
+     */
+    public function setSubject(string $value): static;
+
+    /**
+     * Sets the message snippet/preview
+     *
+     * @since 2025.05.01
+     *
+     * @param string|null $value
+     *
+     * @return self
+     */
+    public function setSnippet(?string $value): static;
+
+    /**
+     * Sets the plain text body content
+     *
+     * @since 2025.05.01
+     *
+     * @param string|null $value
+     *
+     * @return self
+     */
+    public function setBodyText(?string $value): static;
+
+    /**
+     * Sets the HTML body content
+     *
+     * @since 2025.05.01
+     *
+     * @param string|null $value
+     *
+     * @return self
+     */
+    public function setBodyHtml(?string $value): static;
+
+    /**
+     * Sets the attachments
+     *
+     * @since 2025.05.01
+     *
+     * @param AttachmentInterface ...$value
+     *
+     * @return self
+     */
+    public function setAttachments(AttachmentInterface ...$value): static;
+
+    /**
+     * Adds an attachment
+     *
+     * @since 2025.05.01
+     *
+     * @param AttachmentInterface $value
+     *
+     * @return self
+     */
+    public function addAttachment(AttachmentInterface $value): static;
+    /**
+     * Sets message tags
+     *
+     * @since 2025.05.01
+     *
+     * @param array{read: bool, starred: bool, important: bool, answered: bool, forwarded: bool, draft: bool, deleted: bool, flagged: bool} $value
+     *
+     * @return self
+     */
+    public function setFlag(string $label, bool $value): static;
+
+}