mattermost · harshilsharma63 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026 · Aug 14, 2026
diff --git a/source/administration-guide/compliance-with-mattermost.rst b/source/administration-guide/compliance-with-mattermost.rst
@@ -15,11 +15,13 @@ Mattermost is purpose-built to help enterprises keep sensitive data safe and com
     Export channel data </administration-guide/comply/export-mattermost-channel-data>
     Legal Hold </administration-guide/comply/legal-hold>
     JSON audit log schema </administration-guide/comply/embedded-json-audit-log-schema>
+    Post delivery audit logging </administration-guide/comply/post-delivery-audit-logging>
 
 * :doc:`Compliance exports </administration-guide/comply/compliance-export>` - Export compliance reports to third-party systems to archive history.
 * :doc:`Compliance monitoring </administration-guide/comply/compliance-monitoring>` - Enable oversight and prevent unauthorized queries with compliance exports.
 * :doc:`Electronic discovery </administration-guide/comply/electronic-discovery>` - Extract data from Mattermost for eDiscovery.
 * :doc:`Data retention </administration-guide/comply/data-retention-policy>` - Control how long data is stored in Mattermost with global and custom retention policies to meet data retention compliance requirements.
 * :doc:`Export channel data </administration-guide/comply/export-mattermost-channel-data>` - Migrate data between systems and back data up for operational continuity.
 * :doc:`Legal Hold </administration-guide/comply/legal-hold>` - Preserve relevant Mattermost information when litigation is anticipated.
-* :doc:`JSON audit log schema </administration-guide/comply/embedded-json-audit-log-schema>` - Learn how to configure Mattermost audit logging using a JSON object.
+* :doc:`JSON audit log schema </administration-guide/comply/embedded-json-audit-log-schema>` - Learn the JSON structure of Mattermost audit log entries.
+* :doc:`Post delivery audit logging </administration-guide/comply/post-delivery-audit-logging>` - Record an audit log entry each time a message is delivered to a user, to establish which users a given message reached.
diff --git a/source/administration-guide/comply/embedded-json-audit-log-schema.rst b/source/administration-guide/comply/embedded-json-audit-log-schema.rst
@@ -356,6 +356,19 @@ Posts & Content Events
 .. note::
    From Mattermost v11.5.0, audit log entries for posts and content access events include a ``non_channel_member_access`` field in the ``meta`` object. When a user accesses posts or content in a channel they are not a member of, this field is set to ``true``. Admins can use this indicator to identify and review unauthorized or unexpected content access in their audit logs.
 
+Post Delivery Events
+~~~~~~~~~~~~~~~~~~~~
+
+Mattermost v12.0 introduces the ``postDelivered`` audit log event, which records each delivery of a message's content to a user or an integration. It's emitted only when :doc:`post delivery audit logging </administration-guide/comply/post-delivery-audit-logging>` is enabled, which is disabled by default. Unlike the other audit log events on this page, ``postDelivered`` is emitted at the dedicated ``audit-delivery`` log level and so requires its own audit log target. See that page for the record format, the payload fields, and the full set of delivery mechanisms.
+
++----------------------------------+-------------------------------------------------------------------+
+| **Event Name**                   | **Description**                                                   |
++==================================+===================================================================+
+| ``postDelivered``                | Delivering post content to a user or integration                  |
++----------------------------------+-------------------------------------------------------------------+
+| ``updateDeliveryTrackingConfig`` | Updating the post delivery audit logging configuration            |
++----------------------------------+-------------------------------------------------------------------+
+
 Authentication and Security Events
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/source/administration-guide/comply/post-delivery-audit-logging.rst b/source/administration-guide/comply/post-delivery-audit-logging.rst
@@ -0,0 +1,214 @@
+Post delivery audit logging
+============================
+
+.. include:: ../../_static/badges/entry-adv.rst
+  :start-after: :nosearch:
+
+From Mattermost v12.0, Mattermost can record an audit log entry each time a message's content is delivered to a user or to an integration. These records let you establish which users a given message was delivered to, and by what means.
+
+.. note::
+
+  Post delivery audit logging is currently in :ref:`Beta <administration-guide/manage/feature-labels:beta>`.
+
+Delivery records are ordinary audit log records, written through the existing audit logging pipeline to whichever audit log targets you've configured.
+
+Before you begin
+----------------
+
+Post delivery audit logging requires all of the following:
+
+- A Mattermost Enterprise Advanced license.
+- The `feature flag <https://developers.mattermost.com/contribute/more-info/server/feature-flags/#changing-feature-flag-values>`_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default. **Restart the server after enabling the feature flag**.
+- Advanced Logging > Advanced Logging to be enabled
+- An audit log target that consumes the ``audit-delivery`` log level in the advanced audit log config.
+
+.. important::
+
+  Enabling post delivery audit logging on its own produces no output. Delivery records are discarded until an audit log target consumes the ``audit-delivery`` log level. Configure the target before you enable the feature. The log volume increases substantially once these audit logs are enabled.
+
+Configure an audit log target
+-----------------------------
+
+Delivery records are written at the ``audit-delivery`` log level, ID ``104``. Unlike the other :ref:`audit log levels <administration-guide/manage/logging:log levels>`, ``audit-delivery`` isn't written by the built-in audit log file target, so enabling ``ExperimentalAuditSettings.FileEnabled`` doesn't capture delivery records. Add a target that consumes level ``104`` to ``ExperimentalAuditSettings.AdvancedLoggingJSON`` instead. See :ref:`advanced logging <administration-guide/manage/logging:advanced logging>` for the available target types and options.
+
+We recommend a dedicated target, so that the volume of delivery records doesn't overwhelm your other audit records. The example below writes delivery records to their own file, rotated at 100 MB, with up to 10,000 records buffered in memory while writing:
+
+.. code-block:: JSON
+
+    {
+        "post-delivery-audit": {
+            "type": "file",
+            "format": "json",
+            "levels": [
+                { "id": 104, "name": "audit-delivery" }
+            ],
+            "options": {
+                "filename": "./logs/post-delivery-audit.log",
+                "max_size": 100,
+                "max_age": 0,
+                "max_backups": 0,
+                "compress": true
+            },
+            "maxqueuesize": 10000
+        }
+    }
+
+If post delivery audit logging is enabled and no audit log target consumes the ``audit-delivery`` level, the configuration remains valid, delivery records are discarded, and Mattermost logs the following warning at startup and whenever the configuration changes:
+
+.. code-block:: text
+
+    DeliveryTrackingSettings.Enable is enabled but no configured audit log target consumes the audit-delivery level; post delivery audit records will be discarded. Add a target for the level via ExperimentalAuditSettings.AdvancedLoggingJSON.
+
+Enable post delivery audit logging
+----------------------------------
+
+In the System Console, enable post delivery audit logging and choose the channels that deliveries are recorded in by going to **Site Configuration > Data Spillage Handling > Post Delivery Audit Logging**. See :ref:`administration-guide/manage/admin/content-flagging:post delivery audit logging` for the steps, and :ref:`administration-guide/configure/site-configuration-settings:content flagging` for the corresponding ``config.json`` settings and environment variables.
+
+Record format
+-------------
+
+Each delivery is recorded as a ``postDelivered`` audit log record. The ``status`` of the record is always ``success``.
+
+**The recipient of the message is the actor of the record**, in ``actor.user_id``. There's no separate recipient field. This lets you group records by actor to answer "what was delivered to this user". Deliveries to a plugin or to an outgoing webhook have no human recipient, so ``actor.user_id`` is empty and ``meta.plugin_id`` or ``meta.webhook_id`` identifies the integration instead.
+
+The ``meta`` object identifies what was delivered and how. Unlike audit records emitted from a REST API request, delivery records carry no ``api_path`` or ``cluster_id`` in ``meta``.
+
+A message delivered to a user through the Mattermost REST API:
+
+.. code-block:: json
+
+    {
+        "timestamp": "2026-08-12 14:03:11.482 Z",
+        "event_name": "postDelivered",
+        "status": "success",
+        "actor": {
+            "user_id": "hx4k9m2qzbfytr7wn6cbd3jvse",
+            "session_id": "",
+            "client": "",
+            "ip_address": ""
+        },
+        "meta": {
+            "post_id": "xpw97hf6kfncirzhqisb5sym7e",
+            "channel_id": "pfis7ycuy78o7m3zebajmxqeuo",
+            "mechanism": "product"
+        },
+        "error": {}
+    }
+
+The same message delivered to a plugin, with no human recipient:
+
+.. code-block:: json
+
+    {
+        "timestamp": "2026-08-12 14:03:11.509 Z",
+        "event_name": "postDelivered",
+        "status": "success",
+        "actor": {
+            "user_id": "",
+            "session_id": "",
+            "client": "",
+            "ip_address": ""
+        },
+        "meta": {
+            "post_id": "xpw97hf6kfncirzhqisb5sym7e",
+            "channel_id": "pfis7ycuy78o7m3zebajmxqeuo",
+            "mechanism": "plugin",
+            "plugin_id": "com.mattermost.example-plugin"
+        },
+        "error": {}
+    }
+
+See the :doc:`audit log JSON schema </administration-guide/comply/embedded-json-audit-log-schema>` for the fields common to every Mattermost audit log record.
+
+Payload fields
+--------------
+
+The ``meta`` object of a ``postDelivered`` record contains the following fields. The recipient isn't in ``meta`` — the recipient is the actor of the record, in ``actor.user_id``.
+
++--------------------+---------------+-----------------------------------------------------------------------+
+| **Field name**     | **Data type** | **Description**                                                       |
++====================+===============+=======================================================================+
+| post_id            | string        | Always present. The unique identifier of the message whose content    |
+|                    |               | was delivered.                                                        |
++--------------------+---------------+-----------------------------------------------------------------------+
+| channel_id         | string        | Always present. The unique identifier of the channel that the message |
+|                    |               | belongs to.                                                           |
++--------------------+---------------+-----------------------------------------------------------------------+
+| mechanism          | string        | Always present. How the message content reached the recipient. See    |
+|                    |               | `delivery mechanisms <#delivery-mechanisms>`__ for the possible       |
+|                    |               | values.                                                               |
++--------------------+---------------+-----------------------------------------------------------------------+
+| plugin_id          | string        | Present for ``plugin`` deliveries only. The plugin that the message   |
+|                    |               | content was passed to.                                                |
++--------------------+---------------+-----------------------------------------------------------------------+
+| webhook_id         | string        | Present for ``outgoing_webhook`` deliveries only. The outgoing        |
+|                    |               | webhook that the message content was sent to.                         |
++--------------------+---------------+-----------------------------------------------------------------------+
+| via_post_id        | string        | Present for ``permalink_preview`` deliveries only. The message that   |
+|                    |               | embedded the permalink preview.                                       |
++--------------------+---------------+-----------------------------------------------------------------------+
+| via_channel_id     | string        | Present for ``permalink_preview`` deliveries only. The channel        |
+|                    |               | containing the message that embedded the permalink preview.           |
++--------------------+---------------+-----------------------------------------------------------------------+
+
+Delivery mechanisms
+-------------------
+
+The ``mechanism`` field records how the message content reached the recipient. It's always one of the following seven values:
+
++-----------------------+--------------------------------------------------------------------------------+
+| **Value**             | **Delivery**                                                                   |
++=======================+================================================================================+
+| ``product``           | Any read of message content through the Mattermost REST API. This covers       |
+|                       | channel loads, thread and reply views, search results, direct fetches of a     |
+|                       | message by ID, pinned messages, saved messages, and message edit history.      |
++-----------------------+--------------------------------------------------------------------------------+
+| ``post_broadcast``    | A new or edited message pushed over WebSocket to connected channel members.    |
++-----------------------+--------------------------------------------------------------------------------+
+| ``permalink_preview`` | A message rendered as a permalink preview inside another message.              |
++-----------------------+--------------------------------------------------------------------------------+
+| ``email``             | Message content included in a notification email.                              |
++-----------------------+--------------------------------------------------------------------------------+
+| ``push``              | Message content included in a push notification payload, and the               |
+|                       | acknowledgement fetch that retrieves content for an ID-only push notification. |
++-----------------------+--------------------------------------------------------------------------------+
+| ``outgoing_webhook``  | Message content sent to an outgoing webhook.                                   |
++-----------------------+--------------------------------------------------------------------------------+
+| ``plugin``            | A message passed to a plugin's ``MessageWillBePosted`` or                      |
+|                       | ``MessageWillBeUpdated`` hook, or read through the plugin API.                 |
++-----------------------+--------------------------------------------------------------------------------+
+
+.. note::
+
+  Channel loads, thread views, search results, and direct message fetches all share the ``product`` value. They aren't reported as separate mechanisms.
+
+What isn't recorded
+-------------------
+
+The following are never recorded:
+
+- **The message author**: A user never receives a delivery record for their own message.
+- **System messages and ephemeral messages**.
+- **Burn-on-read messages**.
+- **Direct and group messages**: These channels are never eligible, including when deliveries are recorded in all channels.
+- **Generic push notifications**: A push notification that doesn't include message content records nothing. When push notifications are configured to send only IDs, the delivery is recorded when the device fetches the content.
+- **Plugins reading from the database**: A plugin that reads messages directly from the database, rather than through the plugin API or a message hook, can't be observed and isn't recorded.
+
+Messages posted by bots and by outgoing webhooks are recorded like any other message.
+
+Interpret delivery records
+--------------------------
+
+Mattermost records one entry for each message delivered to each recipient, with no batching. A channel load that returns 100 messages produces 100 records, and a new message broadcast to 40 connected channel members produces 40 records.
+
+Delivery records are an append-only event stream, not a deduplicated list of who has seen a message. The same combination of user, message, and mechanism recurs, because every time a user revisits a channel the same page of messages is delivered again. Each record is a genuine delivery with its own timestamp.
+
+Deduplicate on ``actor.user_id``, ``meta.post_id``, and ``meta.mechanism`` to get one entry per recipient, message, and delivery mechanism, taking the earliest timestamp in each group as the first delivery by that mechanism. A recipient who received the same message by more than one mechanism — for example ``push`` and then ``product`` — has one entry per mechanism.
+
+To reduce that to a distinct list of the users a message reached, drop ``meta.mechanism`` from the key and deduplicate on ``actor.user_id`` and ``meta.post_id`` alone.
+
+Keep the following in mind when working with delivery records:
+
+- **Delivery isn't proof of reading**: A record means Mattermost transmitted the message content to an endpoint the recipient could read it from. It doesn't mean anyone read it. A user with email notifications configured to include message content is recorded as a delivery even if they never opened Mattermost.
+- **Records aren't guaranteed to be complete**: Audit logging is asynchronous, so records still queued in memory are lost if the server stops uncleanly. A controlled shutdown flushes the queue. This is existing audit logging behaviour that applies to all audit log levels.
+- **Permalink previews follow the previewed message**: Whether a permalink preview delivery is recorded depends on the channel of the message being previewed, not the channel of the message containing the preview. A preview of a message in a recorded channel is recorded even when the preview is rendered in a channel that isn't. Without this, a recorded message could be read by permalinking it into any other channel. Mattermost renders one level of permalink preview, so one level is recorded.
diff --git a/source/administration-guide/configure/environment-configuration-settings.rst b/source/administration-guide/configure/environment-configuration-settings.rst
@@ -3932,6 +3932,7 @@ Output audit logs to multiple targets
   - See the :doc:`Mattermost logging </administration-guide/manage/logging>` documentation for details on advanced logging configuration. These targets have been chosen as they support the vast majority of log aggregators, and other log analysis tools, without needing additional software installed.
   - Audit logs are recorded asynchronously to reduce latency to the caller.
   - Advanced audit logging supports hot-reloading of logger configuration.
+  - From Mattermost v12.0, the ``audit-delivery`` log level isn't written by the built-in audit log file target, so :ref:`post delivery audit records <administration-guide/comply/post-delivery-audit-logging:configure an audit log target>` are discarded unless you add a target here whose ``levels`` list includes ``{"id": 104, "name": "audit-delivery"}``.
 
 ----