[docs] Added docs for Email Batches #306

Closes: #306 Co-authored-by: Federico Capoano <f.capoano@openwisp.io>
openwisp · Dec 27, 2024 · d04820a · d04820a
1 parent c2489b1
commit d04820a
Show file tree

Hide file tree

Showing 4 changed files with 80 additions and 13 deletions.
diff --git a/docs/user/intro.rst b/docs/user/intro.rst
@@ -7,7 +7,8 @@ include:
 
 - :doc:`sending-notifications`
 - :ref:`notifications_web_notifications`
-- :ref:`notifications_email_notifications`
+- :ref:`notifications_email_notifications` and
+  :ref:`notifications_batches`
 - :doc:`notification-types`
 - :doc:`User notification preferences <notification-preferences>`
 - :ref:`Silencing notifications for specific objects temporarily or

diff --git a/docs/user/settings.rst b/docs/user/settings.rst
@@ -156,3 +156,34 @@ The default configuration is as follows:
         # Maximum interval after which the notification widget should get updated (in seconds)
         "max_allowed_backoff": 15,
     }
+
+.. _openwisp_notifications_email_batch_interval:
+
+``OPENWISP_NOTIFICATIONS_EMAIL_BATCH_INTERVAL``
+-----------------------------------------------
+
+======= =================================
+Type    ``int``
+Default ``1800`` (30 minutes, in seconds)
+======= =================================
+
+This setting determines the :ref:`interval of the email batching feature
+<notifications_batches>`.
+
+The interval is specified in seconds.
+
+To send email notifications immediately without batching, set this value
+to ``0``.
+
+.. _openwisp_notifications_email_batch_display_limit:
+
+``OPENWISP_NOTIFICATIONS_EMAIL_BATCH_DISPLAY_LIMIT``
+----------------------------------------------------
+
+======= =======
+Type    ``int``
+Default ``15``
+======= =======
+
+This setting specifies the maximum number of email notifications that can
+be included in a single :ref:`email batch <notifications_batches>`.
diff --git a/docs/user/web-email-notifications.rst b/docs/user/web-email-notifications.rst
@@ -54,3 +54,38 @@ Email Notifications
 Along with web notifications OpenWISP Notifications also sends email
 notifications leveraging the :ref:`send_email feature of OpenWISP Utils
 <utils_send_email>`.
+
+.. _notifications_batches:
+
+Email Batches
+~~~~~~~~~~~~~
+
+.. figure:: https://i.imgur.com/W5P009W.png
+    :target: https://i.imgur.com/W5P009W.png
+    :align: center
+
+Batching email notifications helps manage the flow of emails sent to
+users, especially during periods of increased alert activity. By grouping
+emails into batches, the system minimizes the risk of emails being marked
+as spam and prevents inboxes from rejecting alerts due to high volumes.
+
+Key aspects of the batch email notification feature include:
+
+- When multiple emails are triggered for the same user within a short time
+  frame, subsequent emails are grouped into a summary.
+- The sending of individual emails is paused for a specified batch
+  interval when batching is enabled.
+
+.. note::
+
+    If new alerts are received while a batch is pending, they will be
+    added to the current summary without resetting the timer. The batched
+    email will be sent when the initial batch interval expires.
+
+You can customize the behavior of batch email notifications using the
+following settings:
+
+- :ref:`OPENWISP_NOTIFICATIONS_EMAIL_BATCH_INTERVAL
+  <openwisp_notifications_email_batch_interval>`.
+- :ref:`OPENWISP_NOTIFICATIONS_EMAIL_BATCH_DISPLAY_LIMIT
+  <openwisp_notifications_email_batch_display_limit>`.
diff --git a/openwisp_notifications/templates/emails/batch_email.html b/openwisp_notifications/templates/emails/batch_email.html
@@ -15,6 +15,9 @@
         .alert.success {
             background-color: #e6f9e8;
         }
+        .alert.warning {
+            background-color: #fff8e1;
+        }
         .alert h2 {
             margin: 0 0 5px 0;
             font-size: 16px;
@@ -27,15 +30,6 @@
             text-overflow: ellipsis;
             vertical-align: middle;
         }
-        .alert.error h2 {
-            color: #d9534f;
-        }
-        .alert.info h2 {
-            color: #333333;
-        }
-        .alert.success h2 {
-            color: #1c8828;
-        }
         .alert p {
             margin: 0;
             font-size: 14px;
@@ -65,18 +59,24 @@
         .badge.success {
             background-color: #1c8828;
         }
+        .badge.warning {
+            background-color: #f0ad4e;
+        }
         .alert a {
             text-decoration: none;
         }
-        .alert.error a {
+        .alert.error a, .alert.error h2 {
             color: #d9534f;
         }
-        .alert.info a {
+        .alert.info a, .alert.info h2 {
             color: #333333;
         }
-        .alert.success a {
+        .alert.success a, .alert.success h2 {
             color: #1c8828;
         }
+        .alert.warning a, .alert.warning h2 {
+            color: #f0ad4e;
+        }
         .alert a:hover {
             text-decoration: underline;
         }