feat: introduce mail configuration management and SES event handling

- Added new services and DTOs to support dynamic mail configuration through `MailConfigurationService`.
- Implemented `SettingsService` tests for encrypted settings storage and retrieval.
- Introduced support for SES bounce and complaint webhook handling via `SesWebhookController`.
- Created `SesUsageRecordModel` and migration for tracking SES usage metrics.
- Integrated encrypted field support in settings pages for secure data storage.

Author: DavidMRGaona

src/app/Application/Mail/DTOs/Response/ConnectionTestResultDTO.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\DTOs\Response;
+
+final readonly class ConnectionTestResultDTO
+{
+    public function __construct(
+        public bool $success,
+        public ?int $responseTimeMs = null,
+        public ?string $errorMessage = null,
+        public ?string $serverResponse = null,
+    ) {}
+}

src/app/Application/Mail/DTOs/Response/MailConfigurationResponseDTO.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\DTOs\Response;
+
+final readonly class MailConfigurationResponseDTO
+{
+    public function __construct(
+        public bool $enabled,
+        public string $driver,
+        public string $fromAddress,
+        public string $fromName,
+        public ?string $smtpHost,
+        public ?int $smtpPort,
+        public ?string $smtpUsername,
+        public bool $hasSmtpPassword,
+        public ?string $smtpEncryption,
+        public ?int $smtpTimeout,
+        public ?string $sesRegion,
+        public ?string $sesAccessKeyId,
+        public bool $hasSesSecretAccessKey,
+        public bool $hasResendApiKey,
+        public ?int $quotaDailyLimit,
+        public ?int $quotaMonthlyLimit,
+        public ?int $quotaWarningThreshold,
+    ) {}
+}

src/app/Application/Mail/DTOs/Response/MailStatisticsResponseDTO.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\DTOs\Response;
+
+final readonly class MailStatisticsResponseDTO
+{
+    public function __construct(
+        public int $sentToday,
+        public int $sentThisMonth,
+        public int $failedToday,
+        public int $failedThisMonth,
+        public float $deliveryRate,
+    ) {}
+}

src/app/Application/Mail/DTOs/Response/QuotaStatusResponseDTO.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\DTOs\Response;
+
+final readonly class QuotaStatusResponseDTO
+{
+    public function __construct(
+        public int $dailyUsed,
+        public int $dailyLimit,
+        public int $monthlyUsed,
+        public int $monthlyLimit,
+        public float $percentageUsed,
+        public bool $isWarning,
+        public bool $isLimitReached,
+    ) {}
+}

src/app/Application/Mail/DTOs/UpdateMailConfigurationDTO.php

@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\DTOs;
+
+final readonly class UpdateMailConfigurationDTO
+{
+    public function __construct(
+        public bool $enabled,
+        public string $driver,
+        public string $fromAddress,
+        public string $fromName,
+        public ?string $smtpHost = null,
+        public ?int $smtpPort = null,
+        public ?string $smtpUsername = null,
+        public ?string $smtpPassword = null,
+        public ?string $smtpEncryption = null,
+        public ?int $smtpTimeout = null,
+        public ?string $sesRegion = null,
+        public ?string $sesAccessKeyId = null,
+        public ?string $sesSecretAccessKey = null,
+        public ?string $resendApiKey = null,
+        public ?int $quotaDailyLimit = null,
+        public ?int $quotaMonthlyLimit = null,
+        public ?int $quotaWarningThreshold = null,
+    ) {}
+
+    /**
+     * @param  array<string, mixed>  $data
+     */
+    public static function fromArray(array $data): self
+    {
+        return new self(
+            enabled: (bool) ($data['mail_enabled'] ?? false),
+            driver: (string) ($data['mail_driver'] ?? 'smtp'),
+            fromAddress: (string) ($data['mail_from_address'] ?? ''),
+            fromName: (string) ($data['mail_from_name'] ?? ''),
+            smtpHost: isset($data['mail_smtp_host']) ? (string) $data['mail_smtp_host'] : null,
+            smtpPort: isset($data['mail_smtp_port']) ? (int) $data['mail_smtp_port'] : null,
+            smtpUsername: isset($data['mail_smtp_username']) ? (string) $data['mail_smtp_username'] : null,
+            smtpPassword: isset($data['mail_smtp_password']) ? (string) $data['mail_smtp_password'] : null,
+            smtpEncryption: isset($data['mail_smtp_encryption']) ? (string) $data['mail_smtp_encryption'] : null,
+            smtpTimeout: isset($data['mail_smtp_timeout']) ? (int) $data['mail_smtp_timeout'] : null,
+            sesRegion: isset($data['mail_ses_region']) ? (string) $data['mail_ses_region'] : null,
+            sesAccessKeyId: isset($data['mail_ses_access_key_id']) ? (string) $data['mail_ses_access_key_id'] : null,
+            sesSecretAccessKey: isset($data['mail_ses_secret_access_key']) ? (string) $data['mail_ses_secret_access_key'] : null,
+            resendApiKey: isset($data['mail_resend_api_key']) ? (string) $data['mail_resend_api_key'] : null,
+            quotaDailyLimit: isset($data['mail_quota_daily_limit']) ? (int) $data['mail_quota_daily_limit'] : null,
+            quotaMonthlyLimit: isset($data['mail_quota_monthly_limit']) ? (int) $data['mail_quota_monthly_limit'] : null,
+            quotaWarningThreshold: isset($data['mail_quota_warning_threshold']) ? (int) $data['mail_quota_warning_threshold'] : null,
+        );
+    }
+}

src/app/Application/Mail/Services/EmailQuotaServiceInterface.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\Services;
+
+use App\Application\Mail\DTOs\Response\QuotaStatusResponseDTO;
+
+interface EmailQuotaServiceInterface
+{
+    public function canSendEmail(): bool;
+
+    public function getQuotaStatus(): QuotaStatusResponseDTO;
+}

src/app/Application/Mail/Services/MailConfigurationServiceInterface.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\Services;
+
+use App\Application\Mail\DTOs\Response\MailConfigurationResponseDTO;
+use App\Application\Mail\DTOs\UpdateMailConfigurationDTO;
+use App\Domain\Mail\Enums\MailDriver;
+
+interface MailConfigurationServiceInterface
+{
+    /**
+     * Get the current mail configuration (passwords masked).
+     */
+    public function getConfiguration(): MailConfigurationResponseDTO;
+
+    /**
+     * Update the mail configuration.
+     */
+    public function updateConfiguration(UpdateMailConfigurationDTO $dto): void;
+
+    /**
+     * Apply stored settings to Laravel's runtime config.
+     */
+    public function applyToRuntime(): void;
+
+    /**
+     * Check if mail sending is enabled.
+     */
+    public function isMailEnabled(): bool;
+
+    /**
+     * Get the currently active mail driver.
+     */
+    public function getActiveDriver(): MailDriver;
+}

src/app/Application/Mail/Services/MailStatisticsServiceInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\Services;
+
+use App\Application\Mail\DTOs\Response\MailStatisticsResponseDTO;
+
+interface MailStatisticsServiceInterface
+{
+    public function getStats(): MailStatisticsResponseDTO;
+}

src/app/Application/Mail/Services/MailTestServiceInterface.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Application\Mail\Services;
+
+use App\Application\Mail\DTOs\Response\ConnectionTestResultDTO;
+
+interface MailTestServiceInterface
+{
+    /**
+     * Test SMTP connection by opening a socket and performing EHLO.
+     */
+    public function testSmtpConnection(): ConnectionTestResultDTO;
+
+    /**
+     * Send a test email to verify the full mail pipeline.
+     */
+    public function sendTestEmail(string $to): ConnectionTestResultDTO;
+}

src/app/Application/Services/SettingsServiceInterface.php

@@ -23,6 +23,16 @@ public function set(string $key, string $value): void;
      */
     public function getLocationSettings(): LocationSettingsDTO;
 
+    /**
+     * Get an encrypted setting, decrypting it on read.
+     */
+    public function getEncrypted(string $key, mixed $default = null): mixed;
+
+    /**
+     * Set a setting, encrypting the value before storage.
+     */
+    public function setEncrypted(string $key, string $value): void;
+
     /**
      * Clear the settings cache.
      */