Beautiful Open-Source Form Builder
Track email integration outcomes and SES delivery per recipient (#1299)
Julien Nahum94c2edc4a8a6
diff --git a/.github/workflows/ci-cd.yml b/.github/workflows/ci-cd.ymlindex 43ac494e3..2c164a8f6 100644--- a/.github/workflows/ci-cd.yml+++ b/.github/workflows/ci-cd.yml@@ -98,6 +98,9 @@ jobs:- name: Run ESLintrun: npm run lint+ - name: Test integration email event rendering+ run: npm run test:email-events+- name: Run front-end testsrun: npm run test -- --rundiff --git a/api/.env.example b/api/.env.exampleindex c90a9f69d..db1556916 100644--- a/api/.env.example+++ b/api/.env.example@@ -178,3 +178,6 @@ LICENSE_API_ENDPOINT=https://api.opnform.comLICENSE_CHECKOUT_SUCCESS_URL=https://opnform.com/self-hosted/checkout/successLICENSE_CHECKOUT_CANCEL_URL=https://opnform.com/self-hosted/checkout/canceledLICENSE_PORTAL_RETURN_URL=https://opnform.com/self-hosted/checkout/success++# Exact SES/SNS topic ARNs allowed to update integration email events (comma-separated).+EMAIL_TRACKING_SNS_TOPICS=diff --git a/api/app/Http/Controllers/Forms/Integration/FormIntegrationsEventController.php b/api/app/Http/Controllers/Forms/Integration/FormIntegrationsEventController.phpindex 40849588b..765da767e 100644--- a/api/app/Http/Controllers/Forms/Integration/FormIntegrationsEventController.php+++ b/api/app/Http/Controllers/Forms/Integration/FormIntegrationsEventController.php@@ -19,7 +19,7 @@ class FormIntegrationsEventController extends Controller$formIntegration = $form->integrations()->findOrFail((int) $integrationid);return FormIntegrationsEventResource::collection(- $formIntegration->events()->orderByDesc('created_at')->get()+ $formIntegration->events()->with('integration')->orderByDesc('created_at')->get());}}diff --git a/api/app/Http/Controllers/Integrations/SesIntegrationFeedbackController.php b/api/app/Http/Controllers/Integrations/SesIntegrationFeedbackController.phpnew file mode 100644index 000000000..6d0326e38--- /dev/null+++ b/api/app/Http/Controllers/Integrations/SesIntegrationFeedbackController.php@@ -0,0 +1,54 @@+<?php++namespace App\Http\Controllers\Integrations;++use App\Http\Controllers\Controller;+use App\Service\Integrations\EmailDeliveryTracker;+use Aws\Sns\Message;+use Aws\Sns\MessageValidator;+use Illuminate\Http\Request;+use Illuminate\Support\Facades\Http;+use Illuminate\Support\Facades\Log;++class SesIntegrationFeedbackController extends Controller+{+ public function __invoke(Request $request, MessageValidator $validator, EmailDeliveryTracker $tracker)+ {+ abort_if(strlen($request->getContent()) > 300000, 413);+ $body = json_decode($request->getContent(), true);+ abort_unless(is_array($body), 422);+ abort_unless(in_array($body['TopicArn'] ?? '', config('email-tracking.sns_topics', []), true), 403);+ foreach (['Type', 'Message', 'MessageId', 'Timestamp', 'Signature', 'SignatureVersion', 'TopicArn', 'SigningCertURL'] as $field) {+ abort_unless(is_string($body[$field] ?? null), 403);+ }+ foreach (['Subject', 'SubscribeURL', 'Token', 'UnsubscribeURL'] as $field) {+ abort_if(isset($body[$field]) && !is_string($body[$field]), 403);+ }+ try {+ $validator->validate(new Message($body));+ } catch (\Illuminate\Http\Client\ConnectionException|\Illuminate\Http\Client\RequestException $e) {+ abort(503, 'SNS certificate temporarily unavailable.');+ } catch (\Aws\Sns\Exception\InvalidSnsMessageException|\InvalidArgumentException $e) {+ abort(403, 'Invalid SNS signature.');+ }+ if (($body['Type'] ?? '') === 'SubscriptionConfirmation') {+ // Construct the AWS endpoint ourselves; never follow a supplied SubscribeURL.+ preg_match('/^arn:aws:sns:([a-z0-9-]+):[0-9]{12}:[A-Za-z0-9_-]+$/', $body['TopicArn'], $matches);+ abort_unless(isset($matches[1]) && is_string($body['Token'] ?? null), 422);+ Http::timeout(10)->withOptions(['allow_redirects' => false])+ ->get('https://sns.'.$matches[1].'.amazonaws.com/', [+ 'Action' => 'ConfirmSubscription', 'Version' => '2010-03-31',+ 'TopicArn' => $body['TopicArn'], 'Token' => $body['Token'],+ ])->throw();+ return response()->json(['ok' => true]);+ }+ abort_unless(($body['Type'] ?? '') === 'Notification', 422);+ abort_unless(is_string($body['Message'] ?? null), 422);+ $payload = json_decode($body['Message'], true);+ abort_unless(is_array($payload), 422);+ if (!$tracker->feedback($payload)) {+ Log::info('SES feedback did not match a retained integration email', ['sns_message_id' => $body['MessageId'] ?? null]);+ }+ return response()->json(['ok' => true]);+ }+}diff --git a/api/app/Http/Resources/FormIntegrationsEventResource.php b/api/app/Http/Resources/FormIntegrationsEventResource.phpindex 0d2be4b16..d65d06048 100644--- a/api/app/Http/Resources/FormIntegrationsEventResource.php+++ b/api/app/Http/Resources/FormIntegrationsEventResource.php@@ -17,6 +17,10 @@ class FormIntegrationsEventResource extends JsonResourcereturn ['date' => date('Y-m-d H:i', strtotime($this->created_at)),'status' => ucfirst($this->status),+ 'tracking_id' => $this->tracking_id,+ 'email_tracking' => $this->tracking_id !== null,+ 'legacy_email' => !$this->tracking_id && $this->integration?->integration_id === 'email',+ 'updated_at' => $this->updated_at?->toIso8601String(),'data' => $this->data];}diff --git a/api/app/Integrations/Handlers/AbstractIntegrationHandler.php b/api/app/Integrations/Handlers/AbstractIntegrationHandler.phpindex 0779310af..30b7154a1 100644--- a/api/app/Integrations/Handlers/AbstractIntegrationHandler.php+++ b/api/app/Integrations/Handlers/AbstractIntegrationHandler.php@@ -85,7 +85,7 @@ abstract class AbstractIntegrationHandlerreturn self::formatWebhookData($this->form, $this->submissionData, $this->submissionMeta);}- final public function run(): void+ public function run(): void{try {$this->handle();diff --git a/api/app/Integrations/Handlers/EmailIntegration.php b/api/app/Integrations/Handlers/EmailIntegration.phpindex d8cd2eb49..fb2b74bfd 100644--- a/api/app/Integrations/Handlers/EmailIntegration.php+++ b/api/app/Integrations/Handlers/EmailIntegration.php@@ -4,9 +4,7 @@ namespace App\Integrations\Handlers;use App\Models\Forms\Form;use App\Models\Integration\FormIntegration;-use App\Notifications\Forms\FormEmailNotification;use Illuminate\Support\Facades\Log;-use Illuminate\Support\Facades\Notification;use App\Open\MentionParser;use App\Service\Billing\Feature;use App\Service\Forms\FormSubmissionFormatter;@@ -16,6 +14,8 @@ use Illuminate\Support\Facades\Auth;class EmailIntegration extends AbstractIntegrationHandler{+ use TracksEmailIntegration;+public const RISKY_USERS_LIMIT = 120;public const MAX_PDF_ATTACHMENTS = 3;@@ -80,17 +80,7 @@ class EmailIntegration extends AbstractIntegrationHandlerprotected function shouldRun(): bool{- // Check basic conditions first- if (!$this->integrationData?->send_to || !parent::shouldRun()) {- return false;- }-- // Only check risk limit if integration would otherwise run- if ($this->riskLimitReached()) {- throw new \Exception('Email integration temporarily blocked due to account restrictions. Please contact support to unblock your account or upgrade to a Pro plan to continue sending emails.');- }-- return true;+ return $this->integrationData?->send_to && parent::shouldRun();}// To avoid phishing abuse we limit this feature for risky users@@ -113,7 +103,21 @@ class EmailIntegration extends AbstractIntegrationHandlerpublic function handle(): void{+ if (!$this->emailTrackingId) {+ $this->run();+ return;+ }if (!$this->shouldRun()) {+ $this->emailSkipped('No email sent: integration conditions were not met or recipients were not configured.');+ return;+ }++ if ($this->riskLimitReached()) {+ app(\App\Service\Integrations\EmailDeliveryTracker::class)->outcome(+ $this->emailTrackingId,+ 'error',+ 'Email sending is blocked by account restrictions. Contact support to review the account.'+ );return;}@@ -129,20 +133,6 @@ class EmailIntegration extends AbstractIntegrationHandler$sendTo = $this->integrationData?->send_to;}- $recipients = collect(preg_split("/\r\n|\n|\r/", $sendTo))- ->filter(function ($email) {- return filter_var($email, FILTER_VALIDATE_EMAIL);- });- Log::info('Sending email notification', [- 'recipients' => $recipients->toArray(),- 'form_id' => $this->form->id,- 'form_slug' => $this->form->slug,- ]);-- $recipients->each(function ($subscriber) {- Notification::route('mail', $subscriber)->notify(- new FormEmailNotification($this->event, $this->integrationData)- );- });+ $this->sendTrackedEmails(preg_split("/\r\n|\n|\r/", $sendTo));}}diff --git a/api/app/Integrations/Handlers/TracksEmailIntegration.php b/api/app/Integrations/Handlers/TracksEmailIntegration.phpnew file mode 100644index 000000000..653aaa9ba--- /dev/null+++ b/api/app/Integrations/Handlers/TracksEmailIntegration.php@@ -0,0 +1,80 @@+<?php++namespace App\Integrations\Handlers;++use App\Service\Integrations\EmailDeliveryTracker;+use Illuminate\Support\Facades\Notification;+use Illuminate\Support\Str;+use App\Notifications\Forms\FormEmailNotification;++trait TracksEmailIntegration+{+ private ?string $emailTrackingId = null;+ private bool $emailSendAttempted = false;++ public function run(): void+ {+ $this->emailTrackingId = (string) Str::uuid();+ $this->formIntegration->events()->createQuietly([+ 'tracking_id' => $this->emailTrackingId,+ 'status' => 'processing',+ 'data' => [+ 'submission_id' => $this->submissionData['submission_id'] ?? null,+ 'notion_page_id' => $this->submissionData['notion_page_id'] ?? null,+ 'email' => ['version' => 1, 'recipients' => []],+ ],+ ]);+ try {+ $this->handle();+ } catch (\Throwable $e) {+ try {+ app(EmailDeliveryTracker::class)->outcome(+ $this->emailTrackingId,+ $this->emailSendAttempted ? 'unknown' : 'error',+ $this->emailSendAttempted+ ? 'Email processing was interrupted. Review recipient outcomes; do not retry blindly.'+ : 'The application could not prepare the email. Contact support with this event ID.'+ );+ } catch (\Throwable $trackingException) {+ // A database outage after a possible send must not replay the notification job.+ \Illuminate\Support\Facades\Log::error('Could not persist interrupted email outcome', [+ 'tracking_id' => $this->emailTrackingId, 'exception_type' => get_class($trackingException),+ ]);+ }+ \Illuminate\Support\Facades\Log::error('Email integration processing failed', [+ 'tracking_id' => $this->emailTrackingId, 'exception_type' => get_class($e),+ ]);+ }+ }++ private function emailSkipped(string $reason): void+ {+ if ($this->emailTrackingId) {+ app(EmailDeliveryTracker::class)->outcome($this->emailTrackingId, 'skipped', $reason);+ }+ }++ private function sendTrackedEmails(array $addresses): void+ {+ $tracker = app(EmailDeliveryTracker::class);+ foreach ($tracker->prepare($this->emailTrackingId, $addresses) as $recipientId => $recipient) {+ if ($recipient['status'] === 'invalid') {+ continue;+ }+ $tracker->recipient($this->emailTrackingId, $recipientId, ['status' => 'sending']);+ try {+ $notification = new FormEmailNotification($this->event, $this->integrationData);+ $notification->emailTracking = ['event' => $this->emailTrackingId, 'recipient' => $recipientId];+ $this->emailSendAttempted = true;+ Notification::route('mail', $recipient['address'])->notify($notification);+ // If NotificationSending vetoed the send there is no NotificationSent event.+ $record = \App\Models\Integration\FormIntegrationsEvent::where('tracking_id', $this->emailTrackingId)->first();+ if (data_get($record?->data, "email.recipients.$recipientId.status") === 'sending') {+ $tracker->recipient($this->emailTrackingId, $recipientId, ['status' => 'blocked', 'reason' => 'The application cancelled the notification.']);+ }+ } catch (\Throwable $e) {+ $tracker->failure($this->emailTrackingId, $recipientId, $e);+ }+ }+ }+}diff --git a/api/app/Models/Integration/FormIntegrationsEvent.php b/api/app/Models/Integration/FormIntegrationsEvent.phpindex eff41425e..68569c725 100644--- a/api/app/Models/Integration/FormIntegrationsEvent.php+++ b/api/app/Models/Integration/FormIntegrationsEvent.php@@ -15,6 +15,7 @@ class FormIntegrationsEvent extends Modelprotected $fillable = ['integration_id',+ 'tracking_id','status','data'];diff --git a/api/app/Notifications/Forms/FormEmailNotification.php b/api/app/Notifications/Forms/FormEmailNotification.phpindex 9d871e73b..4a935b243 100644--- a/api/app/Notifications/Forms/FormEmailNotification.php+++ b/api/app/Notifications/Forms/FormEmailNotification.php@@ -34,6 +34,8 @@ class FormEmailNotification extends Notification];public FormSubmitted $event;+ public ?string $emailTransport = null;+ public ?array $emailTracking = null;private ?array $computedValues = null;private array $inlineImages = [];private int $inlineImageBytes = 0;@@ -114,7 +116,14 @@ class FormEmailNotification extends Notificationpublic function toMail($notifiable){$mail = (new MailMessage())- ->mailer($this->getMailer())+ ->mailer($mailer = $this->getMailer())+ ->withSymfonyMessage(function ($message) use ($mailer) {+ $this->emailTransport = config("mail.mailers.$mailer.transport", $mailer);+ if ($this->emailTracking) {+ $message->getHeaders()->addTextHeader('X-Form-Email-Event-ID', $this->emailTracking['event']);+ $message->getHeaders()->addTextHeader('X-Form-Email-Recipient-ID', $this->emailTracking['recipient']);+ }+ })->replyTo($this->getReplyToEmail($this->event->form->creator->email))->from($this->getFromEmail(), $this->getSenderName())->subject($this->getSubject());diff --git a/api/app/Providers/AppServiceProvider.php b/api/app/Providers/AppServiceProvider.phpindex 9197bb7f6..d6cee5cdc 100644--- a/api/app/Providers/AppServiceProvider.php+++ b/api/app/Providers/AppServiceProvider.php@@ -105,6 +105,15 @@ class AppServiceProvider extends ServiceProvider*/public function register(){+ $this->app->bind(\Aws\Sns\MessageValidator::class, fn () => new \Aws\Sns\MessageValidator(+ fn ($url) => \Illuminate\Support\Facades\Cache::remember(+ 'sns-signing-cert:'.hash('sha256', $url),+ 3600,+ fn () => \Illuminate\Support\Facades\Http::timeout(5)->withOptions(['allow_redirects' => false])+ ->get($url)->throw()->body()+ )+ ));+$this->app->singleton(StripeClient::class, function () {return new StripeClient(config('cashier.secret'));});diff --git a/api/app/Providers/EventServiceProvider.php b/api/app/Providers/EventServiceProvider.phpindex fa31572f9..abe10f8cb 100644--- a/api/app/Providers/EventServiceProvider.php+++ b/api/app/Providers/EventServiceProvider.php@@ -38,6 +38,7 @@ class EventServiceProvider extends ServiceProvider* @var array*/protected $listen = [+ \Illuminate\Notifications\Events\NotificationSent::class => [\App\Service\Integrations\EmailDeliveryTracker::class],Registered::class => [SendEmailVerificationNotification::class,],diff --git a/api/app/Service/Integrations/EmailDeliveryTracker.php b/api/app/Service/Integrations/EmailDeliveryTracker.phpnew file mode 100644index 000000000..dbb71e624--- /dev/null+++ b/api/app/Service/Integrations/EmailDeliveryTracker.php@@ -0,0 +1,257 @@+<?php++namespace App\Service\Integrations;++use App\Models\Integration\FormIntegrationsEvent;+use Illuminate\Notifications\Events\NotificationSent;+use Illuminate\Support\Facades\DB;+use Illuminate\Support\Str;++/** Updates the existing integration event; never sends or retries email. */+class EmailDeliveryTracker+{+ public function handle(NotificationSent $event): void+ {+ $context = $event->notification->emailTracking ?? null;+ if ($event->channel !== 'mail' || !$context) {+ return;+ }+ $message = $event->response?->getSymfonySentMessage()->getOriginalMessage();+ $sesId = $message?->getHeaders()->get('X-SES-Message-ID')?->getBodyAsString();+ $transport = $event->notification->emailTransport ?? 'unknown';+ $status = match (true) {+ $event->response === null => 'blocked',+ in_array($transport, ['log', 'array']) => 'not_sent',+ (bool) $sesId || in_array($transport, ['smtp', 'ses', 'ses-v2', 'mailgun', 'postmark', 'sendmail', 'resend']) => 'accepted',+ default => 'unknown', // A failover/custom driver can return a response after only logging the email.+ };+ $this->recipient($context['event'], $context['recipient'], [+ 'status' => $status,+ 'provider' => $sesId ? 'ses' : $transport,+ 'provider_message_id' => $sesId,+ 'reason' => match ($status) {+ 'blocked' => 'The application cancelled the email before transport acceptance.',+ 'not_sent' => 'The configured mail transport does not deliver email.',+ 'unknown' => 'The transport completed, but its delivery capability could not be confirmed.',+ default => 'Accepted by the mail transport; delivery is not yet confirmed.',+ },+ ]);+ }++ public function failure(string $id, string $recipient, \Throwable $exception): void+ {+ $code = null;+ for ($cause = $exception; $cause; $cause = $cause->getPrevious()) {+ if ($cause instanceof \Aws\Exception\AwsException) {+ $code = $cause->getAwsErrorCode();+ break;+ }+ }+ $reasons = [+ 'MessageRejected' => 'SES rejected the message. Check the sender identity and account sending restrictions.',+ 'MailFromDomainNotVerifiedException' => 'SES rejected the message because the MAIL FROM domain is not verified.',+ 'ConfigurationSetDoesNotExistException' => 'SES rejected the message because its configuration set does not exist.',+ 'AccountSendingPausedException' => 'SES email sending is paused for this account.',+ 'ConfigurationSetSendingPausedException' => 'SES sending is paused for this configuration set.',+ 'Throttling' => 'SES refused the send because its sending limit was exceeded.',+ 'ThrottlingException' => 'SES refused the send because its sending limit was exceeded.',+ 'AccessDenied' => 'SES refused the send because the application lacks permission.',+ 'AccessDeniedException' => 'SES refused the send because the application lacks permission.',+ ];+ $rejected = isset($reasons[$code ?? '']);+ $this->recipient($id, $recipient, [+ 'status' => $rejected ? 'rejected' : 'unknown',+ 'reason' => $rejected ? $reasons[$code] : 'The send did not complete normally. Delivery is uncertain; do not retry blindly.',+ 'reason_code' => $rejected ? $code : null,+ 'exception_type' => class_basename($exception),+ ]);+ }++ public function prepare(string $id, array $addresses): array+ {+ $recipients = [];+ foreach (array_unique(array_filter(array_map('trim', $addresses), fn ($address) => $address !== '')) as $address) {+ $valid = (bool) filter_var($address, FILTER_VALIDATE_EMAIL);+ $recipients[(string) Str::uuid()] = [+ 'address' => $address,+ 'status' => $valid ? 'pending' : 'invalid',+ 'reason' => $valid ? null : 'Invalid recipient address. No email was sent.',+ 'updated_at' => now()->toIso8601String(),+ ];+ }+ $this->update($id, function (&$data) use ($recipients) {+ $data['email']['recipients'] = $recipients;+ if (!$recipients) {+ $data['email']['reason'] = 'No recipient address was resolved. No email was sent.';+ $data['email']['outcome'] = 'error';+ }+ });+ return $recipients;+ }++ public function recipient(string $id, string $recipient, array $changes): void+ {+ $this->update($id, function (&$data) use ($recipient, $changes) {+ if (!isset($data['email']['recipients'][$recipient])) {+ return;+ }+ $current = &$data['email']['recipients'][$recipient];+ // Acceptance is positive evidence even if a later listener or persistence step fails.+ if (($current['status'] ?? null) === 'accepted' && in_array($changes['status'] ?? null, ['unknown', 'blocked', 'rejected'])) {+ return;+ }+ if (isset($changes['status'])) {+ $current['timeline'][$changes['status']] ??= now()->toIso8601String();+ }+ // Feedback can arrive before NotificationSent. Preserve its outcome and correlation.+ if (isset($current['feedback'])) {+ unset($changes['status'], $changes['reason'], $changes['reason_code']);+ if (!empty($current['provider_message_id'])) {+ unset($changes['provider_message_id'], $changes['provider']);+ }+ }+ $current = array_merge($current, $changes, ['updated_at' => now()->toIso8601String()]);+ });+ }++ public function outcome(string $id, string $status, string $reason, array $metadata = []): void+ {+ $this->update($id, function (&$data) use ($status, $reason, $metadata) {+ $data = array_merge($data, $metadata);+ $data['email']['outcome'] = $status;+ $data['email']['reason'] = $reason;+ });+ }++ public function feedback(array $payload): bool+ {+ $type = strtolower(is_string($payload['notificationType'] ?? $payload['eventType'] ?? null)+ ? ($payload['notificationType'] ?? $payload['eventType']) : '');+ if (!in_array($type, ['delivery', 'bounce', 'complaint'])) {+ return false;+ }+ $rules = [+ 'mail' => 'required|array',+ 'mail.messageId' => 'required|string|max:1024',+ 'mail.headers' => 'required|array|max:200',+ 'mail.headers.*' => 'required|array',+ 'mail.headers.*.name' => 'required|string|max:256',+ 'mail.headers.*.value' => 'present|string|max:10000',+ $type => 'required|array',+ "$type.timestamp" => 'sometimes|string|max:128',+ ];+ $list = match ($type) {+ 'delivery' => 'recipients', 'bounce' => 'bouncedRecipients', 'complaint' => 'complainedRecipients',+ };+ $rules["$type.$list"] = 'required|array|max:1000';+ $rules["$type.$list.*"] = $type === 'delivery' ? 'required|string|max:320' : 'required|array';+ if ($type !== 'delivery') {+ $rules["$type.$list.*.emailAddress"] = 'required|string|max:320';+ }+ foreach (['bounceType', 'bounceSubType', 'complaintFeedbackType'] as $field) {+ $rules["$type.$field"] = 'sometimes|string|max:128';+ }+ if (\Illuminate\Support\Facades\Validator::make($payload, $rules)->fails()) {+ return false;+ }+ $headers = [];+ foreach ($payload['mail']['headers'] ?? [] as $header) {+ $headers[strtolower($header['name'] ?? '')] = $header['value'] ?? '';+ }+ $id = $headers['x-form-email-event-id'] ?? '';+ $recipientId = $headers['x-form-email-recipient-id'] ?? '';+ if (!Str::isUuid($id) || !Str::isUuid($recipientId)) {+ return false;+ }+ $section = $payload[$type] ?? [];+ $addresses = match ($type) {+ 'delivery' => $section['recipients'] ?? [],+ 'bounce' => array_column($section['bouncedRecipients'] ?? [], 'emailAddress'),+ 'complaint' => array_column($section['complainedRecipients'] ?? [], 'emailAddress'),+ default => [],+ };+ $matched = false;+ $this->update($id, function (&$data) use ($recipientId, $type, $section, $addresses, $payload, &$matched) {+ if (!isset($data['email']['recipients'][$recipientId])) {+ return;+ }+ $recipient = &$data['email']['recipients'][$recipientId];+ if (!in_array($recipient['address'], $addresses, true)) {+ return;+ }+ $messageId = $payload['mail']['messageId'] ?? null;+ if (!$messageId || (!empty($recipient['provider_message_id']) && $recipient['provider_message_id'] !== $messageId)) {+ return;+ }+ $matched = true;+ if (isset($recipient['feedback'][$type])) {+ return;+ }+ // One immutable fact per feedback type. Duplicates and out-of-order delivery are harmless.+ $recipient['feedback'][$type] ??= [+ 'at' => $section['timestamp'] ?? null,+ 'received_at' => now()->toIso8601String(),+ 'type' => $type === 'bounce' ? ($section['bounceType'] ?? null) : ($section['complaintFeedbackType'] ?? null),+ 'subtype' => $section['bounceSubType'] ?? null,+ ];+ $recipient['provider'] = 'ses';+ $recipient['provider_message_id'] = $messageId;+ $recipient['status'] = isset($recipient['feedback']['complaint']) ? 'complained' : (isset($recipient['feedback']['bounce']) ? 'bounced' : 'delivered');+ $recipient['reason'] = match ($recipient['status']) {+ 'complained' => 'The recipient reported this email as spam.',+ 'bounced' => 'Email delivery failed. Check the bounce type before sending again.',+ default => 'Accepted by the receiving mail server. Inbox placement is not guaranteed.',+ };+ $recipient['updated_at'] = now()->toIso8601String();+ });+ return $matched;+ }++ private function update(string $id, callable $change): void+ {+ DB::transaction(function () use ($id, $change) {+ $event = FormIntegrationsEvent::where('tracking_id', $id)->lockForUpdate()->first();+ if (!$event) {+ return; // The integration or its retained history may have been deleted.+ }+ $data = json_decode(json_encode($event->data), true);+ $before = $data;+ $change($data);+ if ($data === $before) {+ return;+ }+ $statuses = array_column($data['email']['recipients'] ?? [], 'status');+ $status = $data['email']['outcome'] ?? 'processing';+ if ($statuses) {+ $status = match (true) {+ (bool) array_intersect($statuses, ['invalid', 'blocked', 'not_sent', 'rejected', 'bounced', 'complained']) => 'error',+ in_array('unknown', $statuses) || (+ ($data['email']['outcome'] ?? null) === 'unknown'+ && array_intersect($statuses, ['pending', 'sending'])+ ) => 'unknown',+ (bool) array_intersect($statuses, ['pending', 'sending']) => 'processing',+ count(array_unique($statuses)) === 1 && $statuses[0] === 'delivered' => 'delivered',+ default => 'accepted',+ };+ }+ $notifyFailure = $status === 'error' && empty($data['email']['failure_notification_attempted']);+ if ($notifyFailure) {+ $data['email']['failure_notification_attempted'] = true;+ }+ $event->update(['data' => $data, 'status' => $status]);+ if ($notifyFailure) {+ DB::afterCommit(function () use ($event) {+ try {+ \App\Events\Models\FormIntegrationsEventCreated::dispatch($event);+ } catch (\Throwable $exception) {+ // Alert delivery must never interrupt the actual recipient sends or SNS acknowledgement.+ \Illuminate\Support\Facades\Log::error('Integration failure alert could not be queued', [+ 'tracking_id' => $event->tracking_id,+ 'exception_type' => get_class($exception),+ ]);+ }+ });+ }+ });+ }+}diff --git a/api/composer.json b/api/composer.jsonindex 7c13884aa..3c1602815 100644--- a/api/composer.json+++ b/api/composer.json@@ -14,6 +14,7 @@"require": {"php": "^8.3","ext-json": "*",+ "aws/aws-php-sns-message-validator": "^1.10","aws/aws-sdk-php": "*","doctrine/dbal": "*","enshrined/svg-sanitize": "^0.22",diff --git a/api/composer.lock b/api/composer.lockindex 3ec2e2f8a..88fd0028e 100644--- a/api/composer.lock+++ b/api/composer.lock@@ -4,7 +4,7 @@"Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies","This file is @generated automatically"],- "content-hash": "bc379d303aea32fd8c42afd5db155ba1",+ "content-hash": "251117e5c7caf5708266268465e60c91","packages": [{"name": "aws/aws-crt-php",@@ -60,6 +60,65 @@},"time": "2024-10-18T22:15:13+00:00"},+ {+ "name": "aws/aws-php-sns-message-validator",+ "version": "1.10.2",+ "source": {+ "type": "git",+ "url": "https://github.com/aws/aws-php-sns-message-validator.git",+ "reference": "dc6abc2dfe30115f39c5196c7543b9509f511bb8"+ },+ "dist": {+ "type": "zip",+ "url": "https://api.github.com/repos/aws/aws-php-sns-message-validator/zipball/dc6abc2dfe30115f39c5196c7543b9509f511bb8",+ "reference": "dc6abc2dfe30115f39c5196c7543b9509f511bb8",+ "shasum": ""+ },+ "require": {+ "ext-openssl": "*",+ "php": ">=8.1",+ "psr/http-message": "^2.0"+ },+ "require-dev": {+ "guzzlehttp/psr7": "^2.4.5",+ "phpunit/phpunit": "^5.6.3 || ^8.5 || ^9.5",+ "squizlabs/php_codesniffer": "^2.8.1 || ^3.13.6",+ "yoast/phpunit-polyfills": "^1.0"+ },+ "type": "library",+ "autoload": {+ "psr-4": {+ "Aws\\Sns\\": "src/"+ }+ },+ "notification-url": "https://packagist.org/downloads/",+ "license": [+ "Apache-2.0"+ ],+ "authors": [+ {+ "name": "Amazon Web Services",+ "homepage": "http://aws.amazon.com"+ }+ ],+ "description": "Amazon SNS message validation for PHP",+ "homepage": "http://aws.amazon.com/sdkforphp",+ "keywords": [+ "SNS",+ "amazon",+ "aws",+ "cloud",+ "message",+ "sdk",+ "webhooks"+ ],+ "support": {+ "forum": "https://forums.aws.amazon.com/forum.jspa?forumID=80",+ "issues": "https://github.com/aws/aws-sns-message-validator/issues",+ "source": "https://github.com/aws/aws-php-sns-message-validator/tree/1.10.2"+ },+ "time": "2026-09-03T15:26:29+00:00"+ },{"name": "aws/aws-sdk-php","version": "3.369.36",@@ -17268,5 +17327,5 @@"ext-pcntl": "8.0","ext-posix": "8.0"},- "plugin-api-version": "2.6.0"+ "plugin-api-version": "2.9.0"}diff --git a/api/config/email-tracking.php b/api/config/email-tracking.phpnew file mode 100644index 000000000..bff783360--- /dev/null+++ b/api/config/email-tracking.php@@ -0,0 +1,5 @@+<?php++return [+ 'sns_topics' => array_values(array_filter(array_map('trim', explode(',', env('EMAIL_TRACKING_SNS_TOPICS', ''))))),+];diff --git a/api/database/migrations/2026_09_22_000000_add_tracking_id_to_form_integrations_events.php b/api/database/migrations/2026_09_22_000000_add_tracking_id_to_form_integrations_events.phpnew file mode 100644index 000000000..19ca28673--- /dev/null+++ b/api/database/migrations/2026_09_22_000000_add_tracking_id_to_form_integrations_events.php@@ -0,0 +1,22 @@+<?php++use Illuminate\Database\Migrations\Migration;+use Illuminate\Database\Schema\Blueprint;+use Illuminate\Support\Facades\Schema;++return new class () extends Migration {+ public function up(): void+ {+ Schema::table('form_integrations_events', function (Blueprint $table) {+ $table->uuid('tracking_id')->nullable()->unique();+ });+ }++ public function down(): void+ {+ Schema::table('form_integrations_events', function (Blueprint $table) {+ $table->dropUnique(['tracking_id']);+ $table->dropColumn('tracking_id');+ });+ }+};diff --git a/api/routes/api.php b/api/routes/api.phpindex d597c3a48..d94b9beae 100644--- a/api/routes/api.php+++ b/api/routes/api.php@@ -576,3 +576,6 @@ Route::get('local/temp/{path}', function (Request $request, string $path) {Route::get('caddy/ask-certificate/{secret?}', [\App\Http\Controllers\CaddyController::class, 'ask'])->name('caddy.ask')->middleware(\App\Http\Middleware\CaddyRequestMiddleware::class);++Route::post('/aws/sns/ses/integration-events', \App\Http\Controllers\Integrations\SesIntegrationFeedbackController::class)+ ->withoutMiddleware(['throttle:100,1', 'throttle:150,1', 'throttle:api']);diff --git a/api/tests/Feature/Forms/EmailNotificationTest.php b/api/tests/Feature/Forms/EmailNotificationTest.phpindex de904bcc6..688595a1b 100644--- a/api/tests/Feature/Forms/EmailNotificationTest.php+++ b/api/tests/Feature/Forms/EmailNotificationTest.php@@ -755,3 +755,49 @@ function emailTinyPngBytes(): stringtrue) ?: '';}++it('tracks a real email integration from handler through SES response and subsequent delivery', function () {+ $user = $this->actingAsProUser();+ $workspace = $this->createUserWorkspace($user);+ $form = $this->createForm($user, $workspace);+ \Illuminate\Support\Facades\Event::fake([\App\Events\Models\FormIntegrationsEventCreated::class]);+ $integration = \App\Models\Integration\FormIntegration::createQuietly([+ 'form_id' => $form->id, 'integration_id' => 'email', 'status' => 'active',+ 'data' => [+ 'send_to' => "[email protected]\ninvalid-address", 'sender_name' => 'Test',+ 'subject' => 'Tracking test', 'email_content' => 'Local test only',+ 'include_submission_data' => false,+ ],+ ]);+ $raw = null;+ $ses = new \Aws\Ses\SesClient([+ 'version' => 'latest', 'region' => 'eu-west-2', 'credentials' => ['key' => 'local', 'secret' => 'local'],+ 'handler' => function ($command) use (&$raw) {+ $raw = (string) $command['RawMessage']['Data'];+ return \GuzzleHttp\Promise\Create::promiseFor(new \Aws\Result(['MessageId' => 'real-handler-ses-id']));+ },+ ]);+ config(['mail.default' => 'ses']);+ \Illuminate\Support\Facades\Mail::extend('ses', fn () => new \Illuminate\Mail\Transport\SesTransport($ses));+ \Illuminate\Support\Facades\Mail::purge('ses');+ \Illuminate\Support\Facades\Event::forget(\Illuminate\Mail\Events\MessageSending::class);+ (new \App\Integrations\Handlers\EmailIntegration(new \App\Events\Forms\FormSubmitted($form, []), $integration, []))->run();+ $event = $integration->events()->sole();+ expect($event->status)->toBe('error'); // One invalid recipient, not a global false success.+ $recipients = (array) $event->data->email->recipients;+ $recipientId = array_key_first($recipients);+ expect($recipients[$recipientId]->status)->toBe('accepted');+ expect($recipients[$recipientId]->provider_message_id)->toBe('real-handler-ses-id');+ expect($raw)->toContain('X-Form-Email-Event-ID: '.$event->tracking_id)+ ->toContain('X-Form-Email-Recipient-ID: '.$recipientId);+ app(\App\Service\Integrations\EmailDeliveryTracker::class)->feedback([+ 'notificationType' => 'Delivery',+ 'mail' => ['messageId' => 'real-handler-ses-id', 'headers' => [+ ['name' => 'X-Form-Email-Event-ID', 'value' => $event->tracking_id],+ ['name' => 'X-Form-Email-Recipient-ID', 'value' => $recipientId],+ ]],+ 'delivery' => ['recipients' => ['[email protected]']],+ ]);+ expect(data_get($event->fresh()->data, 'email.recipients.'.$recipientId.'.status'))->toBe('delivered');+ expect($integration->events()->count())->toBe(1);+});diff --git a/api/tests/TrackedEmailHarness.php b/api/tests/TrackedEmailHarness.phpnew file mode 100644index 000000000..aa1d8d611--- /dev/null+++ b/api/tests/TrackedEmailHarness.php@@ -0,0 +1,25 @@+<?php++namespace Tests;++use App\Models\Integration\FormIntegration;++class TrackedEmailHarness+{+ use \App\Integrations\Handlers\TracksEmailIntegration;++ public array $submissionData = [];+ public object $integrationData;+ public \App\Events\Forms\FormSubmitted $event;++ public function __construct(public FormIntegration $formIntegration)+ {+ $this->integrationData = (object) [];+ $this->event = new \App\Events\Forms\FormSubmitted(new \App\Models\Forms\Form(), []);+ }++ public function handle(): void+ {+ $this->sendTrackedEmails(['[email protected]', '[email protected]']);+ }+}diff --git a/api/tests/Unit/EmailDeliveryTrackingTest.php b/api/tests/Unit/EmailDeliveryTrackingTest.phpnew file mode 100644index 000000000..67de74d45--- /dev/null+++ b/api/tests/Unit/EmailDeliveryTrackingTest.php@@ -0,0 +1,337 @@+<?php++use App\Models\Integration\FormIntegration;+use App\Models\Integration\FormIntegrationsEvent;+use App\Service\Integrations\EmailDeliveryTracker;+use Tests\TrackedEmailHarness;+use Aws\Sns\MessageValidator;+use Illuminate\Database\Schema\Blueprint;+use Illuminate\Foundation\Testing\TestCase;+use Illuminate\Notifications\Events\NotificationSent;+use Illuminate\Support\Facades\Event;+use Illuminate\Support\Facades\Http;+use Illuminate\Support\Facades\Schema;+use Illuminate\Support\Str;++uses(TestCase::class);++beforeEach(function () {+ // Isolate legacy suppression tables; individual tests install their own mail veto.+ Event::forget(\Illuminate\Mail\Events\MessageSending::class);+ Event::fake([\App\Events\Models\FormIntegrationsEventCreated::class]);+ Schema::create('form_integrations_events', function (Blueprint $table) {+ $table->id();+ $table->unsignedBigInteger('integration_id');+ $table->string('status');+ $table->json('data');+ $table->timestamps();+ });+ (require database_path('migrations/2026_09_22_000000_add_tracking_id_to_form_integrations_events.php'))->up();+ $this->id = (string) Str::uuid();+ $this->event = FormIntegrationsEvent::createQuietly([+ 'integration_id' => 1, 'tracking_id' => $this->id, 'status' => 'processing',+ 'data' => ['email' => ['version' => 1, 'recipients' => []]],+ ]);+ $this->tracker = app(EmailDeliveryTracker::class);+ $this->recipients = $this->tracker->prepare($this->id, [' [email protected] ', '[email protected]']);+ $this->recipientId = array_key_first($this->recipients);+ config(['email-tracking.sns_topics' => ['arn:aws:sns:eu-west-2:123456789012:Emails']]);+ Http::preventStrayRequests();+});++function emailFeedback($test, string $type = 'Delivery'): array+{+ return [+ 'notificationType' => $type,+ 'mail' => ['messageId' => 'ses-message-id', 'headers' => [+ ['name' => 'X-Form-Email-Event-ID', 'value' => $test->id],+ ['name' => 'X-Form-Email-Recipient-ID', 'value' => $test->recipientId],+ ]],+ lcfirst($type) => match ($type) {+ 'Bounce' => ['bouncedRecipients' => [['emailAddress' => '[email protected]']], 'bounceType' => 'Permanent', 'bounceSubType' => 'Suppressed'],+ 'Complaint' => ['complainedRecipients' => [['emailAddress' => '[email protected]']], 'complaintFeedbackType' => 'abuse'],+ default => ['recipients' => ['[email protected]']],+ },+ ];+}++function snsEmailEnvelope(array $payload): array+{+ return [+ 'Type' => 'Notification', 'Message' => json_encode($payload), 'MessageId' => 'sns-id',+ 'TopicArn' => 'arn:aws:sns:eu-west-2:123456789012:Emails',+ 'Timestamp' => '2026-09-22T10:00:00Z', 'Signature' => 'invalid',+ 'SignatureVersion' => '1', 'SigningCertURL' => 'https://sns.eu-west-2.amazonaws.com/SimpleNotificationService-test.pem',+ ];+}++it('retains invalid recipients and never calls an empty list successful', function () {+ $recipients = $this->tracker->prepare($this->id, ['bad', ' [email protected] ', '[email protected]']);+ expect($recipients)->toHaveCount(2);+ expect($this->event->fresh()->status)->toBe('error');+ $this->tracker->prepare($this->id, ['']);+ expect($this->event->fresh()->status)->toBe('error');+});++it('captures the SES message ID rather than the MIME id and records SMTP acceptance', function ($transport, $sesId, $expectedStatus) {+ $email = (new \Symfony\Component\Mime\Email())->from('[email protected]')->to('[email protected]')->text('test');+ if ($sesId) {+ $email->getHeaders()->addTextHeader('X-SES-Message-ID', $sesId);+ }+ $response = new \Illuminate\Mail\SentMessage(new \Symfony\Component\Mailer\SentMessage($email, \Symfony\Component\Mailer\Envelope::create($email)));+ $notification = new class () extends \Illuminate\Notifications\Notification {+ public array $emailTracking;+ public string $emailTransport;+ };+ $notification->emailTracking = ['event' => $this->id, 'recipient' => $this->recipientId];+ $notification->emailTransport = $transport;+ $this->tracker->handle(new NotificationSent(new stdClass(), $notification, 'mail', $response));+ $recipient = data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId);+ expect($recipient->status)->toBe($expectedStatus)->and($recipient->provider_message_id)->toBe($sesId);+})->with([['ses', 'ses-message-id', 'accepted'], ['smtp', null, 'accepted'], ['log', null, 'not_sent'], ['failover', null, 'unknown']]);++it('does not treat a cancelled mail send as success', function () {+ $notification = new class () extends \Illuminate\Notifications\Notification {+ public array $emailTracking;+ };+ $notification->emailTracking = ['event' => $this->id, 'recipient' => $this->recipientId];+ $this->tracker->handle(new NotificationSent(new stdClass(), $notification, 'mail', null));+ expect(data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId.'.status'))->toBe('blocked');+});++it('preserves early feedback and prevents duplicate or late delivery from erasing a bounce or complaint', function () {+ expect($this->tracker->feedback(emailFeedback($this, 'Bounce')))->toBeTrue();+ $this->tracker->recipient($this->id, $this->recipientId, ['status' => 'accepted', 'reason' => 'accepted']);+ $this->tracker->feedback(emailFeedback($this));+ $this->tracker->feedback(emailFeedback($this, 'Bounce'));+ expect(data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId.'.status'))->toBe('bounced');+ $this->tracker->feedback(emailFeedback($this, 'Complaint'));+ $this->tracker->feedback(emailFeedback($this));+ expect(data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId.'.status'))->toBe('complained');+ Event::assertDispatchedTimes(\App\Events\Models\FormIntegrationsEventCreated::class, 1);+});++it('only reports full delivery when all recipients have delivery confirmation', function () {+ $this->tracker->feedback(emailFeedback($this));+ expect($this->event->fresh()->status)->toBe('processing');+ $other = array_key_last($this->recipients);+ $this->tracker->recipient($this->id, $other, ['status' => 'accepted']);+ expect($this->event->fresh()->status)->toBe('accepted');+ $payload = emailFeedback($this);+ $payload['mail']['headers'][1]['value'] = $other;+ $payload['delivery']['recipients'] = ['[email protected]'];+ $this->tracker->feedback($payload);+ expect($this->event->fresh()->status)->toBe('delivered');+});++it('rejects mismatched recipients and message IDs without changing the event', function () {+ $payload = emailFeedback($this);+ $payload['delivery']['recipients'] = ['[email protected]'];+ expect($this->tracker->feedback($payload))->toBeFalse();+ $this->tracker->recipient($this->id, $this->recipientId, ['provider_message_id' => 'different']);+ expect($this->tracker->feedback(emailFeedback($this)))->toBeFalse();+ expect($this->event->fresh()->status)->toBe('processing');+});++it('rejects unsigned and unauthorized SNS envelopes', function () {+ $payload = snsEmailEnvelope(emailFeedback($this));+ unset($payload['Signature']);+ $this->postJson('/aws/sns/ses/integration-events', $payload)->assertForbidden();+ $payload['TopicArn'] = 'arn:aws:sns:eu-west-2:999999999999:Attack';+ $this->postJson('/aws/sns/ses/integration-events', $payload)->assertForbidden();+ Http::assertNothingSent();+});++it('processes verified SNS envelopes including text plain AWS requests', function () {+ $validator = Mockery::mock(MessageValidator::class);+ $validator->shouldReceive('validate')->once();+ app()->instance(MessageValidator::class, $validator);+ $this->call('POST', '/aws/sns/ses/integration-events', [], [], [], ['CONTENT_TYPE' => 'text/plain'], json_encode(snsEmailEnvelope(emailFeedback($this))))->assertOk();+ expect(data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId.'.status'))->toBe('delivered');+});++it('confirms only the allowlisted SNS topic without following the supplied URL', function () {+ $validator = Mockery::mock(MessageValidator::class);+ $validator->shouldReceive('validate')->once();+ app()->instance(MessageValidator::class, $validator);+ Http::fake(['https://sns.eu-west-2.amazonaws.com/*' => Http::response('ok')]);+ $body = snsEmailEnvelope([]);+ $body['Type'] = 'SubscriptionConfirmation';+ $body['Token'] = 'signed-token';+ $body['SubscribeURL'] = 'http://localhost/internal';+ $this->postJson('/aws/sns/ses/integration-events', $body)->assertOk();+ Http::assertSentCount(1);+ Http::assertSent(fn ($request) => str_starts_with($request->url(), 'https://sns.eu-west-2.amazonaws.com/'));+});++it('keeps a timeout visible and continues other recipients without replaying the accepted one', function () {+ $integration = new FormIntegration();+ $integration->id = 7;+ $call = 0;+ \Illuminate\Support\Facades\Notification::shouldReceive('send')->twice()->andReturnUsing(function ($notifiable, $notification) use (&$call) {+ $call++;+ if ($call === 1) {+ throw new RuntimeException('secret SMTP payload');+ }+ app(EmailDeliveryTracker::class)->recipient($notification->emailTracking['event'], $notification->emailTracking['recipient'], ['status' => 'accepted']);+ });+ (new TrackedEmailHarness($integration))->run();+ $event = FormIntegrationsEvent::where('integration_id', 7)->sole();+ $states = array_map(fn ($recipient) => $recipient->status, (array) $event->data->email->recipients);+ expect(array_values($states))->toBe(['unknown', 'accepted']);+ expect($event->status)->toBe('unknown')->and(json_encode($event->data))->not->toContain('secret SMTP payload');+});++it('records a notification veto instead of false success', function () {+ $integration = new FormIntegration();+ $integration->id = 7;+ \Illuminate\Support\Facades\Notification::shouldReceive('send')->twice()->andReturnNull();+ (new TrackedEmailHarness($integration))->run();+ expect(FormIntegrationsEvent::where('integration_id', 7)->sole()->status)->toBe('error');+});++it('verifies real SNS signatures and rejects tampering without certificate network access', function () {+ $key = openssl_pkey_new(['private_key_bits' => 2048]);+ $csr = openssl_csr_new(['commonName' => 'sns.eu-west-2.amazonaws.com'], $key);+ $cert = openssl_csr_sign($csr, null, $key, 1);+ openssl_x509_export($cert, $pem);+ app()->instance(MessageValidator::class, new MessageValidator(fn () => $pem));+ $body = snsEmailEnvelope(emailFeedback($this));+ $canonical = '';+ foreach (['Message', 'MessageId', 'Timestamp', 'TopicArn', 'Type'] as $field) {+ $canonical .= "$field\n{$body[$field]}\n";+ }+ openssl_sign($canonical, $signature, $key, OPENSSL_ALGO_SHA1);+ $body['Signature'] = base64_encode($signature);+ $this->postJson('/aws/sns/ses/integration-events', $body)->assertOk();+ $body['Message'] = '{}';+ $this->postJson('/aws/sns/ses/integration-events', $body)->assertForbidden();+});++it('records real Laravel SES transport acceptance and a MessageSending veto without sending externally', function () {+ $calls = 0;+ $ses = new \Aws\Ses\SesClient([+ 'version' => 'latest', 'region' => 'eu-west-2',+ 'credentials' => ['key' => 'local-test', 'secret' => 'local-test'],+ 'handler' => function () use (&$calls) {+ $calls++;+ return \GuzzleHttp\Promise\Create::promiseFor(new \Aws\Result(['MessageId' => 'sdk-message-id']));+ },+ ]);+ config(['mail.mailers.tracking_test' => ['transport' => 'tracking_test']]);+ \Illuminate\Support\Facades\Mail::extend('tracking_test', fn () => new \Illuminate\Mail\Transport\SesTransport($ses));+ $notification = new class () extends \Illuminate\Notifications\Notification {+ public array $emailTracking;+ public string $emailTransport = 'ses';+ public function via($notifiable)+ {+ return ['mail'];+ }+ public function toMail($notifiable)+ {+ return (new \Illuminate\Notifications\Messages\MailMessage())->mailer('tracking_test')->subject('Local test')->line('Local only');+ }+ };+ $notification->emailTracking = ['event' => $this->id, 'recipient' => $this->recipientId];+ // Isolate unrelated suppression listeners requiring their own database tables.+ Event::forget(\Illuminate\Mail\Events\MessageSending::class);+ \Illuminate\Support\Facades\Notification::route('mail', '[email protected]')->notify($notification);+ expect(data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId.'.provider_message_id'))->toBe('sdk-message-id');+ Event::listen(\Illuminate\Mail\Events\MessageSending::class, fn () => false);+ $notification->emailTracking['recipient'] = array_key_last($this->recipients);+ \Illuminate\Support\Facades\Notification::route('mail', '[email protected]')->notify($notification);+ expect($calls)->toBe(1);+ expect(data_get($this->event->fresh()->data, 'email.recipients.'.array_key_last($this->recipients).'.status'))->toBe('blocked');+});+++it('distinguishes an explicit SES rejection from an uncertain transport failure without leaking raw diagnostics', function () {+ $aws = new \Aws\Exception\AwsException('private provider text', new \Aws\Command('SendRawEmail'), ['code' => 'MessageRejected']);+ $wrapped = new \Symfony\Component\Mailer\Exception\TransportException('private SMTP text', 0, $aws);+ $this->tracker->failure($this->id, $this->recipientId, $wrapped);+ $recipient = data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId);+ expect($recipient->status)->toBe('rejected')->and($recipient->reason_code)->toBe('MessageRejected');+ expect(json_encode($recipient))->not->toContain('private');+ expect($this->event->fresh()->status)->toBe('error');+});++it('keeps confirmed acceptance when a later synchronous listener throws', function () {+ $this->tracker->recipient($this->id, $this->recipientId, ['status' => 'accepted', 'provider_message_id' => 'accepted-id']);+ $this->tracker->failure($this->id, $this->recipientId, new RuntimeException('Later listener failed'));+ $recipient = data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId);+ expect($recipient->status)->toBe('accepted')->and($recipient->provider_message_id)->toBe('accepted-id');+});++it('does not let an unavailable alert queue interrupt other recipients', function () {+ Event::getFacadeRoot()->except([\App\Events\Models\FormIntegrationsEventCreated::class]);+ Event::forget(\App\Events\Models\FormIntegrationsEventCreated::class);+ Event::listen(\App\Events\Models\FormIntegrationsEventCreated::class, function () {+ throw new RuntimeException('Queue unavailable');+ });+ // Pending recipients must still be returned for dispatch despite the invalid-address alert.+ $recipients = $this->tracker->prepare($this->id, ['invalid', '[email protected]']);+ expect($recipients)->toHaveCount(2)->and($this->event->fresh()->status)->toBe('error');+});++it('does not retry the sending job when tracking persistence fails after a possible send', function () {+ $integration = new FormIntegration();+ $integration->id = 7;+ $this->partialMock(EmailDeliveryTracker::class, function ($mock) {+ $mock->shouldReceive('failure')->once()->andThrow(new RuntimeException('Database unavailable'));+ $mock->shouldReceive('outcome')->once()->andThrow(new RuntimeException('Still unavailable'));+ });+ \Illuminate\Support\Facades\Notification::shouldReceive('send')->once()->andThrow(new RuntimeException('Transport timeout'));+ expect(fn () => (new TrackedEmailHarness($integration))->run())->not->toThrow(Throwable::class);+ expect(FormIntegrationsEvent::where('integration_id', 7)->sole()->status)->toBe('processing');+});++it('does not refresh event timestamps for unmatched or duplicate feedback', function () {+ $this->tracker->feedback(emailFeedback($this));+ $before = $this->event->fresh()->getAttributes();+ $this->travel(20)->minutes();+ $this->tracker->feedback(emailFeedback($this));+ $payload = emailFeedback($this);+ $payload['delivery']['recipients'] = ['[email protected]'];+ $this->tracker->feedback($payload);+ expect($this->event->fresh()->getAttributes())->toBe($before);+});++it('preserves feedback identifiers and records acceptance when feedback wins the race', function () {+ $this->tracker->feedback(emailFeedback($this));+ $this->tracker->recipient($this->id, $this->recipientId, ['status' => 'accepted', 'provider_message_id' => null, 'provider' => 'unknown']);+ $recipient = data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId);+ expect($recipient->status)->toBe('delivered')->and($recipient->provider_message_id)->toBe('ses-message-id')+ ->and($recipient->timeline->accepted)->not->toBeNull();+});++it('safely ignores malformed structured feedback', function ($bad) {+ $before = $this->event->fresh()->getAttributes();+ expect($this->tracker->feedback(array_replace_recursive(emailFeedback($this), $bad)))->toBeFalse();+ expect($this->event->fresh()->getAttributes())->toBe($before);+})->with([+ [['notificationType' => []]],+ [['mail' => ['headers' => 'not-an-array']]],+ [['delivery' => ['recipients' => 'not-an-array']]],+ [['mail' => ['messageId' => ['bad']]]],+]);++it('asks SNS to retry a temporary signing certificate download failure', function () {+ Http::fake(['https://sns.eu-west-2.amazonaws.com/*' => Http::response('', 503)]);+ $this->postJson('/aws/sns/ses/integration-events', snsEmailEnvelope(emailFeedback($this)))->assertStatus(503);+});+++it('shows a known interruption immediately without erasing completed recipient evidence', function () {+ $this->tracker->recipient($this->id, $this->recipientId, ['status' => 'accepted']);+ $this->tracker->outcome($this->id, 'unknown', 'Processing interrupted.');+ expect($this->event->fresh()->status)->toBe('unknown');+ expect(data_get($this->event->fresh()->data, 'email.recipients.'.$this->recipientId.'.status'))->toBe('accepted');+});+++it('rejects malformed optional SNS envelope fields before any certificate request', function () {+ $payload = snsEmailEnvelope(emailFeedback($this));+ $payload['Subject'] = ['not-a-string'];+ $this->postJson('/aws/sns/ses/integration-events', $payload)->assertForbidden();+ Http::assertNothingSent();+});diff --git a/client/components/open/integrations/components/IntegrationEmailEvent.vue b/client/components/open/integrations/components/IntegrationEmailEvent.vuenew file mode 100644index 000000000..2371e87ff--- /dev/null+++ b/client/components/open/integrations/components/IntegrationEmailEvent.vue@@ -0,0 +1,29 @@+<template>+ <div class="space-y-3 min-w-64 max-w-xl whitespace-normal">+ <p v-if="event.data?.email?.reason" class="text-sm">{{ event.data.email.reason }}</p>+ <p v-if="isStale(event)" class="text-sm text-amber-600">+ Processing has not completed. The outcome is unknown; do not retry blindly.+ </p>+ <div v-for="(recipient, id) in event.data?.email?.recipients" :key="id" class="border-b border-neutral-200 pb-2 text-sm dark:border-neutral-700">+ <p class="font-medium break-all">{{ recipient.address }}</p>+ <p>{{ recipientLabel(recipient.status) }}</p>+ <p v-if="recipient.reason" class="text-neutral-500">{{ recipient.reason }}</p>+ <p v-if="recipient.reason_code" class="text-xs text-neutral-500">{{ recipient.reason_code }}</p>+ <p v-if="recipient.feedback?.bounce" class="text-neutral-500">+ Bounce: {{ recipient.feedback.bounce.type }} / {{ recipient.feedback.bounce.subtype }}+ </p>+ <p v-for="(at, state) in recipient.timeline" :key="state" class="text-xs text-neutral-500">{{ recipientLabel(state) }}: {{ at }}</p>+ <p v-for="(feedback, type) in recipient.feedback" :key="type" class="text-xs text-neutral-500">{{ type }}: {{ feedback.at || feedback.received_at }}</p>+ <p v-if="recipient.updated_at" class="text-xs text-neutral-500">Updated: {{ recipient.updated_at }}</p>+ <p v-if="recipient.provider_message_id" class="text-xs text-neutral-500 break-all">Message ID: {{ recipient.provider_message_id }}</p>+ </div>+ <p v-if="event.tracking_id" class="text-xs text-neutral-500 break-all">Event ID: {{ event.tracking_id }}</p>+ <p class="text-xs text-neutral-500">Delivery means acceptance by the receiving mail server, not inbox placement. No delivery event means delivery is unconfirmed.</p>+ </div>+</template>++<script setup>+import { isStale, recipientLabel } from "~/lib/integration-email-status"++defineProps({ event: { type: Object, required: true } })+</script>diff --git a/client/components/open/integrations/components/IntegrationEventsModal.vue b/client/components/open/integrations/components/IntegrationEventsModal.vueindex d5a428152..7e128cbe1 100644--- a/client/components/open/integrations/components/IntegrationEventsModal.vue+++ b/client/components/open/integrations/components/IntegrationEventsModal.vue@@ -11,15 +11,12 @@:data="integrationEvents"><template #status-cell="{ row }">- <UBadge- variant="subtle"- :color="row.original.status === 'Success' ? 'success' : 'error'"- :label="row.original.status"- />+ <UBadge variant="subtle" :color="eventColor(row.original)" :label="eventLabel(row.original)" /></template><template #data-cell="{ row }">+ <IntegrationEmailEvent v-if="row.original.email_tracking" :event="row.original" /><vue-json-pretty- v-if="row.original.data && Object.keys(row.original.data).length > 0"+ v-else-if="row.original.data && Object.keys(row.original.data).length > 0":data="row.original.data":collapsed-node-length="0":show-length="true"@@ -31,6 +28,7 @@</template><template #footer>+ <UButton color="neutral" variant="outline" label="Refresh" :loading="integrationEventsLoading" @click="fetchEvents" /><UButtoncolor="neutral"variant="outline"@@ -42,6 +40,8 @@</template><script setup>+import IntegrationEmailEvent from "./IntegrationEmailEvent.vue"+import { eventColor, eventLabel } from "~/lib/integration-email-status"import VueJsonPretty from "vue-json-pretty"import "vue-json-pretty/lib/styles.css"import { formsApi } from "~/api/forms"@@ -53,6 +53,7 @@ const props = defineProps({})const emit = defineEmits(["close"])+const alert = useAlert()// Modal stateconst isOpen = computed({@@ -87,6 +88,9 @@ const fetchEvents = () => {integrationEvents.value = []formsApi.integrations.events(props.form.id, props.formIntegrationId).then((data) => {integrationEvents.value = data+ }).catch(() => {+ alert.error("Could not load integration events. Please refresh.")+ }).finally(() => {integrationEventsLoading.value = false})})diff --git a/client/lib/integration-email-status.js b/client/lib/integration-email-status.jsnew file mode 100644index 000000000..1b1a9c9c4--- /dev/null+++ b/client/lib/integration-email-status.js@@ -0,0 +1,25 @@+export function isStale(event, now = Date.now()) {+ if (!event.email_tracking) return false+ return (event.status === "Processing" && now - Date.parse(event.updated_at) > 10 * 60 * 1000) ||+ Object.values(event.data?.email?.recipients || {}).some((recipient) =>+ ["pending", "sending"].includes(recipient.status) && now - Date.parse(recipient.updated_at) > 10 * 60 * 1000)++}++export function eventLabel(event) {+ if (event.status === "Error") return "Action needed"+ if (event.legacy_email && event.status === "Success") return "Completed · delivery untracked"+ if (isStale(event)) return "Outcome unknown"+ return ({ Accepted: "Accepted · delivery unconfirmed", Delivered: "Delivered to mail server", Unknown: "Outcome unknown", Error: "Action needed" })[event.status] || event.status+}++export function eventColor(event) {+ if (event.status === "Error") return "error"+ if (isStale(event) || ["Unknown", "Accepted", "Processing"].includes(event.status)) return "warning"+ if (["Success", "Delivered"].includes(event.status)) return event.legacy_email ? "neutral" : "success"+ return event.status === "Error" ? "error" : "neutral"+}++export function recipientLabel(status) {+ return ({ pending: "Not yet attempted", sending: "Sending · outcome unconfirmed", accepted: "Accepted by transport · delivery unconfirmed", delivered: "Delivered to mail server", invalid: "Invalid address · not sent", blocked: "Cancelled by application · not sent", not_sent: "Non-delivering transport", unknown: "Outcome unknown", rejected: "Rejected by email provider", bounced: "Bounced", complained: "Spam complaint" })[status] || status+}diff --git a/client/package.json b/client/package.jsonindex 0255b8f5a..26fbf4499 100644--- a/client/package.json+++ b/client/package.json@@ -10,6 +10,7 @@"generate": "export NODE_TLS_REJECT_UNAUTHORIZED=0; nuxt generate","preview": "nuxt preview","postinstall": "nuxt prepare",+ "test:email-events": "node --test tests/integration-email-status.test.mjs","lint": "eslint --ext .js,.vue .","lint:fix": "eslint . --fix --ext .js,.vue","test": "VITEST=true vitest",diff --git a/client/tests/integration-email-status.test.mjs b/client/tests/integration-email-status.test.mjsnew file mode 100644index 000000000..7740e5f65--- /dev/null+++ b/client/tests/integration-email-status.test.mjs@@ -0,0 +1,62 @@+import { test } from 'node:test'+import assert from 'node:assert/strict'+import { eventLabel, eventColor, isStale, recipientLabel } from '../lib/integration-email-status.js'++test('acceptance and legacy success do not imply mailbox delivery', () => {+ assert.equal(eventLabel({ status: 'Accepted' }), 'Accepted · delivery unconfirmed')+ assert.equal(eventLabel({ status: 'Success', legacy_email: true }), 'Completed · delivery untracked')+ assert.equal(eventColor({ status: 'Success', legacy_email: true }), 'neutral')+ assert.equal(eventLabel({ status: 'Success' }), 'Success')+})++test('abandoned processing becomes explicitly uncertain', () => {+ const event = { email_tracking: true, status: 'Processing', updated_at: '2026-01-01T00:00:00Z' }+ assert.equal(isStale(event, Date.parse('2026-01-01T00:11:00Z')), true)+ assert.equal(isStale(event, Date.parse('2026-01-01T00:01:00Z')), false)+ assert.equal(isStale({ ...event, email_tracking: false }, Date.now()), false)+})++test('a partial failure does not conceal an abandoned recipient', () => {+ const event = { email_tracking: true, status: 'Error', data: { email: { recipients: { a: { status: 'sending', updated_at: '2026-01-01T00:00:00Z' } } } } }+ assert.equal(isStale(event, Date.parse('2026-01-01T00:11:00Z')), true)+ assert.equal(recipientLabel('bounced'), 'Bounced')+ assert.equal(recipientLabel('unknown'), 'Outcome unknown')+})+++test('renders recipient evidence and the inbox limitation in the actual Vue component', async () => {+ const { readFile, writeFile, mkdir, rm } = await import('node:fs/promises')+ const { pathToFileURL } = await import('node:url')+ const { resolve } = await import('node:path')+ const { parse, compileScript } = await import('@vue/compiler-sfc')+ const { createSSRApp } = await import('vue')+ const { renderToString } = await import('@vue/server-renderer')+ const source = await readFile(new URL('../components/open/integrations/components/IntegrationEmailEvent.vue', import.meta.url), 'utf8')+ const { descriptor } = parse(source)+ const compiled = compileScript(descriptor, { id: 'email-event-test', inlineTemplate: true })+ const generatedPath = resolve('node_modules/.cache/email-event-test.mjs')+ await mkdir(resolve('node_modules/.cache'), { recursive: true })+ await writeFile(generatedPath, compiled.content.replace('~/lib/integration-email-status', pathToFileURL(resolve('lib/integration-email-status.js')).href))+ try {+ const { default: component } = await import(pathToFileURL(generatedPath).href)+ const html = await renderToString(createSSRApp(component, { event: {+ email_tracking: true, status: 'Error', data: { email: { recipients: {+ first: { address: '[email protected]', status: 'delivered', provider_message_id: 'ses-123' },+ second: { address: '[email protected]', status: 'bounced', reason: 'Receiving server rejected the email.' },+ } } },+ } }))+ assert.match(html, /Delivered to mail server/)+ assert.match(html, /Bounced/)+ assert.match(html, /ses-123/)+ assert.match(html, /not inbox placement/)+ } finally {+ await rm(generatedPath)+ }+})+++test('confirmed errors stay prominent when another recipient has an uncertain stale result', () => {+ const event = { email_tracking: true, status: 'Error', data: { email: { recipients: { a: { status: 'sending', updated_at: '2020-01-01T00:00:00Z' } } } } }+ assert.equal(eventLabel(event), 'Action needed')+ assert.equal(eventColor(event), 'error')+})diff --git a/docs/development/email-delivery-tracking.md b/docs/development/email-delivery-tracking.mdnew file mode 100644index 000000000..8558d9179--- /dev/null+++ b/docs/development/email-delivery-tracking.md@@ -0,0 +1,37 @@+# Integration email events++## Resolved design review (grill-me)++- **Do we need another tracking system?** No. Use the existing integration event, its JSON data, and an indexed nullable UUID. Create the event before sending and register each resolved recipient before dispatch. Non-email integrations keep their existing behavior.+- **What does success prove?** A transport response proves acceptance only. A signed SES Delivery event proves acceptance by the receiving server, never inbox placement. Old Success events are explicitly untracked. Log/array transports are marked not sent.+- **What if only one recipient fails?** Keep each recipient's result, including invalid addresses, application cancellation, uncertain exceptions, bounces and complaints. Continue other recipients. Trim and deduplicate addresses. Never silently discard invalid recipients.+- **Can feedback arrive first or twice?** Yes. Correlate two server-generated MIME headers (event UUID and recipient UUID), require matching destination and SES message ID, and lock the event row when merging. Retain one fact per feedback type. A late Delivery cannot erase Bounce/Complaint. Keep attempt/acceptance timestamps and feedback timestamps.+- **Are existing SNS webhooks sufficient?** They provide the feedback mechanism; they do not automatically associate feedback with an integration execution. Subscribe this new signed endpoint alongside the existing bounce/complaint handlers. It never writes the legacy suppression table or removes its consumers.+- **Could another AWS customer forge feedback?** A valid signature is insufficient: the topic must also appear in this app's exact allowlist. Confirmation goes only to the AWS endpoint constructed from that allowlisted ARN. Invalid/unsigned requests fail closed.+- **Can we retry an uncertain attempt?** No automatic resend is introduced. NoteForms disables grouped retry for tracked email events, server-side as well as in the UI. Queue redelivery/exactly-once delivery is NOT solved by this change. Worker death leaves a visible uncertain event after ten minutes; this threshold is a display heuristic, not proof of delivery failure.+- **What about custom SMTP?** Acceptance is visible but SES delivery feedback does not cover external SMTP. Cached custom SMTP transport must be purged when changing workspace configuration.+- **Does this change anti-abuse or support access?** Existing sending restrictions remain. NoteForms baseline counts include tracked attempts. Events remain scoped to the form's integration, including the previously insufficiently scoped NoteForms list endpoint.+- **What remains outside coverage?** This tracks form email integrations after their worker starts, not every transactional email or a job that never starts. No retroactive provider evidence is invented. Existing history retention (14 days) applies; unmatched/expired feedback is acknowledged and logged. No new SQS/configuration-set infrastructure is needed.++## Deployment and activation (not performed by this change)++1. Apply the additive migration before starting the new application/workers. Deploy backend and frontend together; refresh cached routes/config/events and restart long-lived workers. NoteForms includes the prior signed SNS/topic-allowlist repair as its base.+2. Set `EMAIL_TRACKING_SNS_TOPICS` to the exact comma-separated ARNs for this application's Bounce, Complaint and Delivery topics in the sending SES region/account. Empty means the endpoint accepts nothing. Do not include other applications' topics.+3. Subscribe the HTTPS endpoint `/aws/sns/ses/integration-events` to the bounce and complaint topics without replacing existing subscriptions. Create/use a separate Delivery topic and configure SES identity Delivery notifications to it. Existing bounce endpoints may not support Delivery payloads.+4. Enable inclusion of original email headers on **all three** SES identity notification types. Check every sending identity and region. Configure SNS topic policy to permit SES publishing. This implementation uses `notificationType` or `eventType` and requires intact tracking headers; absent/truncated headers leave delivery unconfirmed and produce an unmatched-feedback log.+5. Verify confirmed subscriptions, then run an explicitly authorized controlled submission to a test mailbox and SES bounce/complaint simulator addresses. Confirm the original integration event gains the correct recipient outcome and SES message ID, and duplicate feedback produces no duplicate failure alert. Do not send test messages to customers.+6. Monitor unmatched-feedback logs and SNS failed-notification metrics. An accepted event without feedback stays unconfirmed; it is not reported as delivered or inferred as bounced. Refresh the event modal to load asynchronous updates.++The webhook stores only normalized feedback type/subtype, identifiers and timestamps, not complete message content or raw SMTP responses. Transient database errors return server errors so SNS can retry. Permanent non-matches are acknowledged to avoid a retry storm after history deletion.++## Rollback++Roll back code/workers first and leave the nullable column in place until no new workers use it. Disable the new subscriptions independently; preserve legacy bounce/complaint subscriptions. Removing the column later drops correlation only, not the event JSON. Do not replay uncertain events while rolling back.++## Failure isolation and callback retries++A later listener failure cannot erase already-persisted transport acceptance. Failure alerts are best-effort: queue failures are logged but cannot interrupt recipient sends or SNS acknowledgement. If tracking storage fails after a possible send, the handler stops and logs the tracking ID instead of automatically replaying the sending job; the retained incomplete event becomes uncertain in the UI. This does not provide exactly-once sending after worker termination.++SNS certificate downloads have a five-second timeout, redirects disabled and a one-hour cache. Temporary HTTP failures return 503 so SNS can retry, while invalid signatures return 403. Malformed or unmatched SES feedback is acknowledged without changing the event; duplicate feedback does not refresh timestamps. Known errors remain highlighted even if another recipient has an uncertain result.++Run `npm run test:email-events` from client/ for the event status and Vue rendering regressions; CI also runs this command.