Document email address validation step for unsubscribe and resubscribe (8.0 backport)

[promptless-for-oss]

Description

Backport of the reviewed unsubscribe/resubscribe email-validation documentation (PR #913, branch promptless/pr-16870-unsubscribe-validation) 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 stays aligned with the reviewed changes on PR #913.

Latest change (link fix ported from #913) — commit ports the link fix @adiati98 approved on #913 to this 8.0 backport, at the maintainer's request. In the Require email validation for unsubscribe bullet of docs/configuration/settings.rst, the closing sentence's whole-page reference See the Unsubscribing section of the :doc:/channels/emails documentation … becomes the section cross-reference See the :ref:Unsubscribing section of the Email documentation …, so it links directly to the "Unsubscribing" section rather than the whole page. The :ref: target resolves to the "Unsubscribing" heading present in docs/channels/emails.rst on this branch. This is the identical link form already applied and approved on the 7.3 sibling PR #913; the two now read the same at that spot.

Reviewer-feedback disposition (this pass)

• @adiati98 "apply the link fix to Document email address validation step for unsubscribe and resubscribe (8.0 backport) #970" (requested on Document email address validation step for unsubscribe and resubscribe #913): applied verbatim — the :ref: section-link form from Document email address validation step for unsubscribe and resubscribe #913's commit 72c87c36 was reproduced on docs/configuration/settings.rst. Verified the :ref: target Unsubscribing resolves unambiguously on this branch.

Linked issue

Screenshots or screen recordings

Not applicable — RST documentation-only change (a cross-reference link form).

---

Open in Promptless

[promptless-for-oss]

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.

[promptless-for-oss]

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.

[promptless-for-oss]

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.

[adiati98]

@promptless-for-oss apply the latest changes to #913

[promptless-for-oss]

In reply to this discussion

Got it — I'll bring this 8.0 backport in line with the latest reviewed changes on #913. I'll follow up here once the branch is updated.

[promptless-for-oss]

In reply to this discussion

Blocked — one thing needed from you

Before I change anything: applying #913's current content onto this 8.0 backport would revert your own review on #970. The branches differ only in four spots in emails.rst where #970 is already ahead of #913 — the active-voice rewording, the clearer phrasing in place of "see below", and the hyphen instead of parentheses — and #913 has had no newer unsubscribe change since it was last reviewed, so there's nothing newer on #913 to carry over.

Need: Confirm the direction — should I instead bring #913 up to #970's reviewed wording so the two converge, or is there a specific newer change you'd like applied here?
Next: Once you confirm, I'll make the change and follow up in this thread.

[adiati98]

In reply to this discussion

Blocked — one thing needed from you

Before I change anything: applying #913's current content onto this 8.0 backport would revert your own review on #970. The branches differ only in four spots in emails.rst where #970 is already ahead of #913 — the active-voice rewording, the clearer phrasing in place of "see below", and the hyphen instead of parentheses — and #913 has had no newer unsubscribe change since it was last reviewed, so there's nothing newer on #913 to carry over.

Need: Confirm the direction — should I instead bring #913 up to #970's reviewed wording so the two converge, or is there a specific newer change you'd like applied here? Next: Once you confirm, I'll make the change and follow up in this thread.

I mean, bring the changes of the active-voice rewording, the clearer phrasing in place of "see below", and the hyphen instead of parentheses to #913

[promptless-for-oss]

In reply to this discussion

Got it, and thanks for confirming — I'll bring the active-voice rewording, the clearer phrasing in place of 'see below', and the hyphen instead of parentheses over to #913. I'll follow up here once that's done.

[promptless-for-oss]

In reply to this discussion

Done — I've brought the three wording improvements from #970 into #913's channels/emails.rst Unsubscribing section: the active-voice rewording, 'described later in this section' in place of 'see below', and the hyphen instead of parentheses on the HTTP 404 note. The two now read the same at those spots.

I deliberately left out #970's one other difference — the note that the legacy data-mautic-disable-tracking attribute is removed in Mautic 8.0 — since that's 8.0-specific and doesn't apply to #913's 7.3 branch.

One heads-up: the failing check on #913 is a pre-existing link-check failure unrelated to this edit (a broken external link plus some longstanding heading/label warnings), not something this change introduced.

Docs PR: #913

[adiati98]

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

[promptless-for-oss]

In reply to this discussion

Thanks — I'm on it. I'll run Vale on the changed files, fix the flagged warnings, and follow up here once the PR is clean.

[promptless-for-oss]

In reply to this discussion

Done — the Vale warnings on the changed lines are now cleared and PR #970 is clean under the project's Vale config. Where the warnings were the Mautic.FeatureList suggestion on genuinely generic wording, I reworded our own prose to drop the unnecessary "validation page" references — the dedicated paragraph and the :ref: cross-reference already explain the step. Where they fell on text we quote verbatim from the product (the 'Confirm your email address' page title, the exact mismatch error, the Require email validation for unsubscribe setting label, 'Record not found.', and HTTP 404), I wrapped those blocks in .. vale off/.. vale on — the same convention already used elsewhere in this repo — so the annotations clear while the product's exact wording stays intact.

I kept this aligned with the primary PR #913 (identical wording), and the 8.0-specific data-mautic-disable-tracking note was preserved. Ready for another look.

[promptless-for-oss]

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.