Initial Version

shared/lib/Mail/Collection/CollectionRoles.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Collection;
+
+use JsonSerializable;
+
+/**
+ * Mail Collection Roles
+ * 
+ * Standard mailbox/folder roles for mail collections.
+ * 
+ * @since 2025.05.01
+ */
+enum CollectionRoles: string implements JsonSerializable {
+
+    case Inbox = 'inbox';
+    case Drafts = 'drafts';
+    case Sent = 'sent';
+    case Trash = 'trash';
+    case Junk = 'junk';
+    case Archive = 'archive';
+    case Outbox = 'outbox';
+    case Queue = 'queue';
+    case Custom = 'custom';
+
+    public function jsonSerialize(): string {
+        return $this->value;
+    }
+
+}

shared/lib/Mail/Collection/ICollectionBase.php

@@ -0,0 +1,117 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Collection;
+
+use DateTimeImmutable;
+use JsonSerializable;
+
+/**
+ * Mail Collection Base Interface
+ * 
+ * Represents a mailbox/folder in a mail service.
+ * For future use with full mail providers (IMAP, JMAP, etc.)
+ * 
+ * @since 2025.05.01
+ */
+interface ICollectionBase extends JsonSerializable {
+
+    public const JSON_TYPE = 'mail.collection';
+    public const JSON_PROPERTY_TYPE = '@type';
+    public const JSON_PROPERTY_PROVIDER = 'provider';
+    public const JSON_PROPERTY_SERVICE = 'service';
+    public const JSON_PROPERTY_IN = 'in';
+    public const JSON_PROPERTY_ID = 'id';
+    public const JSON_PROPERTY_LABEL = 'label';
+    public const JSON_PROPERTY_ROLE = 'role';
+    public const JSON_PROPERTY_TOTAL = 'total';
+    public const JSON_PROPERTY_UNREAD = 'unread';
+
+    /**
+     * Gets the parent collection identifier (null for root)
+     *
+     * @since 2025.05.01
+     *
+     * @return string|int|null
+     */
+    public function in(): string|int|null;
+
+    /**
+     * Gets the collection identifier
+     *
+     * @since 2025.05.01
+     *
+     * @return string|int
+     */
+    public function id(): string|int;
+
+    /**
+     * Gets the collection label/name
+     *
+     * @since 2025.05.01
+     *
+     * @return string
+     */
+    public function getLabel(): string;
+
+    /**
+     * Gets the collection role
+     *
+     * @since 2025.05.01
+     *
+     * @return CollectionRoles
+     */
+    public function getRole(): CollectionRoles;
+
+    /**
+     * Gets the total message count
+     *
+     * @since 2025.05.01
+     *
+     * @return int|null
+     */
+    public function getTotal(): ?int;
+
+    /**
+     * Gets the unread message count
+     *
+     * @since 2025.05.01
+     *
+     * @return int|null
+     */
+    public function getUnread(): ?int;
+
+    /**
+     * Gets the collection signature/sync token
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getSignature(): ?string;
+
+    /**
+     * Gets the creation date
+     *
+     * @since 2025.05.01
+     *
+     * @return DateTimeImmutable|null
+     */
+    public function created(): ?DateTimeImmutable;
+
+    /**
+     * Gets the modification date
+     *
+     * @since 2025.05.01
+     *
+     * @return DateTimeImmutable|null
+     */
+    public function modified(): ?DateTimeImmutable;
+
+}

shared/lib/Mail/Entity/Address.php

@@ -0,0 +1,141 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Entity;
+
+/**
+ * Mail Address Implementation
+ * 
+ * Concrete implementation of IAddress for email addresses.
+ * 
+ * @since 2025.05.01
+ */
+class Address implements IAddress {
+
+    /**
+     * @param string $address Email address
+     * @param string|null $name Display name
+     */
+    public function __construct(
+        private string $address = '',
+        private ?string $name = null,
+    ) {}
+
+    /**
+     * 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_NAME] ?? $data['name'] ?? null,
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getAddress(): string {
+        return $this->address;
+    }
+
+    /**
+     * Sets the email address
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $address
+     * 
+     * @return self
+     */
+    public function setAddress(string $address): self {
+        $this->address = $address;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getName(): ?string {
+        return $this->name;
+    }
+
+    /**
+     * Sets the display name
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string|null $name
+     * 
+     * @return self
+     */
+    public function setName(?string $name): self {
+        $this->name = $name;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function toString(): string {
+        if ($this->name !== null && $this->name !== '') {
+            return sprintf('"%s" <%s>', $this->name, $this->address);
+        }
+        return $this->address;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return array_filter([
+            self::JSON_PROPERTY_ADDRESS => $this->address,
+            self::JSON_PROPERTY_NAME => $this->name,
+        ], fn($v) => $v !== null && $v !== '');
+    }
+
+    /**
+     * String representation
+     */
+    public function __toString(): string {
+        return $this->toString();
+    }
+
+}

shared/lib/Mail/Entity/Attachment.php

@@ -0,0 +1,195 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Entity;
+
+/**
+ * Mail Attachment Implementation
+ * 
+ * Concrete implementation of IAttachment for mail attachments.
+ * 
+ * @since 2025.05.01
+ */
+class Attachment implements IAttachment {
+
+    /**
+     * @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);
+        }
+    }
+
+    /**
+     * 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);
+    }
+
+    /**
+     * @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);
+    }
+
+}

shared/lib/Mail/Entity/IAddress.php

@@ -0,0 +1,53 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Entity;
+
+use JsonSerializable;
+
+/**
+ * Mail Address Interface
+ * 
+ * Represents an email address with optional display name.
+ * 
+ * @since 2025.05.01
+ */
+interface IAddress extends JsonSerializable {
+
+    public const JSON_PROPERTY_ADDRESS = 'address';
+    public const JSON_PROPERTY_NAME = 'name';
+
+    /**
+     * Gets the email address
+     *
+     * @since 2025.05.01
+     *
+     * @return string Email address (e.g., "user@example.com")
+     */
+    public function getAddress(): string;
+
+    /**
+     * Gets the display name
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null Display name (e.g., "John Doe") or null
+     */
+    public function getName(): ?string;
+
+    /**
+     * 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/Entity/IAttachment.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\Entity;
+
+use JsonSerializable;
+
+/**
+ * Mail Attachment Interface
+ * 
+ * Represents a file attachment on a mail message.
+ * 
+ * @since 2025.05.01
+ */
+interface IAttachment 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/Entity/IMessageBase.php

@@ -0,0 +1,176 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Entity;
+
+use DateTimeImmutable;
+use JsonSerializable;
+
+/**
+ * Mail Message Base Interface
+ * 
+ * Read-only interface for mail message entities.
+ * 
+ * @since 2025.05.01
+ */
+interface IMessageBase extends JsonSerializable {
+
+    public const JSON_TYPE = 'mail.message';
+    public const JSON_PROPERTY_TYPE = '@type';
+    public const JSON_PROPERTY_ID = 'id';
+    public const JSON_PROPERTY_SUBJECT = 'subject';
+    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_DATE = 'date';
+    public const JSON_PROPERTY_BODY_TEXT = 'bodyText';
+    public const JSON_PROPERTY_BODY_HTML = 'bodyHtml';
+    public const JSON_PROPERTY_ATTACHMENTS = 'attachments';
+    public const JSON_PROPERTY_HEADERS = 'headers';
+
+    /**
+     * Gets the message identifier
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null Message ID or null for unsent messages
+     */
+    public function getId(): ?string;
+
+    /**
+     * Gets the message subject
+     *
+     * @since 2025.05.01
+     *
+     * @return string
+     */
+    public function getSubject(): string;
+
+    /**
+     * Gets the sender address
+     *
+     * @since 2025.05.01
+     *
+     * @return IAddress|null
+     */
+    public function getFrom(): ?IAddress;
+
+    /**
+     * Gets the reply-to address
+     *
+     * @since 2025.05.01
+     *
+     * @return IAddress|null
+     */
+    public function getReplyTo(): ?IAddress;
+
+    /**
+     * Gets the primary recipients (To)
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int, IAddress>
+     */
+    public function getTo(): array;
+
+    /**
+     * Gets the carbon copy recipients (CC)
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int, IAddress>
+     */
+    public function getCc(): array;
+
+    /**
+     * Gets the blind carbon copy recipients (BCC)
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int, IAddress>
+     */
+    public function getBcc(): array;
+
+    /**
+     * Gets the message date
+     *
+     * @since 2025.05.01
+     *
+     * @return DateTimeImmutable|null
+     */
+    public function getDate(): ?DateTimeImmutable;
+
+    /**
+     * Gets the plain text body
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getBodyText(): ?string;
+
+    /**
+     * Gets the HTML body
+     *
+     * @since 2025.05.01
+     *
+     * @return string|null
+     */
+    public function getBodyHtml(): ?string;
+
+    /**
+     * Gets the attachments
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int, IAttachment>
+     */
+    public function getAttachments(): array;
+
+    /**
+     * 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|null Header value or null if not set
+     */
+    public function getHeader(string $name): ?string;
+
+    /**
+     * Checks if the message has any recipients
+     *
+     * @since 2025.05.01
+     *
+     * @return bool True if To, CC, or BCC has at least one recipient
+     */
+    public function hasRecipients(): bool;
+
+    /**
+     * 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;
+
+}

shared/lib/Mail/Entity/IMessageMutable.php

@@ -0,0 +1,211 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Entity;
+
+use DateTimeImmutable;
+
+/**
+ * Mail Message Mutable Interface
+ * 
+ * Interface for composing and modifying mail messages with fluent setters.
+ * 
+ * @since 2025.05.01
+ */
+interface IMessageMutable extends IMessageBase {
+
+    /**
+     * Sets the message identifier
+     *
+     * @since 2025.05.01
+     *
+     * @param string|null $id
+     *
+     * @return self
+     */
+    public function setId(?string $id): self;
+
+    /**
+     * Sets the message subject
+     *
+     * @since 2025.05.01
+     *
+     * @param string $subject
+     *
+     * @return self
+     */
+    public function setSubject(string $subject): self;
+
+    /**
+     * Sets the sender address
+     *
+     * @since 2025.05.01
+     *
+     * @param IAddress|null $from
+     *
+     * @return self
+     */
+    public function setFrom(?IAddress $from): self;
+
+    /**
+     * Sets the reply-to address
+     *
+     * @since 2025.05.01
+     *
+     * @param IAddress|null $replyTo
+     *
+     * @return self
+     */
+    public function setReplyTo(?IAddress $replyTo): self;
+
+    /**
+     * Sets the primary recipients (To)
+     *
+     * @since 2025.05.01
+     *
+     * @param array<int, IAddress> $to
+     *
+     * @return self
+     */
+    public function setTo(array $to): self;
+
+    /**
+     * Adds a primary recipient (To)
+     *
+     * @since 2025.05.01
+     *
+     * @param IAddress $address
+     *
+     * @return self
+     */
+    public function addTo(IAddress $address): self;
+
+    /**
+     * Sets the carbon copy recipients (CC)
+     *
+     * @since 2025.05.01
+     *
+     * @param array<int, IAddress> $cc
+     *
+     * @return self
+     */
+    public function setCc(array $cc): self;
+
+    /**
+     * Adds a carbon copy recipient (CC)
+     *
+     * @since 2025.05.01
+     *
+     * @param IAddress $address
+     *
+     * @return self
+     */
+    public function addCc(IAddress $address): self;
+
+    /**
+     * Sets the blind carbon copy recipients (BCC)
+     *
+     * @since 2025.05.01
+     *
+     * @param array<int, IAddress> $bcc
+     *
+     * @return self
+     */
+    public function setBcc(array $bcc): self;
+
+    /**
+     * Adds a blind carbon copy recipient (BCC)
+     *
+     * @since 2025.05.01
+     *
+     * @param IAddress $address
+     *
+     * @return self
+     */
+    public function addBcc(IAddress $address): self;
+
+    /**
+     * Sets the message date
+     *
+     * @since 2025.05.01
+     *
+     * @param DateTimeImmutable|null $date
+     *
+     * @return self
+     */
+    public function setDate(?DateTimeImmutable $date): self;
+
+    /**
+     * Sets the plain text body
+     *
+     * @since 2025.05.01
+     *
+     * @param string|null $text
+     *
+     * @return self
+     */
+    public function setBodyText(?string $text): self;
+
+    /**
+     * Sets the HTML body
+     *
+     * @since 2025.05.01
+     *
+     * @param string|null $html
+     *
+     * @return self
+     */
+    public function setBodyHtml(?string $html): self;
+
+    /**
+     * Sets the attachments
+     *
+     * @since 2025.05.01
+     *
+     * @param array<int, IAttachment> $attachments
+     *
+     * @return self
+     */
+    public function setAttachments(array $attachments): self;
+
+    /**
+     * Adds an attachment
+     *
+     * @since 2025.05.01
+     *
+     * @param IAttachment $attachment
+     *
+     * @return self
+     */
+    public function addAttachment(IAttachment $attachment): self;
+
+    /**
+     * Sets custom headers
+     *
+     * @since 2025.05.01
+     *
+     * @param array<string, string> $headers Header name => value
+     *
+     * @return self
+     */
+    public function setHeaders(array $headers): self;
+
+    /**
+     * Sets a specific header value
+     *
+     * @since 2025.05.01
+     *
+     * @param string $name Header name
+     * @param string $value Header value
+     *
+     * @return self
+     */
+    public function setHeader(string $name, string $value): self;
+
+}

shared/lib/Mail/Entity/Message.php

@@ -0,0 +1,383 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Entity;
+
+use DateTimeImmutable;
+
+/**
+ * Mail Message Implementation
+ * 
+ * Concrete implementation of IMessageMutable for composing mail messages.
+ * 
+ * @since 2025.05.01
+ */
+class Message implements IMessageMutable {
+
+    private ?string $id = null;
+    private string $subject = '';
+    private ?IAddress $from = null;
+    private ?IAddress $replyTo = null;
+    /** @var array<int, IAddress> */
+    private array $to = [];
+    /** @var array<int, IAddress> */
+    private array $cc = [];
+    /** @var array<int, IAddress> */
+    private array $bcc = [];
+    private ?DateTimeImmutable $date = null;
+    private ?string $bodyText = null;
+    private ?string $bodyHtml = null;
+    /** @var array<int, IAttachment> */
+    private array $attachments = [];
+    /** @var array<string, string> */
+    private array $headers = [];
+
+    /**
+     * Creates a message from array data
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        $message = new self();
+        
+        if (isset($data[self::JSON_PROPERTY_ID])) {
+            $message->setId($data[self::JSON_PROPERTY_ID]);
+        }
+        if (isset($data[self::JSON_PROPERTY_SUBJECT])) {
+            $message->setSubject($data[self::JSON_PROPERTY_SUBJECT]);
+        }
+        if (isset($data[self::JSON_PROPERTY_FROM])) {
+            $message->setFrom(Address::fromArray($data[self::JSON_PROPERTY_FROM]));
+        }
+        if (isset($data[self::JSON_PROPERTY_REPLY_TO])) {
+            $message->setReplyTo(Address::fromArray($data[self::JSON_PROPERTY_REPLY_TO]));
+        }
+        if (isset($data[self::JSON_PROPERTY_TO])) {
+            $message->setTo(array_map(fn($a) => Address::fromArray($a), $data[self::JSON_PROPERTY_TO]));
+        }
+        if (isset($data[self::JSON_PROPERTY_CC])) {
+            $message->setCc(array_map(fn($a) => Address::fromArray($a), $data[self::JSON_PROPERTY_CC]));
+        }
+        if (isset($data[self::JSON_PROPERTY_BCC])) {
+            $message->setBcc(array_map(fn($a) => Address::fromArray($a), $data[self::JSON_PROPERTY_BCC]));
+        }
+        if (isset($data[self::JSON_PROPERTY_DATE])) {
+            $message->setDate(new DateTimeImmutable($data[self::JSON_PROPERTY_DATE]));
+        }
+        if (isset($data[self::JSON_PROPERTY_BODY_TEXT])) {
+            $message->setBodyText($data[self::JSON_PROPERTY_BODY_TEXT]);
+        }
+        if (isset($data[self::JSON_PROPERTY_BODY_HTML])) {
+            $message->setBodyHtml($data[self::JSON_PROPERTY_BODY_HTML]);
+        }
+        if (isset($data[self::JSON_PROPERTY_ATTACHMENTS])) {
+            $message->setAttachments(array_map(fn($a) => Attachment::fromArray($a), $data[self::JSON_PROPERTY_ATTACHMENTS]));
+        }
+        if (isset($data[self::JSON_PROPERTY_HEADERS])) {
+            $message->setHeaders($data[self::JSON_PROPERTY_HEADERS]);
+        }
+        
+        return $message;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getId(): ?string {
+        return $this->id;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setId(?string $id): self {
+        $this->id = $id;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getSubject(): string {
+        return $this->subject;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setSubject(string $subject): self {
+        $this->subject = $subject;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getFrom(): ?IAddress {
+        return $this->from;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setFrom(?IAddress $from): self {
+        $this->from = $from;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getReplyTo(): ?IAddress {
+        return $this->replyTo;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setReplyTo(?IAddress $replyTo): self {
+        $this->replyTo = $replyTo;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getTo(): array {
+        return $this->to;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setTo(array $to): self {
+        $this->to = $to;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function addTo(IAddress $address): self {
+        $this->to[] = $address;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getCc(): array {
+        return $this->cc;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setCc(array $cc): self {
+        $this->cc = $cc;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function addCc(IAddress $address): self {
+        $this->cc[] = $address;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBcc(): array {
+        return $this->bcc;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setBcc(array $bcc): self {
+        $this->bcc = $bcc;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function addBcc(IAddress $address): self {
+        $this->bcc[] = $address;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getDate(): ?DateTimeImmutable {
+        return $this->date;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setDate(?DateTimeImmutable $date): self {
+        $this->date = $date;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBodyText(): ?string {
+        return $this->bodyText;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setBodyText(?string $text): self {
+        $this->bodyText = $text;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getBodyHtml(): ?string {
+        return $this->bodyHtml;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setBodyHtml(?string $html): self {
+        $this->bodyHtml = $html;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getAttachments(): array {
+        return $this->attachments;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setAttachments(array $attachments): self {
+        $this->attachments = $attachments;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function addAttachment(IAttachment $attachment): self {
+        $this->attachments[] = $attachment;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getHeaders(): array {
+        return $this->headers;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getHeader(string $name): ?string {
+        return $this->headers[$name] ?? null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setHeaders(array $headers): self {
+        $this->headers = $headers;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function setHeader(string $name, string $value): self {
+        $this->headers[$name] = $value;
+        return $this;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function hasRecipients(): bool {
+        return !empty($this->to) || !empty($this->cc) || !empty($this->bcc);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function hasBody(): bool {
+        return ($this->bodyText !== null && $this->bodyText !== '') 
+            || ($this->bodyHtml !== null && $this->bodyHtml !== '');
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        $data = [
+            self::JSON_PROPERTY_TYPE => self::JSON_TYPE,
+        ];
+        
+        if ($this->id !== null) {
+            $data[self::JSON_PROPERTY_ID] = $this->id;
+        }
+        
+        $data[self::JSON_PROPERTY_SUBJECT] = $this->subject;
+        
+        if ($this->from !== null) {
+            $data[self::JSON_PROPERTY_FROM] = $this->from;
+        }
+        if ($this->replyTo !== null) {
+            $data[self::JSON_PROPERTY_REPLY_TO] = $this->replyTo;
+        }
+        if (!empty($this->to)) {
+            $data[self::JSON_PROPERTY_TO] = $this->to;
+        }
+        if (!empty($this->cc)) {
+            $data[self::JSON_PROPERTY_CC] = $this->cc;
+        }
+        if (!empty($this->bcc)) {
+            $data[self::JSON_PROPERTY_BCC] = $this->bcc;
+        }
+        if ($this->date !== null) {
+            $data[self::JSON_PROPERTY_DATE] = $this->date->format('c');
+        }
+        if ($this->bodyText !== null) {
+            $data[self::JSON_PROPERTY_BODY_TEXT] = $this->bodyText;
+        }
+        if ($this->bodyHtml !== null) {
+            $data[self::JSON_PROPERTY_BODY_HTML] = $this->bodyHtml;
+        }
+        if (!empty($this->attachments)) {
+            $data[self::JSON_PROPERTY_ATTACHMENTS] = $this->attachments;
+        }
+        if (!empty($this->headers)) {
+            $data[self::JSON_PROPERTY_HEADERS] = $this->headers;
+        }
+        
+        return $data;
+    }
+
+}

shared/lib/Mail/Exception/SendException.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Exception;
+
+use Exception;
+
+/**
+ * Mail Send Exception
+ * 
+ * Exception thrown when mail delivery fails.
+ * 
+ * @since 2025.05.01
+ */
+class SendException extends Exception {
+
+    /**
+     * @param string $message Error message
+     * @param int $code Error code
+     * @param Exception|null $previous Previous exception
+     * @param string|null $recipient Specific recipient that failed (if applicable)
+     * @param bool $permanent Whether this is a permanent failure (no retry)
+     */
+    public function __construct(
+        string $message,
+        int $code = 0,
+        ?Exception $previous = null,
+        public readonly ?string $recipient = null,
+        public readonly bool $permanent = false,
+    ) {
+        parent::__construct($message, $code, $previous);
+    }
+
+    /**
+     * Creates a permanent failure exception (no retry)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $message
+     * @param string|null $recipient
+     * 
+     * @return self
+     */
+    public static function permanent(string $message, ?string $recipient = null): self {
+        return new self($message, 0, null, $recipient, true);
+    }
+
+    /**
+     * Creates a temporary failure exception (will retry)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $message
+     * @param Exception|null $previous
+     * 
+     * @return self
+     */
+    public static function temporary(string $message, ?Exception $previous = null): self {
+        return new self($message, 0, $previous, null, false);
+    }
+
+}

shared/lib/Mail/Provider/IProviderBase.php

@@ -0,0 +1,132 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Provider;
+
+use JsonSerializable;
+use KTXF\Mail\Selector\ServiceSelector;
+use KTXF\Mail\Service\IServiceBase;
+
+/**
+ * Mail Provider Base Interface
+ * 
+ * Core interface for mail providers with context-aware service discovery.
+ * 
+ * @since 2025.05.01
+ */
+interface IProviderBase extends JsonSerializable {
+
+    public const CAPABILITY_SERVICE_LIST = 'ServiceList';
+    public const CAPABILITY_SERVICE_FETCH = 'ServiceFetch';
+    public const CAPABILITY_SERVICE_EXTANT = 'ServiceExtant';
+    public const CAPABILITY_SERVICE_FIND_BY_ADDRESS = 'ServiceFindByAddress';
+
+    public const JSON_TYPE = 'mail.provider';
+    public const JSON_PROPERTY_TYPE = '@type';
+    public const JSON_PROPERTY_ID = 'id';
+    public const JSON_PROPERTY_LABEL = 'label';
+    public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
+
+    /**
+     * Confirms if a specific capability is supported
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value Required capability e.g. 'ServiceList'
+     *
+     * @return bool
+     */
+    public function capable(string $value): bool;
+
+    /**
+     * Lists all supported capabilities
+     *
+     * @since 2025.05.01
+     *
+     * @return array<string,bool>
+     */
+    public function capabilities(): array;
+
+    /**
+     * Gets the unique identifier for this provider
+     *
+     * @since 2025.05.01
+     *
+     * @return string Provider ID (e.g., 'smtp', 'imap', 'jmap')
+     */
+    public function id(): string;
+
+    /**
+     * Gets the localized human-friendly name of this provider
+     *
+     * @since 2025.05.01
+     *
+     * @return string Provider label (e.g., 'SMTP Mail Provider')
+     */
+    public function label(): string;
+
+    /**
+     * Lists services for a tenant, optionally filtered by user context
+     * 
+     * When userId is null, returns only System-scoped services.
+     * When userId is provided, returns System-scoped services plus
+     * User-scoped services owned by that user.
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context (null = system only)
+     * @param ServiceSelector|null $selector Optional filter criteria
+     *
+     * @return array<string|int, IServiceBase>
+     */
+    public function serviceList(string $tenantId, ?string $userId = null, ?ServiceSelector $selector = null): array;
+
+    /**
+     * Checks if specific services exist
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context
+     * @param string|int ...$identifiers Service identifiers to check
+     *
+     * @return array<string|int, bool> Identifier => exists
+     */
+    public function serviceExtant(string $tenantId, ?string $userId, string|int ...$identifiers): array;
+
+    /**
+     * Fetches a specific service by identifier
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context
+     * @param string|int $identifier Service identifier
+     *
+     * @return IServiceBase|null
+     */
+    public function serviceFetch(string $tenantId, ?string $userId, string|int $identifier): ?IServiceBase;
+
+    /**
+     * Finds a service that handles a specific email address
+     * 
+     * Searches within the appropriate scope based on userId context.
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for context
+     * @param string $address Email address to find service for
+     *
+     * @return IServiceBase|null Service handling the address, or null
+     */
+    public function serviceFindByAddress(string $tenantId, ?string $userId, string $address): ?IServiceBase;
+
+}

shared/lib/Mail/Provider/IProviderServiceMutate.php

@@ -0,0 +1,77 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Provider;
+
+use KTXF\Json\JsonDeserializable;
+use KTXF\Mail\Service\IServiceBase;
+
+/**
+ * Mail Provider Service Mutate Interface
+ * 
+ * Optional interface for providers that support service CRUD operations.
+ * 
+ * @since 2025.05.01
+ */
+interface IProviderServiceMutate extends JsonDeserializable {
+
+    public const CAPABILITY_SERVICE_FRESH = 'ServiceFresh';
+    public const CAPABILITY_SERVICE_CREATE = 'ServiceCreate';
+    public const CAPABILITY_SERVICE_MODIFY = 'ServiceModify';
+    public const CAPABILITY_SERVICE_DESTROY = 'ServiceDestroy';
+
+    /**
+     * Creates a new blank service instance for configuration
+     *
+     * @since 2025.05.01
+     *
+     * @return IServiceBase Fresh service object
+     */
+    public function serviceFresh(): IServiceBase;
+
+    /**
+     * Creates a new service configuration
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId Owner user ID (null for system services)
+     * @param IServiceBase $service Service configuration to create
+     *
+     * @return string|int Created service identifier
+     */
+    public function serviceCreate(string $tenantId, ?string $userId, IServiceBase $service): string|int;
+
+    /**
+     * Modifies an existing service configuration
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for authorization context
+     * @param IServiceBase $service Service configuration to update
+     *
+     * @return string|int Updated service identifier
+     */
+    public function serviceModify(string $tenantId, ?string $userId, IServiceBase $service): string|int;
+
+    /**
+     * Destroys a service configuration
+     *
+     * @since 2025.05.01
+     *
+     * @param string $tenantId Tenant identifier
+     * @param string|null $userId User identifier for authorization context
+     * @param IServiceBase $service Service to destroy
+     *
+     * @return bool True if destroyed, false if not found
+     */
+    public function serviceDestroy(string $tenantId, ?string $userId, IServiceBase $service): bool;
+
+}

shared/lib/Mail/Queue/SendOptions.php

@@ -0,0 +1,81 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Queue;
+
+use JsonSerializable;
+
+/**
+ * Mail Send Options
+ * 
+ * Configuration options for message delivery behavior.
+ * 
+ * @since 2025.05.01
+ */
+class SendOptions implements JsonSerializable {
+
+    /**
+     * @param bool $immediate Send immediately bypassing queue (for 2FA, etc.)
+     * @param int $priority Queue priority (-100 to 100, higher = sooner)
+     * @param int $retryCount Maximum retry attempts on failure
+     * @param int|null $delaySeconds Delay before first send attempt
+     */
+    public function __construct(
+        public readonly bool $immediate = false,
+        public readonly int $priority = 0,
+        public readonly int $retryCount = 3,
+        public readonly ?int $delaySeconds = null,
+    ) {}
+
+    /**
+     * Creates options for immediate delivery (bypasses queue)
+     * 
+     * @since 2025.05.01
+     * 
+     * @return self
+     */
+    public static function immediate(): self {
+        return new self(immediate: true);
+    }
+
+    /**
+     * Creates options for high-priority queued delivery
+     * 
+     * @since 2025.05.01
+     * 
+     * @return self
+     */
+    public static function highPriority(): self {
+        return new self(priority: 50);
+    }
+
+    /**
+     * Creates options for low-priority queued delivery (bulk mail)
+     * 
+     * @since 2025.05.01
+     * 
+     * @return self
+     */
+    public static function lowPriority(): self {
+        return new self(priority: -50);
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return [
+            'immediate' => $this->immediate,
+            'priority' => $this->priority,
+            'retryCount' => $this->retryCount,
+            'delaySeconds' => $this->delaySeconds,
+        ];
+    }
+
+}

shared/lib/Mail/Selector/ServiceSelector.php

@@ -0,0 +1,183 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Selector;
+
+use JsonSerializable;
+use KTXF\Mail\Service\ServiceScope;
+
+/**
+ * Mail Service Selector
+ * 
+ * Filter criteria for selecting mail services from providers.
+ * 
+ * @since 2025.05.01
+ */
+class ServiceSelector implements JsonSerializable {
+
+    private ?ServiceScope $scope = null;
+    private ?string $owner = null;
+    private ?string $address = null;
+    private ?array $capabilities = null;
+    private ?bool $enabled = null;
+
+    /**
+     * Filter by service scope
+     * 
+     * @since 2025.05.01
+     * 
+     * @param ServiceScope|null $scope
+     * 
+     * @return self
+     */
+    public function setScope(?ServiceScope $scope): self {
+        $this->scope = $scope;
+        return $this;
+    }
+
+    /**
+     * Gets the scope filter
+     * 
+     * @since 2025.05.01
+     * 
+     * @return ServiceScope|null
+     */
+    public function getScope(): ?ServiceScope {
+        return $this->scope;
+    }
+
+    /**
+     * Filter by owner user ID
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string|null $owner
+     * 
+     * @return self
+     */
+    public function setOwner(?string $owner): self {
+        $this->owner = $owner;
+        return $this;
+    }
+
+    /**
+     * Gets the owner filter
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null
+     */
+    public function getOwner(): ?string {
+        return $this->owner;
+    }
+
+    /**
+     * Filter by email address (matches primary or secondary)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string|null $address
+     * 
+     * @return self
+     */
+    public function setAddress(?string $address): self {
+        $this->address = $address;
+        return $this;
+    }
+
+    /**
+     * Gets the address filter
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null
+     */
+    public function getAddress(): ?string {
+        return $this->address;
+    }
+
+    /**
+     * Filter by required capabilities
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array<string>|null $capabilities
+     * 
+     * @return self
+     */
+    public function setCapabilities(?array $capabilities): self {
+        $this->capabilities = $capabilities;
+        return $this;
+    }
+
+    /**
+     * Gets the capabilities filter
+     * 
+     * @since 2025.05.01
+     * 
+     * @return array<string>|null
+     */
+    public function getCapabilities(): ?array {
+        return $this->capabilities;
+    }
+
+    /**
+     * Filter by enabled status
+     * 
+     * @since 2025.05.01
+     * 
+     * @param bool|null $enabled
+     * 
+     * @return self
+     */
+    public function setEnabled(?bool $enabled): self {
+        $this->enabled = $enabled;
+        return $this;
+    }
+
+    /**
+     * Gets the enabled filter
+     * 
+     * @since 2025.05.01
+     * 
+     * @return bool|null
+     */
+    public function getEnabled(): ?bool {
+        return $this->enabled;
+    }
+
+    /**
+     * Checks if any filter criteria are set
+     * 
+     * @since 2025.05.01
+     * 
+     * @return bool
+     */
+    public function hasFilters(): bool {
+        return $this->scope !== null
+            || $this->owner !== null
+            || $this->address !== null
+            || $this->capabilities !== null
+            || $this->enabled !== null;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return array_filter([
+            'scope' => $this->scope?->value,
+            'owner' => $this->owner,
+            'address' => $this->address,
+            'capabilities' => $this->capabilities,
+            'enabled' => $this->enabled,
+        ], fn($v) => $v !== null);
+    }
+
+}

shared/lib/Mail/Service/IServiceBase.php

@@ -0,0 +1,139 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+use JsonSerializable;
+use KTXF\Mail\Entity\IAddress;
+
+/**
+ * Mail Service Base Interface
+ * 
+ * Core interface for mail services providing identity, addressing, and capability information.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceBase extends JsonSerializable {
+
+    public const JSON_TYPE = 'mail.service';
+    public const JSON_PROPERTY_TYPE = '@type';
+    public const JSON_PROPERTY_PROVIDER = 'provider';
+    public const JSON_PROPERTY_ID = 'id';
+    public const JSON_PROPERTY_LABEL = 'label';
+    public const JSON_PROPERTY_SCOPE = 'scope';
+    public const JSON_PROPERTY_OWNER = 'owner';
+    public const JSON_PROPERTY_ENABLED = 'enabled';
+    public const JSON_PROPERTY_CAPABILITIES = 'capabilities';
+    public const JSON_PROPERTY_PRIMARY_ADDRESS = 'primaryAddress';
+    public const JSON_PROPERTY_SECONDARY_ADDRESSES = 'secondaryAddresses';
+
+    /**
+     * Confirms if a specific capability is supported
+     *
+     * @since 2025.05.01
+     *
+     * @param string $value Required capability e.g. 'Send'
+     *
+     * @return bool
+     */
+    public function capable(string $value): bool;
+
+    /**
+     * Lists all supported capabilities
+     *
+     * @since 2025.05.01
+     *
+     * @return array<string,bool>
+     */
+    public function capabilities(): array;
+
+    /**
+     * Gets the unique identifier of the provider this service belongs to
+     *
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function in(): string;
+
+    /**
+     * Gets the unique identifier for this service
+     *
+     * @since 2025.05.01
+     * 
+     * @return string|int
+     */
+    public function id(): string|int;
+
+    /**
+     * Gets the localized human-friendly name of this service
+     *
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getLabel(): string;
+
+    /**
+     * Gets the scope of this service (System or User)
+     *
+     * @since 2025.05.01
+     * 
+     * @return ServiceScope
+     */
+    public function getScope(): ServiceScope;
+
+    /**
+     * Gets the owner user ID for User-scoped services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null User ID or null for System scope
+     */
+    public function getOwner(): ?string;
+
+    /**
+     * Gets whether this service is enabled
+     *
+     * @since 2025.05.01
+     * 
+     * @return bool
+     */
+    public function getEnabled(): bool;
+
+    /**
+     * Gets the primary mailing address for this service
+     *
+     * @since 2025.05.01
+     *
+     * @return IAddress
+     */
+    public function getPrimaryAddress(): IAddress;
+
+    /**
+     * Gets the secondary mailing addresses (aliases) for this service
+     *
+     * @since 2025.05.01
+     *
+     * @return array<int, IAddress>
+     */
+    public function getSecondaryAddresses(): array;
+
+    /**
+     * Checks if this service handles a specific email address
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $address Email address to check
+     * 
+     * @return bool True if address matches primary or any secondary address
+     */
+    public function handlesAddress(string $address): bool;
+
+}

shared/lib/Mail/Service/IServiceIdentity.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+use JsonSerializable;
+
+/**
+ * Mail Service Identity Interface
+ * 
+ * Base interface for authentication credentials used by mail services.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceIdentity extends JsonSerializable {
+
+    public const TYPE_BASIC = 'basic';
+    public const TYPE_OAUTH = 'oauth';
+    public const TYPE_APIKEY = 'apikey';
+
+    /**
+     * Gets the identity/authentication type
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string One of: 'basic', 'oauth', 'apikey'
+     */
+    public function getType(): string;
+
+}

shared/lib/Mail/Service/IServiceIdentityApiKey.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service API Key Identity Interface
+ * 
+ * API key authentication for transactional mail services (SendGrid, Mailgun, etc.)
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceIdentityApiKey extends IServiceIdentity {
+
+    /**
+     * Gets the API key
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getApiKey(): string;
+
+    /**
+     * Gets the optional API key identifier/name
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null
+     */
+    public function getApiKeyId(): ?string;
+
+}

shared/lib/Mail/Service/IServiceIdentityBasic.php

@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service Basic Authentication Identity Interface
+ * 
+ * Username/password authentication for traditional mail services.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceIdentityBasic extends IServiceIdentity {
+
+    /**
+     * Gets the username/login identifier
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getUsername(): string;
+
+    /**
+     * Gets the password/secret
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getPassword(): string;
+
+}

shared/lib/Mail/Service/IServiceIdentityOAuth.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+use DateTimeImmutable;
+
+/**
+ * Mail Service OAuth Identity Interface
+ * 
+ * OAuth2 token-based authentication for modern mail APIs.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceIdentityOAuth extends IServiceIdentity {
+
+    /**
+     * Gets the OAuth access token
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string
+     */
+    public function getAccessToken(): string;
+
+    /**
+     * Gets the OAuth refresh token
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null
+     */
+    public function getRefreshToken(): ?string;
+
+    /**
+     * Gets the token expiration time
+     * 
+     * @since 2025.05.01
+     * 
+     * @return DateTimeImmutable|null
+     */
+    public function getExpiresAt(): ?DateTimeImmutable;
+
+    /**
+     * Gets the granted OAuth scopes
+     * 
+     * @since 2025.05.01
+     * 
+     * @return array<string>
+     */
+    public function getScopes(): array;
+
+    /**
+     * Checks if the access token has expired
+     * 
+     * @since 2025.05.01
+     * 
+     * @return bool
+     */
+    public function isExpired(): bool;
+
+}

shared/lib/Mail/Service/IServiceLocation.php

@@ -0,0 +1,105 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+use JsonSerializable;
+
+/**
+ * Mail Service Location Interface
+ * 
+ * Unified interface supporting both URI-based (API services) and socket-based
+ * (traditional IMAP/SMTP) connection configurations.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceLocation extends JsonSerializable {
+
+    public const TYPE_URI = 'uri';
+    public const TYPE_SOCKET_SINGLE = 'socket-single';
+    public const TYPE_SOCKET_SPLIT = 'socket-split';
+
+    public const SECURITY_NONE = 'none';
+    public const SECURITY_SSL = 'ssl';
+    public const SECURITY_TLS = 'tls';
+    public const SECURITY_STARTTLS = 'starttls';
+
+    /**
+     * Gets the location type
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string One of: 'uri', 'socket-single', 'socket-split'
+     */
+    public function getType(): string;
+
+    /**
+     * Gets the URI for API-based services (JMAP, EWS, Graph API, HTTP relay)
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null URI or null if not URI-based
+     */
+    public function getUri(): ?string;
+
+    /**
+     * Gets the inbound/primary host for socket-based services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null Hostname or null if URI-based
+     */
+    public function getInboundHost(): ?string;
+
+    /**
+     * Gets the inbound/primary port for socket-based services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return int|null Port number or null if URI-based
+     */
+    public function getInboundPort(): ?int;
+
+    /**
+     * Gets the inbound/primary security mode
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null One of: 'none', 'ssl', 'tls', 'starttls'
+     */
+    public function getInboundSecurity(): ?string;
+
+    /**
+     * Gets the outbound host for split-socket services (e.g., SMTP separate from IMAP)
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null Hostname or null if not split-socket
+     */
+    public function getOutboundHost(): ?string;
+
+    /**
+     * Gets the outbound port for split-socket services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return int|null Port number or null if not split-socket
+     */
+    public function getOutboundPort(): ?int;
+
+    /**
+     * Gets the outbound security mode for split-socket services
+     * 
+     * @since 2025.05.01
+     * 
+     * @return string|null One of: 'none', 'ssl', 'tls', 'starttls'
+     */
+    public function getOutboundSecurity(): ?string;
+
+}

shared/lib/Mail/Service/IServiceSend.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+use KTXF\Mail\Entity\IMessageMutable;
+use KTXF\Mail\Exception\SendException;
+
+/**
+ * Mail Service Send Interface
+ * 
+ * Interface for mail services capable of sending outbound messages.
+ * This is the minimum capability for an outbound-only mail service.
+ * 
+ * @since 2025.05.01
+ */
+interface IServiceSend extends IServiceBase {
+
+    public const CAPABILITY_SEND = 'Send';
+
+    /**
+     * Creates a new fresh message object
+     *
+     * @since 2025.05.01
+     *
+     * @return IMessageMutable Fresh message object for composing
+     */
+    public function messageFresh(): IMessageMutable;
+
+    /**
+     * Sends an outbound message
+     *
+     * @since 2025.05.01
+     *
+     * @param IMessageMutable $message Message to send
+     *
+     * @return string Message ID assigned by the transport
+     * 
+     * @throws SendException On delivery failure
+     */
+    public function messageSend(IMessageMutable $message): string;
+
+}

shared/lib/Mail/Service/ServiceIdentityApiKey.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service API Key Identity Implementation
+ * 
+ * API key authentication for transactional mail services.
+ * 
+ * @since 2025.05.01
+ */
+class ServiceIdentityApiKey implements IServiceIdentityApiKey {
+
+    /**
+     * @param string $apiKey API key
+     * @param string|null $apiKeyId Optional API key identifier
+     */
+    public function __construct(
+        private string $apiKey,
+        private ?string $apiKeyId = null,
+    ) {}
+
+    /**
+     * Creates from array data
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        return new self(
+            $data['apiKey'] ?? '',
+            $data['apiKeyId'] ?? null,
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getType(): string {
+        return self::TYPE_APIKEY;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getApiKey(): string {
+        return $this->apiKey;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getApiKeyId(): ?string {
+        return $this->apiKeyId;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return array_filter([
+            'type' => self::TYPE_APIKEY,
+            'apiKeyId' => $this->apiKeyId,
+            // API key intentionally omitted from serialization for security
+        ], fn($v) => $v !== null);
+    }
+
+}

shared/lib/Mail/Service/ServiceIdentityBasic.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service Basic Identity Implementation
+ * 
+ * Username/password authentication credentials.
+ * 
+ * @since 2025.05.01
+ */
+class ServiceIdentityBasic implements IServiceIdentityBasic {
+
+    /**
+     * @param string $username Login username
+     * @param string $password Login password
+     */
+    public function __construct(
+        private string $username,
+        private string $password,
+    ) {}
+
+    /**
+     * Creates from array data
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        return new self(
+            $data['username'] ?? '',
+            $data['password'] ?? '',
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getType(): string {
+        return self::TYPE_BASIC;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getUsername(): string {
+        return $this->username;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getPassword(): string {
+        return $this->password;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        return [
+            'type' => self::TYPE_BASIC,
+            'username' => $this->username,
+            // Password intentionally omitted from serialization for security
+        ];
+    }
+
+}

shared/lib/Mail/Service/ServiceLocation.php

@@ -0,0 +1,211 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+/**
+ * Mail Service Location Implementation
+ * 
+ * Unified implementation supporting URI-based and socket-based connections.
+ * 
+ * @since 2025.05.01
+ */
+class ServiceLocation implements IServiceLocation {
+
+    /**
+     * @param string $type Location type (uri, socket-single, socket-split)
+     * @param string|null $uri URI for API-based services
+     * @param string|null $inboundHost Inbound/primary host
+     * @param int|null $inboundPort Inbound/primary port
+     * @param string|null $inboundSecurity Inbound security (none, ssl, tls, starttls)
+     * @param string|null $outboundHost Outbound host (for split-socket)
+     * @param int|null $outboundPort Outbound port (for split-socket)
+     * @param string|null $outboundSecurity Outbound security (for split-socket)
+     */
+    public function __construct(
+        private string $type,
+        private ?string $uri = null,
+        private ?string $inboundHost = null,
+        private ?int $inboundPort = null,
+        private ?string $inboundSecurity = null,
+        private ?string $outboundHost = null,
+        private ?int $outboundPort = null,
+        private ?string $outboundSecurity = null,
+    ) {}
+
+    /**
+     * Creates a URI-based location (for API services)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $uri
+     * 
+     * @return self
+     */
+    public static function uri(string $uri): self {
+        return new self(self::TYPE_URI, $uri);
+    }
+
+    /**
+     * Creates a single-socket location (e.g., SMTP only)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $host
+     * @param int $port
+     * @param string $security
+     * 
+     * @return self
+     */
+    public static function socket(string $host, int $port, string $security = self::SECURITY_TLS): self {
+        return new self(
+            self::TYPE_SOCKET_SINGLE,
+            null,
+            $host,
+            $port,
+            $security
+        );
+    }
+
+    /**
+     * Creates a split-socket location (IMAP + SMTP)
+     * 
+     * @since 2025.05.01
+     * 
+     * @param string $inboundHost IMAP host
+     * @param int $inboundPort IMAP port
+     * @param string $inboundSecurity IMAP security
+     * @param string $outboundHost SMTP host
+     * @param int $outboundPort SMTP port
+     * @param string $outboundSecurity SMTP security
+     * 
+     * @return self
+     */
+    public static function splitSocket(
+        string $inboundHost,
+        int $inboundPort,
+        string $inboundSecurity,
+        string $outboundHost,
+        int $outboundPort,
+        string $outboundSecurity
+    ): self {
+        return new self(
+            self::TYPE_SOCKET_SPLIT,
+            null,
+            $inboundHost,
+            $inboundPort,
+            $inboundSecurity,
+            $outboundHost,
+            $outboundPort,
+            $outboundSecurity
+        );
+    }
+
+    /**
+     * Creates from array data
+     * 
+     * @since 2025.05.01
+     * 
+     * @param array $data
+     * 
+     * @return self
+     */
+    public static function fromArray(array $data): self {
+        return new self(
+            $data['type'] ?? self::TYPE_SOCKET_SINGLE,
+            $data['uri'] ?? null,
+            $data['inboundHost'] ?? $data['host'] ?? null,
+            $data['inboundPort'] ?? $data['port'] ?? null,
+            $data['inboundSecurity'] ?? $data['security'] ?? null,
+            $data['outboundHost'] ?? null,
+            $data['outboundPort'] ?? null,
+            $data['outboundSecurity'] ?? null,
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getType(): string {
+        return $this->type;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getUri(): ?string {
+        return $this->uri;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getInboundHost(): ?string {
+        return $this->inboundHost;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getInboundPort(): ?int {
+        return $this->inboundPort;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getInboundSecurity(): ?string {
+        return $this->inboundSecurity;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getOutboundHost(): ?string {
+        return $this->outboundHost ?? $this->inboundHost;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getOutboundPort(): ?int {
+        return $this->outboundPort ?? $this->inboundPort;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function getOutboundSecurity(): ?string {
+        return $this->outboundSecurity ?? $this->inboundSecurity;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function jsonSerialize(): array {
+        $data = ['type' => $this->type];
+        
+        if ($this->type === self::TYPE_URI) {
+            $data['uri'] = $this->uri;
+        } else {
+            $data['inboundHost'] = $this->inboundHost;
+            $data['inboundPort'] = $this->inboundPort;
+            $data['inboundSecurity'] = $this->inboundSecurity;
+            
+            if ($this->type === self::TYPE_SOCKET_SPLIT) {
+                $data['outboundHost'] = $this->outboundHost;
+                $data['outboundPort'] = $this->outboundPort;
+                $data['outboundSecurity'] = $this->outboundSecurity;
+            }
+        }
+        
+        return array_filter($data, fn($v) => $v !== null);
+    }
+
+}

shared/lib/Mail/Service/ServiceScope.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: Sebastian Krupinski <krupinski01@gmail.com>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace KTXF\Mail\Service;
+
+use JsonSerializable;
+
+/**
+ * Defines the scope/context of a mail service
+ * 
+ * @since 2025.05.01
+ */
+enum ServiceScope: string implements JsonSerializable {
+
+    /**
+     * System-level service for tenant-wide communications
+     * (e.g., notifications@, reports@, noreply@)
+     */
+    case System = 'system';
+
+    /**
+     * User-level service for personal mail accounts
+     * (e.g., user's own IMAP/SMTP accounts)
+     */
+    case User = 'user';
+
+    public function jsonSerialize(): string {
+        return $this->value;
+    }
+
+}