Gutenberg 23.8 sends an email when a user is mentioned in a note. The message uses the recipient's language and links back to the editor conversation. Real sites still need to test SMTP delivery, duplicate suppression, recipient lookup, current permissions, role changes, note deletion, retries, mail logging, link safety, and privacy in subjects and previews.
Use this for editorial teams with SMTP plugins, transactional mail services, SSO, custom user locales, disabled accounts, role automation, multisite, staging mail capture, or compliance rules for notifications.
Quick answer
Mention one synthetic user once in a note on a private test post. Trace the note event, selected recipient, locale, wp_mail call, provider message ID, delivery status, editor link, and recipient authorization. Repeat with two mentions, an edited note, a deleted note, a disabled user, a role removed after send, and a temporary mail failure. One accepted mention should create one localized message, while opening the link must run a fresh permission check.
What to check first
- Map WordPress user ID, verified email, preferred locale, site membership, role, and notification eligibility for the fixture.
- Trace one mention from note creation through wp_mail, SMTP handoff, provider message ID, delivery, and editor-link click.
- Test repeated mentions, note edits, note deletion, retries, queue replay, and provider redelivery for duplicate notices.
- Review subject, preheader, body, logs, bounce events, and support exports for private draft text or unnecessary personal data.
- Remove the recipient's role after delivery and verify the old email link no longer opens the post or note.
Diagnostic table
Use this table to connect the observed behavior to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Create a synthetic recipient matrix for locale, role, account status, and multisite membership. | Map WordPress user ID, verified email, preferred locale, site membership, role, and notification eligibility for the fixture. | Recipient language follows the user's locale, not the sender or site default. |
| Join application and provider logs with a stable mention or message identifier. | Trace one mention from note creation through wp_mail, SMTP handoff, provider message ID, delivery, and editor-link click. | Provider logs show one final delivery per accepted mention policy. |
| Define duplicate behavior for edits, retries, and repeated mentions before rollout. | Test repeated mentions, note edits, note deletion, retries, queue replay, and provider redelivery for duplicate notices. | Subjects, previews, and logs contain no unnecessary draft content. |
| Reduce private content in subjects, previews, logs, and external support exports. | Review subject, preheader, body, logs, bounce events, and support exports for private draft text or unnecessary personal data. | Expired sessions and removed roles cannot use an old email link. |
Why this usually happens
- A mail plugin retries after the provider already accepted the first request.
- User locale and site locale are confused during background mail composition.
- A note edit is interpreted as a new mention without an idempotency boundary.
- An editor link relies on the recipient at send time instead of current authorization.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
mention_id: note-774-user-48
recipient_user: 48
recipient_locale: es_ES
wp_mail_attempts: 1
provider_message_id: msg_test_8842
expected_delivery: one
link_check: current_capability_required
Test scenarios to run
Run the same controlled fixture across these branches. Write down the expected result before testing so a surprising response is easy to identify.
| Scenario | Fixture | Expected result |
|---|
| One mention | User locale es_ES | One Spanish notice |
| Edited note | Same user mentioned again | Owned duplicate policy |
| Mail retry | Temporary provider error | One final delivery |
| Role removed | Open prior email link | Fresh permission denial |
Safe fix order
Use a sequence that makes each result easy to prove. Stop when new evidence changes the scope or owner of the problem.
- Create a synthetic recipient matrix for locale, role, account status, and multisite membership.
- Join application and provider logs with a stable mention or message identifier.
- Define duplicate behavior for edits, retries, and repeated mentions before rollout.
- Reduce private content in subjects, previews, logs, and external support exports.
- Retest the editor link after session expiry, role removal, post status changes, and note deletion.
Decision rule
Enable mention emails for the team when one accepted mention creates one localized message, retries are idempotent, private content stays limited, and every link enforces current permissions.
Production verification checklist
- Recipient language follows the user's locale, not the sender or site default.
- Provider logs show one final delivery per accepted mention policy.
- Subjects, previews, and logs contain no unnecessary draft content.
- Expired sessions and removed roles cannot use an old email link.
Field notes
- Use synthetic IDs and examples that can be traced from the first request or interaction to the final record.
- Keep a before and after result for every changed setting, package, selector, route, or deployed version.
- Separate user-visible success from internal success so a green interface cannot hide a failed request or inaccessible control.
- Review the evidence after caches, queues, browser history, and scheduled work have had time to settle.
Questions teams ask during testing
Can this be tested on production?
Use production for read-only checks and one narrow synthetic fixture that cannot charge a card, send customer email, expose personal data, or change inventory. Run upgrades, package changes, cache changes, and destructive repairs on staging first.
What evidence should the test report keep?
Keep exact versions, UTC timestamps, stable synthetic IDs, expected and actual results, screenshots or response excerpts, the decision owner, rollback point, and final verification. Redact credentials, tokens, customer data, private addresses, and infrastructure details.
How long should the observation window stay open?
Keep it open long enough to include at least one cache cycle, scheduled job cycle, and representative traffic period. For release changes, include logged-in and logged-out use plus the first real operational handoff.
When is the task complete?
Complete it when the primary user path passes, downstream records reconcile, failure branches are understood, monitoring is active, and an established owner page links to this guide in context.
Mistakes to avoid
- Changing production before recording exact versions, UTC timestamps, settings, stable fixture IDs, and a reproducible baseline.
- Treating one successful screen as proof that keyboard access, APIs, caches, jobs, reports, analytics, and downstream records agree.
- Testing only an administrator session instead of the devices, roles, networks, locales, and failure branches customers use.
- Closing the work without a named owner, rollback point, observation window, and contextual incoming link from an established guide.
What to tell the client or owner
Give the site owner the affected versions, exact synthetic fixture, UTC timeline, before and after evidence, cause class, decision, rollback point, unresolved risks, and next review date. State which measurements prove success and which observation window remains open.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, security, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, trace WordPress notification delivery.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references