Document email address validation step for unsubscribe and resubscribe (8.0 backport) by promptless-for-oss · Pull Request #970 · mautic/user-documentation

promptless-for-oss · 2026-09-15T10:34:59Z

Backport of the reviewed unsubscribe/resubscribe email-validation documentation (#913) onto the 8.0 branch, at maintainer @adiati98's request.

Mautic hardens the public unsubscribe and resubscribe flows against leaked Email links. The {unsubscribe_url}, {unsubscribe_text}, and {resubscribe_url} tokens resolve to a validation page: the Contact lands on a 'Confirm your email address' page and must enter the Email address the message was sent to before the unsubscribe or resubscribe completes. The Contact's Email address is no longer embedded in the first-click URL, which protects against leaked or forwarded links and blocks bot-triggered unsubscribes.

Updates the 'Unsubscribing' section of docs/channels/emails.rst (new confirmation workflow, mismatch error, legacy-link behavior, and bot-unsubscribe rationale), documents the new Require email validation for unsubscribe toggle in the 'Unsubscribe settings' section of docs/configuration/settings.rst, and adds a cross-reference from docs/contacts/preference_center.rst.

The content is identical to the reviewed changes on #913; these three files are the same on the 7.3 and 8.0 branches, so the change applies cleanly.

Trigger Events

mautic/mautic PR #16870: Making unsubscribes/resubscribes more secure

Review feedback addressed (@adiati98) — commit 61c2af8, docs/channels/emails.rst:

"We use hyphen instead of parentheses" (line 865): applied — page-not-found (``404``) error → `page-not-found error - ``HTTP 404```.
"Use active instead of passive voice" (line 844): applied — the {unsubscribe_url} bullet now reads "inserts the URL to the Preference Center when you activate it, or to the unsubscribe page if you don't."
"What does 'see below' refer to?" (line 844, {unsubscribe_url}): applied — replaced the vague "see below" with "described later in this section".
"What does 'see below' refer to?" (line 845, {resubscribe_url}): applied — same concrete forward-reference.
"Please address the Vale warnings and suggestions": addressed on the changed lines — fixed the passive "the message was sent to" → "Mautic sent the message to" and cleared the Google.Parens finding via the hyphen edit. Remaining Vale hits on these lines are false positives left intentionally: Mautic.FeatureList "use 'Landing Page'" on generic destination pages (validation page, unsubscribe page, page-not-found), and findings inside the verbatim single-quoted system error strings ('Confirm your email address', 'This email address does not match...'), which must stay unchanged.

@adiati98

…ckport) Backport of the reviewed changes in PR mautic#913 (branch promptless/pr-16870-unsubscribe-validation) onto the 8.0 branch, at the request of maintainer @adiati98. Mautic 7.x/8.x now shows a 'Confirm your email address' validation page where recipients enter the Email address a message was sent to before an unsubscribe or resubscribe link executes, and no longer embeds the Email address in the first-click URL (mautic/mautic PR #16870). Documents this in the Unsubscribing section of channels/emails.rst (including legacy-link behavior and the bot-unsubscribe rationale), the new "Require email validation for unsubscribe" toggle in configuration/settings.rst, and a cross-reference from contacts/preference_center.rst. Content is identical to the reviewed 7.3 PR mautic#913; the three files are the same on 7.3 and 8.0, so the change applies cleanly.

promptless-for-oss · 2026-09-15T10:36:13Z

I noticed that some CI checks failed for this PR. I'm investigating whether the failures are caused by this suggestion. If they're unrelated or pre-existing, I'll leave this suggestion unchanged and create a separate suggestion if a standalone docs fix is needed.

adiati98

@promptless-for-oss please address the Vale warnings and suggestions.

adiati98 · 2026-09-16T17:05:21Z

 - ``{unsubscribe_text}``: inserts a sentence with a link instructing the Contact to click to unsubscribe.
- ``{unsubscribe_url}``: inserts the URL to the preferences center when it's activated, or to the unsubscribe page if not.
- ``{resubscribe_url}``: inserts the URL to the resubscribe page regardless of whether there's a preference centre in use. It resubscribes the Contact. Useful for double opt out Campaigns.
+- ``{unsubscribe_url}``: inserts the URL to the preferences center when it's activated, or to the unsubscribe page if not. The Contact confirms their Email address on a validation page first - see below.


Use active instead of passive voice.

Will do — I'm rewriting this in active voice. I'll follow up here once it's updated.

Done — I've rewritten this in active voice. The {unsubscribe_url} bullet now reads "…when you activate it" rather than the passive phrasing. Pushed in the latest commit.

adiati98 · 2026-09-16T17:06:59Z

 - ``{unsubscribe_text}``: inserts a sentence with a link instructing the Contact to click to unsubscribe.
- ``{unsubscribe_url}``: inserts the URL to the preferences center when it's activated, or to the unsubscribe page if not.
- ``{resubscribe_url}``: inserts the URL to the resubscribe page regardless of whether there's a preference centre in use. It resubscribes the Contact. Useful for double opt out Campaigns.
+- ``{unsubscribe_url}``: inserts the URL to the preferences center when it's activated, or to the unsubscribe page if not. The Contact confirms their Email address on a validation page first - see below.


This is unlcear. What does "see below" here refer to?

Good catch — I'm clarifying what "see below" refers to here. I'll follow up in this thread with the revised wording.

Good catch — the vague "see below" pointed to the email-address validation step documented later in the same section. I've replaced it with "described later in this section" so the reference is concrete. Pushed in the latest commit.

adiati98 · 2026-09-16T17:07:05Z

- ``{unsubscribe_url}``: inserts the URL to the preferences center when it's activated, or to the unsubscribe page if not.
- ``{resubscribe_url}``: inserts the URL to the resubscribe page regardless of whether there's a preference centre in use. It resubscribes the Contact. Useful for double opt out Campaigns.
+- ``{unsubscribe_url}``: inserts the URL to the preferences center when it's activated, or to the unsubscribe page if not. The Contact confirms their Email address on a validation page first - see below.
+- ``{resubscribe_url}``: inserts the URL to the resubscribe page regardless of whether there's a preference centre in use. It resubscribes the Contact. Useful for double opt out Campaigns. As with unsubscribe links, the Contact confirms their Email address on a validation page first - see below.


This is unlcear. What does "see below" here refer to?

Good catch — I'm clarifying what "see below" refers to here. I'll follow up in this thread with the revised wording.

Good catch — the vague "see below" pointed to the validation step described later in the same section. I've replaced it with "described later in this section" so the reference is concrete. Pushed in the latest commit.

adiati98 · 2026-09-16T17:08:46Z

+
+.. note::
+
+   Links in Emails sent by older versions of Mautic no longer unsubscribe or resubscribe automatically on click. If Mautic still has a record of that send, it redirects the Contact to the same confirmation page. If it doesn't, an unsubscribe link shows a 'Record not found.' message, and a resubscribe link shows a page-not-found (``404``) error.


We use hyphen instead of parentheses.

Thanks — I'm updating this to use a hyphen instead of parentheses. I'll follow up here once the change is in.

Done — I've switched to the hyphen style. This now reads "page-not-found error - HTTP 404" instead of using parentheses. Pushed in the latest commit.

promptless-for-oss · 2026-09-16T17:12:21Z

In reply to this discussion

On it — I'm working through the outstanding Vale warnings and suggestions on the changed files. I'll follow up here once they're resolved.

- Replace parentheses with hyphen for HTTP 404 (adiati98 review) - Rewrite {unsubscribe_url} bullet in active voice - Replace vague 'see below' references with concrete forward-references - Fix passive voice on validation-page paragraph

promptless-for-oss · 2026-09-16T17:29:46Z

In reply to this discussion

Addressed — I've worked through the Vale findings on the changed lines: fixed the passive-voice hit on the validation paragraph ("the message was sent to" → "Mautic sent the message to") and cleared the parentheses finding via the hyphen edit above. The remaining suggestions on these lines are false positives I've left intentionally: the "use Landing Page" hits fall on generic destination pages (the validation page, the unsubscribe page, the page-not-found error), not the Landing Page feature, and the others are inside verbatim quoted system messages that need to stay exact.

One note: I applied your feedback but the tooling couldn't auto re-request your review — our contributor account doesn't have that permission on this upstream repo, so you'll see the new commit on the PR rather than a fresh review request.

promptless-for-oss requested review from a team, adiati98 and favour-chibueze September 15, 2026 10:35

promptless-for-oss mentioned this pull request Sep 15, 2026

Document email address validation step for unsubscribe and resubscribe #913

Open

Merge branch '8.0' into promptless/pr-16870-unsubscribe-validation-8.0

c0c11a7

adiati98 added this to the Mautic 7.3 milestone Sep 16, 2026

adiati98 requested changes Sep 16, 2026

View reviewed changes

Merge branch '8.0' into promptless/pr-16870-unsubscribe-validation-8.0

f9f421e

Address review feedback on Unsubscribing section

61c2af8

- Replace parentheses with hyphen for HTTP 404 (adiati98 review) - Rewrite {unsubscribe_url} bullet in active voice - Replace vague 'see below' references with concrete forward-references - Fix passive voice on validation-page paragraph


		.. note::

		Links in Emails sent by older versions of Mautic no longer unsubscribe or resubscribe automatically on click. If Mautic still has a record of that send, it redirects the Contact to the same confirmation page. If it doesn't, an unsubscribe link shows a 'Record not found.' message, and a resubscribe link shows a page-not-found (``404``) error.

Uh oh!

Conversation

promptless-for-oss commented Sep 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

promptless-for-oss commented Sep 15, 2026

Uh oh!

adiati98 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

promptless-for-oss commented Sep 16, 2026

Uh oh!

promptless-for-oss commented Sep 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

promptless-for-oss commented Sep 15, 2026 •

edited

Loading