feat: Add confirmation email for form respondents

CHANGELOG.en.md

@@ -5,6 +5,18 @@
 
 # Changelog
 
+## Unreleased
+
+- **Confirmation emails for respondents**
+
+    Form owners can enable an automatic confirmation email that is sent to the respondent after a successful submission.
+    Requires an email-validated short text question in the form.
+
+    Supported placeholders in subject/body:
+
+    - `{formTitle}`, `{formDescription}`
+    - `{<fieldName>}` (question `name` or text, sanitized)
+
 ## v5.2.0 - 2025-09-25
 
 - **Time: restrictions and ranges**

docs/API_v3.md

@@ -175,6 +175,9 @@ Returns the full-depth object of the requested form (without submissions).
   "state": 0,
   "lockedBy": null,
   "lockedUntil": null,
+  "confirmationEmailEnabled": false,
+  "confirmationEmailSubject": null,
+  "confirmationEmailBody": null,
   "permissions": [
     "edit",
     "results",

docs/DataStructure.md

@@ -21,6 +21,9 @@ This document describes the Object-Structure, that is used within the Forms App
 | description          | String                               | max. 8192 ch.                           | The Form description                                                                                                             |
 | ownerId              | String                               |                                         | The nextcloud userId of the form owner                                                                                           |
 | submissionMessage    | String                               | max. 2048 ch.                           | Optional custom message, with Markdown support, to be shown to users when the form is submitted (default is used if set to null) |
+| confirmationEmailEnabled | Boolean                          |                                         | If enabled, send a confirmation email to the respondent after submission                                                         |
+| confirmationEmailSubject | String                           | max. 255 ch.                            | Optional confirmation email subject template (supports placeholders)                                                              |
+| confirmationEmailBody    | String                           |                                         | Optional confirmation email body template (plain text, supports placeholders)                                                    |
 | created              | unix timestamp                       |                                         | When the form has been created                                                                                                   |
 | access               | [Access-Object](#access-object)      |                                         | Describing access-settings of the form                                                                                           |
 | expires              | unix-timestamp                       |                                         | When the form should expire. Timestamp `0` indicates _never_                                                                     |
@@ -46,6 +49,9 @@ This document describes the Object-Structure, that is used within the Forms App
   "title": "Form 1",
   "description": "Description Text",
   "ownerId": "jonas",
+  "confirmationEmailEnabled": false,
+  "confirmationEmailSubject": null,
+  "confirmationEmailBody": null,
   "created": 1611240961,
   "access": {},
   "expires": 0,

lib/Constants.php

@@ -147,6 +147,7 @@ class Constants {
 	];
 
 	public const EXTRA_SETTINGS_SHORT = [
+		'confirmationEmailRecipient' => ['boolean'],
 		'validationType' => ['string'],
 		'validationRegex' => ['string'],
 	];

lib/Db/Form.php

@@ -53,6 +53,12 @@
  * @method int|null getMaxSubmissions()
  * @method void setMaxSubmissions(int|null $value)
  * @method void setLockedUntil(int|null $value)
+ * @method int getConfirmationEmailEnabled()
+ * @method void setConfirmationEmailEnabled(bool $value)
+ * @method string|null getConfirmationEmailSubject()
+ * @method void setConfirmationEmailSubject(string|null $value)
+ * @method string|null getConfirmationEmailBody()
+ * @method void setConfirmationEmailBody(string|null $value)
  */
 class Form extends Entity {
 	protected $hash;
@@ -74,6 +80,9 @@ class Form extends Entity {
 	protected $lockedBy;
 	protected $lockedUntil;
 	protected $maxSubmissions;
+	protected $confirmationEmailEnabled;
+	protected $confirmationEmailSubject;
+	protected $confirmationEmailBody;
 
 	/**
 	 * Form constructor.
@@ -90,6 +99,7 @@ public function __construct() {
 		$this->addType('lockedBy', 'string');
 		$this->addType('lockedUntil', 'integer');
 		$this->addType('maxSubmissions', 'integer');
+		$this->addType('confirmationEmailEnabled', 'boolean');
 	}
 
 	// JSON-Decoding of access-column.
@@ -164,6 +174,9 @@ public function setAccess(array $access): void {
 	 *   lockedBy: ?string,
 	 *   lockedUntil: ?int,
 	 *   maxSubmissions: ?int,
+	 *   confirmationEmailEnabled: bool,
+	 *   confirmationEmailSubject: ?string,
+	 *   confirmationEmailBody: ?string,
 	 *  }
 	 */
 	public function read() {
@@ -188,6 +201,9 @@ public function read() {
 			'lockedBy' => $this->getLockedBy(),
 			'lockedUntil' => $this->getLockedUntil(),
 			'maxSubmissions' => $this->getMaxSubmissions(),
+			'confirmationEmailEnabled' => (bool)$this->getConfirmationEmailEnabled(),
+			'confirmationEmailSubject' => $this->getConfirmationEmailSubject(),
+			'confirmationEmailBody' => $this->getConfirmationEmailBody(),
 		];
 	}
 }

lib/FormsMigrator.php

@@ -66,6 +66,9 @@ public function export(IUser $user, IExportDestination $exportDestination, Outpu
 			$forms = $this->formMapper->findAllByOwnerId($user->getUID());
 			foreach ($forms as $form) {
 				$formData = $form->read();
+				$formData['confirmationEmailEnabled'] ??= false;
+				$formData['confirmationEmailSubject'] ??= null;
+				$formData['confirmationEmailBody'] ??= null;
 				$formData['questions'] = $this->formsService->getQuestions($formData['id']);
 				$formData['submissions'] = $this->submissionService->getSubmissions($formData['id']);
 
@@ -149,6 +152,9 @@ public function import(IUser $user, IImportSource $importSource, OutputInterface
 				$form->setAllowEditSubmissions($formData['allowEditSubmissions']);
 				$form->setShowExpiration($formData['showExpiration']);
 				$form->setMaxSubmissions($formData['maxSubmissions'] ?? null);
+				$form->setConfirmationEmailEnabled($formData['confirmationEmailEnabled'] ?? false);
+				$form->setConfirmationEmailSubject($formData['confirmationEmailSubject'] ?? null);
+				$form->setConfirmationEmailBody($formData['confirmationEmailBody'] ?? null);
 
 				$this->formMapper->insert($form);
 

lib/Migration/Version050300Date20260413233000.php

@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2026 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCA\Forms\Migration;
+
+use Closure;
+use OCP\DB\ISchemaWrapper;
+use OCP\DB\Types;
+use OCP\Migration\IOutput;
+use OCP\Migration\SimpleMigrationStep;
+
+/**
+ * Add confirmation email fields to forms
+ */
+class Version050300Date20260413233000 extends SimpleMigrationStep {
+
+	/**
+	 * @param IOutput $output
+	 * @param Closure $schemaClosure The `\Closure` returns a `ISchemaWrapper`
+	 * @param array $options
+	 * @return null|ISchemaWrapper
+	 */
+	public function changeSchema(IOutput $output, Closure $schemaClosure, array $options): ?ISchemaWrapper {
+		/** @var ISchemaWrapper $schema */
+		$schema = $schemaClosure();
+		$table = $schema->getTable('forms_v2_forms');
+
+		if (!$table->hasColumn('confirmation_email_enabled')) {
+			$table->addColumn('confirmation_email_enabled', Types::BOOLEAN, [
+				'notnull' => false,
+				'default' => 0,
+			]);
+		}
+
+		if (!$table->hasColumn('confirmation_email_subject')) {
+			$table->addColumn('confirmation_email_subject', Types::STRING, [
+				'notnull' => false,
+				'default' => null,
+				'length' => 255,
+			]);
+		}
+
+		if (!$table->hasColumn('confirmation_email_body')) {
+			$table->addColumn('confirmation_email_body', Types::TEXT, [
+				'notnull' => false,
+				'default' => null,
+			]);
+		}
+
+		return $schema;
+	}
+}

lib/ResponseDefinitions.php

@@ -26,6 +26,7 @@
  *   dateMax?: int,
  *   dateMin?: int,
  *   dateRange?: bool,
+ *   confirmationEmailRecipient?: bool,
  *   maxAllowedFilesCount?: int,
  *   maxFileSize?: int,
  *   optionsHighest?: 2|3|4|5|6|7|8|9|10,
@@ -141,6 +142,9 @@
  *   shares: list<FormsShare>,
  *   submissionCount?: int,
  *   submissionMessage: ?string,
+ *   confirmationEmailEnabled: bool,
+ *   confirmationEmailSubject: ?string,
+ *   confirmationEmailBody: ?string,
  * }
  *
  * @psalm-type FormsUploadedFile = array{