[BUGFIX] restore UID-based mail-template selection

CHANGELOG.md

@@ -6,4 +6,11 @@ All notable changes to this extension are documented in this file.
 
 - Removed the legacy `StandaloneView` APIs from `TemplateBasedMailMessage`: `getMessageView()`, `setMessageView()`, `getSubjectView()`, and `setSubjectView()`.
   Configure message and subject templates through the mail-template and TypoScript configuration instead.
-- Removed MailUtility::getMailById, use MailUtility::getMailByKey instead
+
+## Fixed
+
+- Restored `MailUtility::getMailById()` for integrations that persist a concrete
+  mail-template UID, such as TYPO3 form finishers. Editors can create multiple
+  templates with the same TypoScript key; a key-based lookup could therefore select
+  a different template than the one selected in the integration. `getMailByKey()`
+  remains the appropriate API for intentional key-based template selection.

Classes/Utility/MailUtility.php

@@ -34,4 +34,37 @@ public static function getMailByKey(string $key, ?int $languageUid = null, array
 
         return $mail->setMailTemplate($mailTemplate, true, $viewParameters);
     }
+
+    /**
+     * Creates a mail from the exact mail-template record selected by its UID.
+     *
+     * Mail template keys are defined in TypoScript and therefore only work for
+     * templates managed by developers. Editor-managed mail templates cannot
+     * reliably use such keys because editors do not manage TypoScript.
+     *
+     * This is especially relevant when editors can create arbitrary forms and
+     * select a mail template for a form finisher. In that case, the selected
+     * template is stored as a concrete record UID and must be retrieved by UID.
+     *
+     * getMailByKey() remains the standard way to retrieve developer-configured
+     * templates by their TypoScript key. Use this method when the calling context
+     * stores an explicit mail template selection as a UID.
+     *
+     * @param int $mailTemplateId The UID of the selected mail-template record
+     * @param array<array-key, mixed> $viewParameters This is necessary if you use Fluid for your mail fields
+     * @throws Exception
+     */
+    public static function getMailById(int $mailTemplateId, array $viewParameters = []): TemplateBasedMailMessage
+    {
+        $mail = GeneralUtility::makeInstance(TemplateBasedMailMessage::class);
+        $templateRepository = GeneralUtility::makeInstance(MailTemplateRepository::class);
+        $mailTemplate = $templateRepository->findByUid($mailTemplateId);
+        if (!$mailTemplate) {
+            throw new Exception('No "MailTemplate" was found for uid "' . $mailTemplateId . '". Please check your database records!', 6976725035);
+        }
+
+        $mailTemplate = GeneralUtility::makeInstance(MailTemplateContentTransformer::class)->transformMailTemplate($mailTemplate);
+
+        return $mail->setMailTemplate($mailTemplate, true, $viewParameters);
+    }
 }

Tests/Fixtures/TemplateBasedMailMessageTest/mail_templates.csv

@@ -1,4 +1,5 @@
 tx_maillogger_domain_model_mailtemplate,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,
 ,uid,pid,typo_script_key,dkim_key,template_path_key,title,subject,message,mail_from_name,mail_from_address,mail_to_names,mail_to_addresses,mail_copy_addresses,mail_blind_copy_addresses,tstamp,crdate,cruser_id,deleted,hidden,starttime,endtime,t3ver_oid,t3ver_id,t3ver_wsid,t3ver_state,t3ver_stage,t3ver_count,t3ver_tstamp,t3ver_move_id,sys_language_uid,l10n_parent,l10n_diffsource
 ,1,1,functionalMail,,,Functional mail,,,,,,,,,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,\NULL
+,3,1,functionalMail,,,Selected functional mail,,,,,,,,,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,\NULL
 ,2,1,directSubjectMail,,,Direct subject mail,,,,,,,,,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,\NULL

Tests/Functional/TemplateBasedMailMessage/TemplateBasedMailMessageTest.php

@@ -51,6 +51,16 @@ public function testConfiguredTemplateIsRenderedAndLoggedWhenSentThroughNullTran
         self::assertStringContainsString('Subject: Functional subject for Ada', $mailLog['headers']);
     }
 
+    public function testMailByIdUsesTheSelectedTemplateWhenTemplatesShareAKey(): void
+    {
+        $mail = MailUtility::getMailById(3, [
+            'name' => 'Ada',
+            'color' => 'blue',
+        ]);
+
+        self::assertSame('Selected functional mail', $mail->getMailTemplate()->getTitle());
+    }
+
     public function testManuallyAssignedSubjectIsKeptWhenTemplateDoesNotConfigureSubject(): void
     {
         $mail = MailUtility::getMailByKey('directSubjectMail', null, [