feat(mail) : MailProviderInterface + MailProviderException

src/Mail/Exception/MailProviderException.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail\Exception;
+
+use RuntimeException;
+
+final class MailProviderException extends RuntimeException
+{
+    public static function connectionFailed(string $reason): self
+    {
+        return new self(sprintf('Mail provider connection failed: %s', $reason));
+    }
+
+    public static function operationFailed(string $operation, string $reason): self
+    {
+        return new self(sprintf('Mail provider operation "%s" failed: %s', $operation, $reason));
+    }
+}

src/Mail/MailProviderInterface.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mail;
+
+use App\Mail\Dto\MailFolderDto;
+use App\Mail\Dto\MailMessageDetailDto;
+use App\Mail\Dto\MailMessageHeaderDto;
+use App\Mail\Exception\MailProviderException;
+
+interface MailProviderInterface
+{
+    /**
+     * Returns the full folder tree of the configured mailbox.
+     *
+     * @return list<MailFolderDto>
+     *
+     * @throws MailProviderException
+     */
+    public function listFolders(): array;
+
+    /**
+     * Returns a paginated list of message headers for the given folder.
+     *
+     * @return list<MailMessageHeaderDto>
+     *
+     * @throws MailProviderException
+     */
+    public function listMessages(string $folderPath, int $limit, int $offset): array;
+
+    /**
+     * Fetches the full message (headers + body + attachments list) by UID.
+     *
+     * @throws MailProviderException
+     */
+    public function fetchMessage(string $folderPath, int $uid): MailMessageDetailDto;
+
+    /**
+     * Marks a message as read or unread on the IMAP server.
+     *
+     * @throws MailProviderException
+     */
+    public function markRead(string $folderPath, int $uid, bool $read): void;
+
+    /**
+     * Marks a message as flagged (starred) or unflagged on the IMAP server.
+     *
+     * @throws MailProviderException
+     */
+    public function markFlagged(string $folderPath, int $uid, bool $flagged): void;
+
+    /**
+     * Moves a message from one folder to another on the IMAP server.
+     *
+     * @throws MailProviderException
+     */
+    public function moveMessage(string $folderPath, int $uid, string $targetFolder): void;
+
+    /**
+     * Fetches the raw binary content of an attachment by its MIME part number.
+     *
+     * @throws MailProviderException
+     */
+    public function fetchAttachment(string $folderPath, int $uid, string $partNumber): string;
+}