Notes: Email users mentioned in a note

[adamsilverstein]

What

Emails users who are @mentioned in a note. The mention autocomplete UI landed in #79604; this is the notification half of that feature.

Fixes #80719

Related: #73415 - that issue covered both halves, and the autocompleter shipped in #79604.

Note

This PR has been trimmed to the minimal version. Earlier revisions carried a per-thread followers model, which is now tracked in #80279, and a deep link that opened the editor focused on the linked thread, which is a separate enhancement and can follow in a later release.

How

On rest_insert_comment for note comments - the same hook core uses for its post-author notification - gutenberg_notify_note_mentions() parses the mentions out of the saved content and emails each mentioned user.

Mentions are stored as chips carrying the mentioned user's ID in a class token: <span class="wp-note-mention user-N">@Name</span>, the markup #79604 and #80528 landed. Only elements carrying both classes are treated as mentions. The email is composed in the recipient's locale via switch_to_user_locale() and links to the post editor with get_edit_post_link(), the same way core's own note notification does.

Notification audience

• Post author is deliberately left out; core already notifies them of every note via wp_new_comment_via_rest_notify_postauthor(), so excluding them here avoids a duplicate email.
• The note's own author is never notified about their own note.
• Recipients are limited to users who can edit_comment the note, the same bar as the REST API's read permission for notes, so emails can't leak note content to users who can't see the note in the editor.
• Notifications fire only when a note is created; editing a note doesn't re-notify.
• The whole feature honors the existing wp_notes_notify preference.

Extensibility

No new filters. Core's comment_notification_recipients already runs on every note through wp_notify_postauthor(), so extra recipients can be added there; pre_wp_mail and wp_mail can suppress or reroute delivery to another channel; and gutenberg_send_note_notification() is a plain function, so a plugin can notify anyone it likes from its own rest_insert_comment callback.

Testing

1. As an admin, create a second user with an editor role and an email address you can inspect (or install an email logger).
2. Add a note to a block and @mention the second user.
3. The mentioned user receives a "[Site] You were mentioned in a note on ..." email linking to the post editor.
4. Mention yourself: no email. Mention the post author: they get core's regular "new note" email only, no duplicate.

phpunit/notes-mentions-test.php covers mention parsing (non-mention spans and plain anchors ignored, IDs deduped), the mentioned-user email, email content and the editor link, author self-exclusion, post-author exclusion, capability gating, nonexistent-user mentions, the wp_notes_notify off switch, and - through real REST dispatches - that creating a note via POST /wp/v2/comments triggers the email while updating one doesn't, which guards the rest_insert_comment wiring itself.

npm run test:unit:php:base -- --filter Tests_Notes_Mentions

12 tests pass locally. Worth noting the parser previously looked for <a class="wp-note-mention ..."> anchors, which was the markup before #80528 switched mentions to span chips - against current trunk it matched nothing and no email was ever sent. Reverting just the tag name in the parser turns 5 of these tests red, so the coverage does hold the fix down.

Follow-up

• Notes: follow threads you participate in and notify followers of replies #80279 - per-thread followers model (subscribe participants, notify on replies, unfollow link).
• Deep linking the email to the specific thread rather than the post.
• Notifying a user who is @mentioned by a later edit of a note. Today only creation notifies. Doing this well means persisting the mentioned set when the email goes out and diffing it on each update, so nobody gets mailed twice - state keeping that is better as its own change.
• Like Notes: Support inline rich text (bold, italic, link, code) #78242 -> wordpress-develop#11843, this should land in WordPress Core as a real backport; the core PR is Comments: Notify users mentioned in a note wordpress-develop#12548 and this PR carries it in the plugin's lib/compat/wordpress-7.1/ layer in the mean time.

[github-actions]

I just cherry-picked this PR to the wp/7.1 branch to get it included in the next release: d8f2c5f

[t-hamano]

As we are approaching the 7.1 RC1 release tomorrow, I would like to confirm whether it has been agreed to backport this PR to 7.1. The milestone for the core ticket is also not set to 7.1. My understanding was that the mention feature in the 7.1 release would only include autocomplete, with email notifications postponed.

cc @annezazu

[Mamaduka]

I thought this (mentions) was a blessed task. Without notifications, adding a mention to a note does nothing, so the feature doesn't make sense. If we can't ship the notification, then it's better to exclude mentions as well.

[adamsilverstein]

As we are approaching the 7.1 RC1 release tomorrow, I would like to confirm whether it has been agreed to backport this PR to 7.1. The milestone for the core ticket is also not set to 7.1. My understanding was that the mention feature in the 7.1 release would only include autocomplete, with email notifications postponed.

I did milestone the core backport for 7.1 (and update the trac ticket description) and it is mainly awaiting review. I also wasn't sure we were shipping with notifications, but I was convinced my @Mamaduka's argument that mentions are of little value without them. Also we de-scoped the feature quite a bit, removing deep links and the follow + unfollow mechanism, edit tracking and so on for now until we have a more comprehensive notification API in place.

All the feature does now is notify mentioned users when a note is created. This is pretty similar to what we added for notes themselves.

That said, I am also fine with punting the mention feature entirely @t-hamano and will let the release team decide. I do agree that if we remove the notification part, we should probably remove the mention capability entirely. what do you think?

[t-hamano]

That said, I am also fine with punting the mention feature entirely @t-hamano and will let the release team decide. I do agree that if we remove the notification part, we should probably remove the mention capability entirely. what do you think?

perhaps we should be able to ship this feature if there is consensus among the release squads. Let's confirm on Slack. https://wordpress.slack.com/archives/C0B4Q0RJVAT/p1785826459345539?thread_ts=1783621633.996009&cid=C0B4Q0RJVAT

[adamsilverstein]

I will commit the backport before RC and gather feedback.

[annezazu]

Just for transparency, commenting here that this is good to land. I agree that this is a necessary and well scoped change to include for the @mentions feature to be more meaningful.

[ArchitectOfRuin]

One concern with the current implementation is that wp_mail() is called synchronously for every mentioned user from the rest_insert_comment callback.

This means that a note mentioning many users can result in many mail operations being performed within the same REST request. A slow or failing mail transport can therefore make the request slow/fail after only part of the notification batch has been delivered.

There also doesn't appear to be persistent notification state/idempotency around these sends, so a client retry after a request timeout could potentially result in another notification batch.

Would it make sense to track this as a follow-up issue for asynchronous notification delivery, retry/backoff, and idempotency?

I think this would also make the implementation more resilient for sites with a larger number of eligible note recipients.

Another consideration is notification volume. The implementation deduplicates repeated mentions of the same user, which is good, but I don't see a notification-specific limit on the number of recipients or notification events generated by a user.

Even if the expected number of recipients is normally small, it may be worth considering a server-side bound or throttling mechanism so that notification volume cannot grow unexpectedly.

I suggest a follow-up issue covering:

• asynchronous delivery of note notifications;
• persistent notification delivery state;
• retry with exponential backoff for transient mail failures;
• idempotency to prevent duplicate notifications;
• a reasonable upper bound/throttling for notification volume.

The current synchronous implementation seems acceptable as an initial compatibility implementation, but these would be useful safeguards for production deployments.

[adamsilverstein]

One concern with the current implementation is that wp_mail() is called synchronously for every mentioned user from the rest_insert_comment callback.

@ArchitectOfRuin some improvements are certainly welcome here and probably an issue with your specific recommendations. Might be worth doing some research on previous efforts and also the discussion on the related effort to enable following/unfollowing discussion threads:

• Enhanced Notification support for Notes #72184

And:

• Notes: subscribe thread participants as followers and notify them of replies #80281
• Notes: notify thread followers when a thread is resolved or reopened #81544