feat: Add confirmation email for form respondents by dtretyakov · Pull Request #3289 · nextcloud/forms

dtretyakov · 2026-04-14T04:46:27Z

Closes #525 - Send confirmation emails to form respondents after submission.

Features:

Add confirmation email settings (enabled, subject, body) to Form entity.
Implement email sending with placeholder replacement:
- {formTitle}, {formDescription}
- Field placeholders based on name or label (e.g. {name}, {email}).
Allow form creators to explicitly select the recipient email field when multiple email fields are present.
Add UI in Settings sidebar to configure confirmation emails and recipient selection.
Replace basic email validation with Nextcloud's internal IEmailValidator.
Integration with activity notifications and background jobs for file syncing.

Technical changes:

Database migration for new Form properties.
Enhanced FormsService with email sending logic and validation.
Extensive unit and integration tests covering the new functionality.
Updated API documentation and OpenAPI spec.

codecov · 2026-04-14T05:33:43Z

Codecov Report

❌ Patch coverage is 68.29268% with 78 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
lib/Migration/Version050300Date20260413233000.php	0.00%	30 Missing ⚠️
lib/BackgroundJob/SendConfirmationMailJob.php	0.00%	29 Missing ⚠️
lib/Service/ConfirmationEmailService.php	88.14%	16 Missing ⚠️
lib/FormsMigrator.php	75.00%	2 Missing ⚠️
lib/Controller/ApiController.php	94.73%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

dtretyakov · 2026-04-14T07:11:53Z

@Chartman123 I also tried to streamline UX for the feature.

Now the form looks like that:

Chartman123 · 2026-04-14T07:21:56Z

@dtretyakov looks good :)

I'll ping the design specialists to see what they think about it :)

dtretyakov · 2026-04-14T07:30:44Z

OCP\Mail\IEmailValidator breaks backward compatibility for this PR. The interface is not available in nextcloud/ocp on stable31.

For app code here, IMailer::validateMailAddress() is the safer choice: it is already available across the supported server branches and covers the same validation use case without introducing a branch-specific compatibility break.

Chartman123 · 2026-04-14T07:49:27Z

No problem, just ignore this. For the next release we will no longer support NC31

dtretyakov · 2026-04-21T17:58:23Z

@Chartman123 the branch is rebased on the fresh main and uses OCP\Mail\IEmailValidator.
Please let me know if you're missing something to push it forward and make NC customers happier.

Chartman123

I did a quick review and found some parts that should be changed in my opinion.

Please also add the new fields to FormsMigrator.php.

Also not sure about the frontend part, especially in the sidebar as I'm no vue expert. I added @susnux and @pringelmann as reviewers :)

Btw no need to hurry, the next release is not yet directly around the corner. We'll get it merged once it's ready :)

pringelmann · 2026-04-23T07:56:51Z

One thing I want to flag before this lands: as written, this turns any public form into an unauthenticated outbound mailer. A submitter controls the recipient address (it's just whatever they typed into the email field), so an attacker can script submissions with a victim's address and use the instance to mailbox-bomb them. Worst case it also burns the operator's MX reputation.

A few options, not mutually exclusive:

Rate limit per recipient address and/or per form.
Restrict the feature to authenticated submitters only (or at least gate it behind a warning when the form is public).
Move sending into a queued job so the queue can be paced.

I'd be more comfortable with at least one of these in place before we ship. Could also be worth a line in the PR description spelling out which mitigations apply, since this is a new outbound channel.

Chartman123 · 2026-04-23T08:10:54Z

One thing I want to flag before this lands: as written, this turns any public form into an unauthenticated outbound mailer.

@pringelmann Perhaps we should also add an admin setting that can turn the feature on/off and that should be off by default?

pringelmann · 2026-04-23T08:12:53Z

+		if (!$table->hasColumn('confirmation_email_enabled')) {
+			$table->addColumn('confirmation_email_enabled', Types::BOOLEAN, [
+				'notnull' => false,
+				'default' => 0,


This means existing rows on upgrade might end up as NULL rather than false. It happens to look right because of the casting, but the column doesn't actually reflect the domain - it's a flag, not tri-state. I'd just make it notnull => true, default => false then we can drop all the bool casting.

We have default => 0 everywhere for booleans. I think this is because one of the DB systems (sqlite?)...

Ah ok, good to know thnx :)

But yes, notnull => true would make sense. Every row should have a value here.

pringelmann · 2026-04-23T08:17:14Z

One thing I want to flag before this lands: as written, this turns any public form into an unauthenticated outbound mailer.

@pringelmann Perhaps we should also add an admin setting that can turn the feature on/off and that should be off by default?

Yeah good idea, default-off admin toggle is a sensible safety net and I'd vote for adding it.

That said, I don't think it replaces a per-form/per-recipient mitigation. Once an admin flips it on (which many likely will, because it is a very useful feature for users), the abuse surface is fully open again on every public form on the instance. So it protects the instances that don't need the feature but does nothing for the ones that do.

I'd still suggest at least one of: rate limit per recipient, gate it behind authentication, or pace via a queued job. The admin toggle then becomes a global kill switch on top of that, which is genuinely useful (e.g. an admin can disable the feature instance-wide if they spot abuse in their mail logs)

dtretyakov · 2026-04-23T22:34:09Z

To mitigate the risks associated with automated emails now we have implemented a 4-layer defense strategy:

Administrative Control: A global "kill switch" (allowConfirmationEmail) is available in the admin settings (defaulting to off), allowing instance operators to opt-in or disable the feature entirely.
Burst Protection: We utilize Nextcloud's built-in AnonRateLimit and UserRateLimit middleware on the submission endpoint to prevent rapid-fire scripting attacks from a single IP.
Recipient Safeguard: A strict per-recipient rate limit (max 3 emails per form/recipient pair per 24 hours) is enforced using a distributed cache with a "silent skip" strategy. This prevents a malicious actor from using a form to target a specific email address repeatedly, even when using multiple source IPs.
Asynchronous Processing: Email sending is offloaded to a QueuedJob (SendConfirmationMailJob). This decouples the SMTP transaction from the HTTP response, preventing server hangs due to mail server latency and ensuring natural pacing of outgoing traffic.

If you see this combination is excessive please let me know and we could relax it.

dtretyakov · 2026-04-27T17:20:54Z

@Chartman123 or @pringelmann please let me know if it requires some extra changes.

github-actions · 2026-04-29T02:21:01Z

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)

dtretyakov · 2026-04-29T19:19:07Z

Thank you all for having the detailed review, I applied the fixes.
Also there are refactoring to make simplify the support of new feature:

SendConfirmationMailJob now uses email template.
ConfirmationEmailService now contains the new logic to process form send requests and triggers the Job.
Cleanup in the SettingsSidebarTab to use NC components.

Chartman123 · 2026-04-30T10:13:46Z

Other question: should we add a check if sending mails is generally available for the server? In my dev instance, I don't have the mail settings configured, but could enable the confirmation mails...

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

- Relocate confirmationEmailRecipient from Question extraSettings to Form - Centralize email question validation in Question model and FormsService - Simplify SettingsSidebarTab component logic - Ensure correct recipient ID mapping during form cloning - Add comprehensive unit tests for validation and notification logic Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

- Add test for globally disabled confirmation emails - Fix rate limiting on APCu-only installs - Optimize formMapper updates and refactor sendConfirmationEmail - Fix PHPDoc, typings and UI validations Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

- Move confirmation email logic from FormsService to ConfirmationEmailService - Implement configurable rate limiting for confirmation emails - Use EMailTemplate in SendConfirmationMailJob for consistent styling - Improve UI with proper Nextcloud Vue components (NcInputField, NcTextArea) - Add comprehensive unit tests for the new service - Clean up Question and ApiController validation logic Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

dtretyakov · 2026-04-30T18:37:23Z

@Chartman123 I rebased the branch and applied the changes.

Other question: should we add a check if sending mails is generally available for the server? In my dev instance, I don't have the mail settings configured, but could enable the confirmation mails...

Now there is a check whether Email is configured by introducing isMailConfigured config property.
It should prevent enabling and using this feature.

Chartman123 · 2026-05-01T18:24:11Z

@dtretyakov from my side it looks good now, just the little suggestion for the migration step regarding notnull.

Chartman123 · 2026-05-01T18:39:26Z

+
+	&__rate-limit {
+		margin-top: calc(var(--default-grid-baseline) * 3);
+		max-width: 300px;
+	}


This max width causes the helper text to be split into new lines within the word boundaries. Do we really need this css rule?

dtretyakov mentioned this pull request Apr 14, 2026

feat: Add confirmation email for form respondents #3098

Closed

dtretyakov marked this pull request as ready for review April 14, 2026 07:10

dtretyakov force-pushed the feat/confirmation-email branch from b111145 to 9452b76 Compare April 14, 2026 07:28

dtretyakov force-pushed the feat/confirmation-email branch 2 times, most recently from 363a0cb to 9cb9c09 Compare April 21, 2026 17:47

Chartman123 requested review from pringelmann and susnux April 21, 2026 21:25

Chartman123 reviewed Apr 21, 2026

View reviewed changes

Chartman123 assigned dtretyakov Apr 21, 2026

Chartman123 added enhancement New feature or request 3. to review Waiting for reviews feature: 📝 submitting responses labels Apr 21, 2026

Chartman123 added this to the 5.3 milestone Apr 21, 2026

Chartman123 reviewed Apr 22, 2026

View reviewed changes

Comment thread lib/Migration/Version050300Date20260413233000.php

Chartman123 reviewed Apr 23, 2026

View reviewed changes

Comment thread lib/Service/FormsService.php Outdated

pringelmann reviewed Apr 23, 2026

View reviewed changes

Comment thread lib/Service/FormsService.php Outdated

pringelmann reviewed Apr 23, 2026

View reviewed changes

dtretyakov force-pushed the feat/confirmation-email branch 4 times, most recently from c7f7327 to 4950eb3 Compare April 23, 2026 22:25

dtretyakov force-pushed the feat/confirmation-email branch from 4950eb3 to 33d9af9 Compare April 24, 2026 08:52

come-nc reviewed Apr 28, 2026

View reviewed changes

Chartman123 reviewed Apr 28, 2026

View reviewed changes

Comment thread lib/Controller/ApiController.php Outdated

Comment thread lib/Controller/ApiController.php Outdated

Comment thread lib/Service/ConfigService.php

github-actions Bot added the feedback-requested label Apr 29, 2026

dtretyakov force-pushed the feat/confirmation-email branch from 9e90ee1 to 394afb8 Compare April 29, 2026 08:11

dtretyakov force-pushed the feat/confirmation-email branch from b2c5303 to 1f60973 Compare April 29, 2026 19:45

Chartman123 reviewed Apr 30, 2026

View reviewed changes

Comment thread lib/Controller/ApiController.php Outdated

Comment thread src/FormsSettings.vue

dtretyakov and others added 10 commits April 30, 2026 20:06

feat: add confirmation email for form respondents

6c110cc

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

refactor: streamline confirmation email recipient setup

c4edd73

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

fix: move confirmation email validation into short branch

3fb94ea

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

Add guarded async confirmation emails

8a3e1ec

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

refactor: address PR review feedback

e93765f

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

refactor: address PR review feedback

96d2988

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

refactor: address PR review feedback

a285496

Signed-off-by: Dmitry Tretyakov <dtretyakov@gmail.com>

dtretyakov force-pushed the feat/confirmation-email branch from 1f60973 to a285496 Compare April 30, 2026 18:31

Chartman123 reviewed May 1, 2026

View reviewed changes

Conversation

dtretyakov commented Apr 14, 2026 • edited by Chartman123 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

dtretyakov commented Apr 14, 2026

Uh oh!

Chartman123 commented Apr 14, 2026

Uh oh!

dtretyakov commented Apr 14, 2026

Uh oh!

Chartman123 commented Apr 14, 2026

Uh oh!

dtretyakov commented Apr 21, 2026

Uh oh!

Chartman123 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pringelmann commented Apr 23, 2026

Uh oh!

Uh oh!

Chartman123 commented Apr 23, 2026

Uh oh!

pringelmann Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Chartman123 Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

pringelmann Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Chartman123 May 1, 2026

Choose a reason for hiding this comment

Uh oh!

pringelmann commented Apr 23, 2026

Uh oh!

dtretyakov commented Apr 23, 2026

Uh oh!

dtretyakov commented Apr 27, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented Apr 29, 2026

Uh oh!

dtretyakov commented Apr 29, 2026

Uh oh!

Uh oh!

Uh oh!

Chartman123 commented Apr 30, 2026

Uh oh!

dtretyakov commented Apr 30, 2026

Uh oh!

Chartman123 commented May 1, 2026

Uh oh!

Chartman123 May 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

dtretyakov commented Apr 14, 2026 •

edited by Chartman123

Loading

codecov Bot commented Apr 14, 2026 •

edited

Loading