First version of moderation emails #9587

marcospri · 2025-05-26T15:54:03Z

Send emails on moderation status changes

Templates for moderation emails
Emit a ModerationEvent on the set_status view
Preview moderation emails on the admin pages

Docs

Follow up tasks (in the project board)

Link KB article on these emails about moderation.
Tune the subject for better threading.
Also send these in non pre-moderated groups.
Add a dropdown to be able to preview all status emails in the admin pages

Testing

Check the email template render in http://localhost:5000/admin/email
In a pre moderated group, create an annotation (or grab the ID of an existing one), with curl we can test the email sending:

curl  -i 'http://localhost:5000/api/annotations/ANNOTATION_ID/moderation' -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'Accept: */*' \
  -H 'x-csrf-token: TOKEN' \
  -b 'auth=AUTH' \
  --data '{"annotation_updated":"2025-05-15T13:40:41.997487+00:00", "moderation_status": "DENIED"}'

In the console you'll see traces of the email being "sent":

worker (stderr)      | [2025-05-27 16:19:51,075: INFO/MainProcess] Task h.tasks.email.send[56486ba7-6cb5-45ba-b0af-f77ed591ac4f] received
worker (stderr)      | [2025-05-27 16:19:51,077: INFO/ForkPoolWorker-16] h.tasks.email.send[56486ba7-6cb5-45ba-b0af-f77ed591ac4f]: emailing in debug mode: check the `mail/` directory
worker (stderr)      | [2025-05-27 16:19:51,079: INFO/ForkPoolWorker-16] h.tasks.email.send[56486ba7-6cb5-45ba-b0af-f77ed591ac4f]: Sent email: tag='moderated_notification', sender_id=3, recipient_ids=[3], annotation_id='MeEgsjGSEfCvzqNvsMlrIg'
worker (stderr)      | [2025-05-27 16:19:51,083: INFO/ForkPoolWorker-16] h.tasks.email.send[56486ba7-6cb5-45ba-b0af-f77ed591ac4f] Task h.tasks.email.send[56486ba7-6cb5-45ba-b0af-f77ed591ac4f] succeeded in 0.003097740998782683s: None

marcospri · 2025-05-27T12:59:28Z

h/routes.py

@@ -58,6 +58,10 @@ def includeme(config):  # noqa: PLR0915
        "admin.email.preview.mention_notification",
        "/admin/email/preview/mention-notification",
    )
+    config.add_route(


New route to preview the email.

marcospri · 2025-05-27T12:59:44Z

h/services/annotation_moderation.py

@@ -26,23 +46,27 @@ def set_status(
        annotation: Annotation,
        status: ModerationStatus | None,
        user: User | None = None,
-    ) -> None:
+    ) -> ModerationLog | None:


Refactor this method to return the resulting log entry.

marcospri · 2025-05-27T13:00:38Z

h/services/annotation_moderation.py

+            report_exception(err)
+
+    @staticmethod
+    def email_subject(group_name: str, new_status: ModerationStatus) -> str:


Using regular python (instead of template logic) for these.

Easier to test them IMO.

marcospri · 2025-05-27T13:01:13Z

h/templates/emails/moderated_annotation_notification.html.jinja2

@@ -0,0 +1,722 @@
+<!doctype html>


We could consider using a base template for these like in LMS.

If it's looking the same as for mention emails, yes, I think we should extract a common layout at some point.

marcospri · 2025-05-27T13:01:58Z

tests/common/factories/moderation_log.py

+from .base import ModelFactory
+
+
+class ModerationLog(ModelFactory):


Missing factory for this model.

marcospri · 2025-05-27T13:03:06Z

h/services/annotation_moderation.py

+            return f"Your comment in {group_name} is pending approval"
+
+        msg = f"Unexpected moderation status change to {new_status}"  # pragma: no cover
+        raise ValueError(msg)


This shouldn't be possible because we check the states for which we send emails but just in case we make a mistake we don't want to send an email with an empty subject or description.

marcospri · 2025-05-27T13:06:10Z

h/views/admin/email.py

+    return {
+        "user_display_name": "Jane Doe",
+        "status_change_description": AnnotationModerationService.email_status_change_description(
+            "GROUP NAME", ModerationStatus.APPROVED


These would be nicer if we had a simple dropdown to be able to preview different statuses.

Added a card to the board to track that.

marcospri · 2025-05-27T14:22:43Z

h/models/notification.py

@@ -20,6 +20,7 @@ class EmailTag(StrEnum):
    RESET_PASSWORD = "reset_password"  # noqa: S105
    MENTION_NOTIFICATION = "mention_notification"
    TEST = "test"
+    MODERATED = "moderated_notification"


New email tag.

The rest of the entries seem to be nouns. Maybe this one should be MODERATION instead of MODERATED?

marcospri · 2025-05-27T14:24:19Z

h/services/annotation_moderation.py

+                    user_id=author.userid, type_=Subscriptions.Type.MODERATED
+                ),
+            ),
+            "preferences_url": request.route_url("account_notifications"),


This URL still doesn't list this type of email, added a card to the board about it.

acelaya

Looks good in general, but I suggested we use nouns as in "moderation" or "annotation moderation" instead of "moderated" or "moderated annotation" in various places.

It sounds more natural and is more consistent with other types of events and notifications.

acelaya · 2025-05-28T08:14:47Z

h/models/notification.py

@@ -20,6 +20,7 @@ class EmailTag(StrEnum):
    RESET_PASSWORD = "reset_password"  # noqa: S105
    MENTION_NOTIFICATION = "mention_notification"
    TEST = "test"
+    MODERATED = "moderated_notification"


The rest of the entries seem to be nouns. Maybe this one should be MODERATION instead of MODERATED?

h/models/subscriptions.py

h/routes.py

acelaya · 2025-05-28T08:25:52Z

h/services/annotation_moderation.py

+            return f"Your comment in {group_name} has been declined"
+
+        if new_status == ModerationStatus.APPROVED:
+            return f"Your comment in {group_name} has been approved"
+
+        if new_status == ModerationStatus.PENDING:
+            return f"Your comment in {group_name} is pending approval"
+


Should we say "comment" or "annotation"?

I know we use the "comment" terminology in other places, but maybe it's worth discussing with the wider group. It should not block merging this PR though.

You're right, I didn't address this in a comment.

TLDR (IMO): we can merge this version, and I’ll link to this comment from the board. I already have a vague "Send moderation emails in non-pre-moderated groups" card there, but I reckon most of the work there will be this issue.

The "comment" wording is what bioRxiv wants, so we’ll start with that. This PR only sends emails for pre-moderated groups, which are only offered to bioRxiv, so this will work for them.

Of course, we’ll want to send these in all cases eventually, so we have a few options:

Use the "comment" wording everywhere.
I don't like this. It would be odd if this were the only place where annotations become comments.

Convince bioRxiv to use “annotation” instead.
I don't think this is likely.

Use the "comment" wording everywhere, but just for "page notes".
Not ideal to use both page note and comment for the same thing, but this would be easy to implement.

Use different templates or a conditional to show comment for bioRxiv and annotation for others.
While this seems like the obvious solution, I’m not sure how we’d determine this—by authority? Organization? The group the annotation is in?

acelaya · 2025-05-28T08:28:49Z

h/templates/emails/moderated_annotation_notification.html.jinja2

Following my previous comments, maybe this file should be named annotation_moderation_notification.html.jinja2

acelaya · 2025-05-28T08:31:30Z

h/templates/emails/moderated_annotation_notification.html.jinja2

@@ -0,0 +1,722 @@
+<!doctype html>


If it's looking the same as for mention emails, yes, I think we should extract a common layout at some point.

- Templates for moderation emails - Emit a ModerationEvent on the set_status view - Preview moderation emails on the admin pages

acelaya

👍🏼

Return new moderation log entry created on moderation changes

dd60ce3

marcospri force-pushed the moderation-emails-simple branch 4 times, most recently from ede5484 to 7141ba1 Compare May 27, 2025 14:01

marcospri changed the title ~~[WIP] Moderation emails simple~~ First version of moderation emails May 27, 2025

marcospri force-pushed the moderation-emails-simple branch from 7141ba1 to d67bafa Compare May 27, 2025 14:13

marcospri commented May 27, 2025

View reviewed changes

marcospri marked this pull request as ready for review May 27, 2025 14:26

marcospri requested a review from acelaya May 27, 2025 14:26

acelaya reviewed May 28, 2025

View reviewed changes

marcospri force-pushed the moderation-emails-simple branch from 1c8384b to e9e353c Compare May 28, 2025 11:29

Send emails on moderation status changes

95971a3

- Templates for moderation emails - Emit a ModerationEvent on the set_status view - Preview moderation emails on the admin pages

marcospri force-pushed the moderation-emails-simple branch from e9e353c to 95971a3 Compare May 28, 2025 11:53

acelaya approved these changes May 28, 2025

View reviewed changes

		from .base import ModelFactory


		class ModerationLog(ModelFactory):

First version of moderation emails #9587

Are you sure you want to change the base?

First version of moderation emails #9587

Uh oh!

Conversation

marcospri commented May 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docs

Follow up tasks (in the project board)

Testing

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!

acelaya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

acelaya left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

marcospri commented May 26, 2025 •

edited

Loading