Data Spillage Handling¶

Available on Entry and Enterprise Advanced plans

Data Spillage Handling helps prevent accidental data spillage and helps system administrators respond quickly to potential leaks without disrupting collaboration. Enabling this feature empowers Mattermost users to report messages that may contain sensitive, regulated, or inappropriate information, and enables designated content reviewers to assess and take appropriate action by removing or dismissing quarantined messages.

By making every team member a first line of defense against sensitive-data exposure, Data Spillage Handling strengthens mission-critical, secure deployments and supports compliance with organizational and regulatory data-handling standards.

Before you begin¶

You must be a System Admin in Mattermost. You need to identify who will be content reviewers for quarantined messages, and you need to decide whether quarantined messages should be hidden from users in Mattermost while under review.

Enable¶

Data Spillage Handling isn’t enabled by default. To enable Data Spillage Handling:

Go to System Console > Site Configuration > Data Spillage Handling.
Set Enable Data Spillage Handling to True.

Alternatively, you can configure Data Spillage Handling via the config.json file or through environment variables.

Configure¶

Under Content Reviewers, define who should review quarantined content:
- Same reviewers for all teams: Set to True to apply one global reviewer list across all teams, or False to configure reviewers per team.
- Reviewers: Start typing to search for users to assign as content reviewers.
Important

Choose reviewers carefully. Assigning reviewer roles grants access to potentially sensitive information and may expose data from private channels.
- A global reviewer can view quarantined messages from all teams and channels, including private channels they’re not a member of.
- Team-specific reviewers can view quarantined messages from their assigned teams, including private channels within those teams they’re not members of.
- Additional reviewers: Optionally include:
  - System Administrators: System admins receive quarantined messages for all teams they are part of.
  - Team Administrators: Team admins receive quarantined messages for their respective teams.
Under Notification Settings, specify who receives updates at each stage of the quarantine workflow when content is quarantined or reviewed:
- Notify when content is quarantined: Reviewer(s), Author.
- Notify when a reviewer is assigned: Reviewer(s).
- Notify when content is removed: Reviewer(s), Author, Reporter.
- Notify on dismissal: Reviewer(s), Author, Reporter.
All notifications are sent via the Data Spillage Bot as direct messages.
Under Additional Settings, configure how the quarantine workflow behaves:
- Reasons for quarantine: Define the preset categories that appear in the quarantine dialog for users (for example: Classification mismatch, Need-to-know violation, Personally identifiable information (PII) exposure, Operational security (OPSEC) concern, Controlled Unclassified Information (CUI) violation).
- Require reporters to add comment: Set to True to require users to add a short explanation when quarantining a message.
- Require reviewers to add comment: Set to True to require reviewers to add a comment when resolving a quarantine.
- Hide message from channel while it is being reviewed: Set to True to automatically hide quarantined messages from the channel until reviews are complete. If a root post is quarantined, the entire thread is hidden.

Tip

We recommend enabling Hide message from channel while it is being reviewed and require comments from both reporters and reviewers to maintain transparency, accountability, and an auditable record of actions.

Monitor quarantined messages¶

When a user quarantines a message, the Data Spillage Bot sends a direct message to all content reviewers.

Direct messages from the Data Spillage Bot is a centralized moderation queue, where reviewers can view, assign, and act on quarantined messages without leaving Mattermost. Reviewers can use it to monitor potential data spills, coordinate response, and maintain an auditable record of review activity.

Each quarantined message appears as a card-formatted message that includes:

Quarantined by: The user who reported the message.
Status: The current state of the review. All quarantined content starts in Pending status.
Reason: The reason selected by the reporter (for example, Classification mismatch, Need-to-know violation).
Message preview: A snippet of the quarantined message, including the author, timestamp, and original channel.
Reviewer: The user currently assigned to review the message (initially Unassigned).
Channel: The name of the channel where the message was originally posted.
Team: The team context for the quarantined message.
Comment: Any reporter-provided context.
Post ID: The system identifier for the original message for auditing purposes.

Reviewers can select View details to take action as follows:

Assign a Reviewer responsible for reviewing the quarantined message.
Remove message: Permanently delete the quarantined message from its original channel for all users. The status of the quarantined message changes to Removed.
Keep message: Dismiss the quarantine and restore the message if it was hidden. The status of the quarantined message changes to Retained.
Add a comment: Record the reason for the decision when required.
Generate a report: Download a report of the quarantined message and review activity for record-keeping or incident response. See Generate a quarantined message report for details.
Download exposure report: Download a report of the users who may have been exposed to the quarantined message while it was visible in its channel. See Generate a post exposure report for details.

Once an action is taken, the Status field updates automatically. The Data Spillage Bot sends follow-up notifications to the reporter, author, and other reviewers based on how Data Spillage Handling is configured.

Generate a quarantined message report¶

Reviewers can generate a downloadable report that captures the full context of a quarantined message and the associated review activity. Reports are useful for record-keeping, incident response, and preserving evidence before a message is permanently removed.

A report can be generated from any of the following entry points:

From the quarantined message details: Select Download report from the message details panel. This option is available regardless of the quarantine’s status, including Pending, Reviewer Assigned, Removed, or Retained.
From the Remove message flow: When you select Remove message, the confirmation dialog includes a Download quarantined message report checkbox, selected by default. With the checkbox selected, Mattermost generates and downloads the report before you can permanently remove the message. This safeguard ensures the record is preserved on your device before the message contents are deleted.
From the Keep message flow: When you select Keep message, the confirmation dialog includes the same checkbox. With the checkbox selected, Mattermost generates and downloads the report in the background while the keep action completes.

If you choose to skip the report download from the Remove message or Keep message flow, Mattermost asks you to confirm that you’re proceeding without a report. The skip decision is recorded in the audit log.

If report generation fails (for example, due to a network interruption or session timeout), the dialog displays an error and offers a retry option. You can also skip the report and proceed with the action, or cancel and download the report later from the message details.

Each time a reviewer generates a quarantined message report or a post exposure report, the Data Spillage Bot notifies all content reviewers so an auditable record exists whenever a copy of the potentially spilled data is obtained.

Tip

We recommend generating a report before removing a message. Once a message is removed, its content, attachments, and edit history are permanently deleted and can’t be recovered.

Report contents and format¶

Each quarantined message report is a ZIP archive containing YAML metadata files, a CSV exposure report, and the original file attachments. YAML is used for the metadata files because it’s both human-readable and machine-parseable, which makes the report suitable for manual review and for ingestion by downstream compliance or incident-response tooling. The exposure report is CSV so that reviewers can open it directly in a spreadsheet.

The archive has the following structure:

/
├── report_metadata.yaml
├── content_review.yaml
├── exposure_report.csv
├── post/
│   ├── post.yaml
│   └── attachments/
│       └── <original attachment files>
└── edit_history/
    └── <edit_post_id>/
        ├── post.yaml
        └── attachments/
            └── <original attachment files>

report_metadata.yaml: Identifies the report itself, including the user ID and username of the reviewer who generated the report, the generation timestamp, and the report format version (used for forward compatibility if the report format changes in future releases). Report format version 1.1 added exposure_report.csv to the archive.
content_review.yaml: Captures the data spillage event, including the reporter’s user ID, username, selected reason, and comment; the report timestamp; whether the message was hidden during review; and, once the quarantine is resolved, the reviewer’s user ID, username, comment, and action timestamp. For unresolved quarantines, reviewer fields are omitted.
exposure_report.csv: Lists the users who may have been exposed to the quarantined message while it was visible in its channel. This is the same report that reviewers can download on its own, in the same format. See Exposure report contents for the columns and how to interpret them.
post/post.yaml: Describes the quarantined message, including the post ID, author ID, author name, author email, message content, channel ID, channel display name, team ID, team display name, creation and update timestamps, pinned status, root ID, post properties, post metadata, reply count (for root posts), and the ordered list of edit history post IDs.
post/attachments/: The original files attached to the quarantined message, included verbatim.
edit_history/<edit_post_id>/: One subdirectory per previous version of the message, each containing a post.yaml and an attachments/ directory in the same format as the base post directory.

To avoid duplication, attachment files are deduplicated across the entire archive by their file ID. Each unique attachment appears exactly once — under the base post if it exists in the current version of the message, or under the earliest edit-history entry that referenced it.

Generate a post exposure report¶

From Mattermost v11.11, reviewers can generate a post exposure report: a CSV file listing the users who may have been exposed to a quarantined message while it was visible in its channel. The report helps a reviewer scope the impact of a potential data spill and decide who needs follow-up.

Important

A post exposure report identifies who may have been exposed to a quarantined message. It isn’t evidence that anyone read the message.

The report is derived from channel membership history and from channel read timestamps. Neither records whether a message was ever displayed on screen.
A Last viewed channel at timestamp after the message was posted means the user opened the channel while the message was visible. It doesn’t mean the message was displayed to them, or that they read it.
The report doesn’t cover every path by which a message can reach someone. Push and email notifications can deliver message content to a user who never opens the channel, and content in a public channel can be reached without joining it.
Treat the report as a starting point for investigation, not as the sole basis for a compliance or disciplinary finding.

See Exposure report limitations for what the report can and can’t establish.

A post exposure report can be obtained from either of the following entry points:

From the quarantined message details: Select View details, then select Download exposure report in the Exposure report row. The file downloads as post-exposure-<post_id>-<timestamp>.csv.
From the quarantined message report: The ZIP archive produced by Download report includes the same data as exposure_report.csv.

Only content reviewers can generate a post exposure report.

Exposure report contents¶

Every row in the report is one user who was a member of the channel at some point between the message being posted and the message being quarantined, taken from channel membership history. That row set is the complete population of users who could have been exposed through channel membership. It isn’t the complete population of users who could have been exposed by any means.

The report doesn’t produce a separate list of users who probably saw the message. Instead, every row carries the channel read state and account activity timestamps needed to judge likelihood, so reviewers triage a single table by sorting and filtering rather than reconciling two overlapping lists.

Report metadata is written as #-prefixed comment lines above the header row, so the file describes itself without a separate metadata file. Most tools can skip these lines — for example, Go’s csv.Reader with Comment: '#', or pandas with comment='#'.

# Report version: 1.0
# Post ID: 8xk3mq7pzjfytr4wn6hb2dcvse
# Channel: Engineering (jr9v2thq5xkfcm8bwd63pnysa4)
# Post created at: 2026-07-14T09:12:03Z
# Flagged at: 2026-07-14T11:48:37Z
# Generated at: 2026-07-14T12:05:19Z
# Total users: 3
User ID,Username,Email,Guest,Remote user,Deactivated,Was channel member,Last viewed channel at (YYYY-MM-DDTHH:MM:SSZ),User last activity time (YYYY-MM-DDTHH:MM:SSZ)
4tqzn8mhs2xdwc7bkgv6yrfpj3,alice.chen,alice.chen@example.com,No,No,No,Yes,2026-07-14T10:31:52Z,2026-07-14T11:59:08Z
mw6cbyx9rntk3f7zqhdps2gjv5,bhavna.rao,bhavna.rao@example.com,No,No,No,Yes,2026-07-02T16:20:44Z,2026-07-14T12:01:44Z
zd7pfk2vqn6ymxb3wcjs9htgr8,carlos.mendes,carlos.mendes@example.com,No,No,Yes,Yes,Unknown,No sessions found

Post created at and Flagged at bound the reporting window that membership is resolved against. Total users is the number of rows in the file, counted after any users whose account records no longer exist are skipped.

The report includes the following columns:

User ID: The system identifier for the user.
Username: The user’s Mattermost username.
Email: The user’s email address.
Guest: Yes if the user is a guest account.
Remote user: Yes if the user belongs to a remote server through a shared channel. Content on a remote server is beyond the reach of hiding or removing the message locally.
Deactivated: Yes if the user’s account is deactivated. Deactivating a user doesn’t undo their exposure, so deactivated accounts are still reported.
Was channel member: Always Yes in report version 1.0. Every row is a channel member by definition, and the column is reserved for future report versions that may add other exposure paths.
Last viewed channel at (YYYY-MM-DDTHH:MM:SSZ): The user’s current last-viewed timestamp for the channel, not a snapshot taken when the message was quarantined. Unknown means no read state exists because the user is no longer a channel member. N/A means the user is a member who has never opened the channel.
User last activity time (YYYY-MM-DDTHH:MM:SSZ): The user’s most recent session activity anywhere in Mattermost, not in this channel. No sessions found means no session records exist for the user, which is always the case for deactivated accounts.

To scope who needs follow-up, compare each row’s Last viewed channel at value against the Post created at value in the report metadata:

At or after Post created at: The user opened the channel while the message was visible. This is a possible exposure, and should be prioritized for follow-up.
Before Post created at: The user was a channel member, but hadn’t opened the channel since before the message was posted. Exposure in the channel is less probable, but not ruled out — the message content may still have reached the user through a push or email notification.
Unknown or N/A: No channel read state exists for the user. Exposure is undetermined. Don’t read these values as confirmation that the user didn’t see the message.

Tip

Generate the exposure report early in the review. Last viewed channel at reflects live channel read state, so it moves whenever a user opens the channel again, including after the quarantine is resolved.

Rows are sorted by username, then by user ID, so row order is the same every time the report is generated. The cell values aren’t: Last viewed channel at and User last activity time both reflect live state, so two reports generated at different times can differ. Column headings and values, including Yes, No, Unknown, N/A, and No sessions found, are localized to the language of the reviewer who generated the report. Downstream tooling shouldn’t match on the English strings.

Exposure report limitations¶

The report is derived from channel membership history and channel read state, which constrains what it can establish:

Notification delivery isn’t covered: A user can be exposed to message content without ever opening the channel. Push and email notifications can include the message text, depending on your push notification contents and email notification contents settings. Notifications aren’t reflected in the report, so an early Last viewed channel at value doesn’t rule out exposure.
Access to public channels without membership isn’t covered: The report lists channel members only. In a public channel, a message can also reach users who never joined the channel — through a post permalink preview rendered when a link to the message is shared in another channel, or through search when searching public channels without membership is enabled. None of these users appear in the report.
Bots are excluded: Bot accounts are omitted from the report.
Users who joined after the message was quarantined are excluded: Membership is resolved against the reporting window only.
Users who left and rejoined appear once: The report is a list of users, so multiple membership periods are collapsed into a single row. Individual join and leave times aren’t reported.
Users who left and didn’t rejoin are included: They’re reported with Last viewed channel at set to Unknown, because no channel read state survives for a former member.
Guests and remote users are included: Both are identified in their own columns.
Archived channels are supported: Members of an archived channel are reported as usual.
Deleted accounts are omitted: If a user’s account record no longer exists, that user is skipped, and Total users reflects the count after the skip.

Generating an exposure report queries session activity for each user in the report individually, and the whole report is assembled in memory before the download starts. On channels with several thousand members, expect generation to take proportionally longer.

Deleted messages¶

When a reviewer permanently removes a quarantined message, the message and all associated data are deleted from the database and file system and can’t be recovered. The deletion covers:

Post record: The text of the message and any associated post properties. The content is scrubbed before the post is deleted.
File attachments: The files stored in Mattermost’s file storage (local, S3, etc.).
File attachment records: The file info database rows for the message, including file names, IDs, and links to storage.
Edit history: Every prior revision of the message, along with file metadata from each revision.
Priority metadata: Any message priority or importance settings.
Persistent notifications: Any recurring notifications attached to the message.
Acknowledgements: Records of users who acknowledged the message.
Reminders: Any reminders created for the message.
Thread, replies, and reactions: The thread record, replies, and reaction data, if any, associated with the message.

Post deletion report¶

When a reviewer selects Remove message, the Data Spillage Bot posts a Post Deletion Report into the reviewer’s content review thread for that quarantined message. The report is delivered to every reviewer who received the original quarantine notification, and is localized to each reviewer’s language. Each post includes a short summary rendered inline, and a full report attached as a Markdown file named deletion_report_<post_id>.md.

The report records every cleanup step performed against the message and its associated data. The steps map directly to the data scope listed in Deleted messages:

File attachments: Files removed from file storage.
File attachment records: File info database rows for the message.
Edit history: Every prior revision of the message. Each revision is reported as its own sub-step so that reviewers can see exactly which revisions were cleared.
Priority metadata: Message priority and importance settings.
Persistent notifications: Recurring notifications attached to the message.
Acknowledgements: Records of users who acknowledged the message.
Reminders: Reminders set on the message.
Thread, replies, and reactions: The thread record, replies, and reaction data associated with the message.
Post record: The post itself. The content is scrubbed before the post is deleted.

Each step is assigned one of the following statuses:

Removed ✅: The data was successfully deleted.
Not applicable ➖: There was no data of this type to delete.
Partial ⚠️: Some items of this type were deleted, but at least one failed. This status most often appears under Edit history when one revision can’t be deleted.
Failed ❌: The step didn’t complete. The report includes an error log so reviewers and System Administrators can inspect what went wrong.

When every step is Removed or Not applicable, no further action is required. The report serves as the auditable record of the deletion.

When any step reports Partial or Failed, the report displays an incomplete warning. Reviewers should escalate to a System Administrator, who can use the attached deletion_report_<postId>.md file - including the full per-step error log - to perform manual remediation and confirm that the data is fully removed.

Note

The post deletion report is the single source of truth for post-removal auditing. It isn’t stored elsewhere in the System Console, so the reviewer thread containing the report should be retained in line with your organization’s audit retention policy.

Best practice recommendations¶

Before rolling out Data Spillage Handling organization-wide, we recommend communicating that the feature protects both users and the organization from accidental data spillage. Start with a pilot team to validate reviewer notifications and workflows, integrate the process with existing data-handling or incident-response playbooks, and require reporter and reviewer comments to ensure every decision is transparent and auditable.