feat: Add confirmation email for form respondents

[dtretyakov]

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]

Codecov Report

❌ Patch coverage is 67.63485% 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]

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

Now the form looks like that:

[Chartman123]

@dtretyakov looks good :)

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

[dtretyakov]

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]

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

[dtretyakov]

@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]

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]

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]

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]

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

1. 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.
2. 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.
3. 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.
4. 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]

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

[github-actions]

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]

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.