Message Groups & Cases¶
Private beta
Email Security is in private beta. It is not generally available, and
access is enabled per organization — if the ext-email-security extension
is not in your catalog, this product is not turned on for you yet.
While it is in beta, expect the surface described here to move: commands, fields and event shapes may change between releases, and they may change in ways that are not backwards compatible. Install or upgrade the CLI before running the examples:
Credential-file examples also require jq. Re-read these pages after upgrading.
Talk to us before relying on it in production.
A message group represents one email delivered to several recipients. Open Email Security → Groups, or choose Group by message from Messages, to triage the copies together. A campaign relates similar messages and may contain several groups. Group membership is stricter than campaign similarity.
Identity and the queue¶
The organization-scoped group_id combines the normalized Message-ID with the
sender, Reply-To, subject and message content. Reusing a legitimate Message-ID
with different content does not put the forged email into the legitimate group.
Recipient-specific delivery headers and supported Safe Links wrapping do not
create separate identities. Missing or truncated identity uses an individual
message identity. Other content changes, including personalized links, can split
copies into separate groups; inspect instances before applying remediation.
The default queue shows groups needing triage: malicious or suspicious copies, medium-or-higher rule severity, or user-reported mail. An analyst benign revision removes that copy's severity-only triage contribution while preserving its historical severity. Dispositions benign, graymail and simulation dismiss that copy's triage contribution; malicious and spam flag it. The historical user-report indicator stays visible. Other undismissed copies keep the group in the queue. Show all groups includes the remaining groups.
Filter by verdict, severity, disposition, user-reported state and time. Omitted user-reported state leaves that dimension unrestricted. Filters combine across dimensions and allow alternatives within one dimension. Message-specific filters such as mailbox and free text are not carried into the Groups view.
The drawer shows first and last seen, message and recipient counts, maximum
verdict and severity, placement and disposition counts, a representative message
and campaign association when unambiguous. Queue summaries show their as_of
time; the drawer reads a consistent current snapshot. A missing severity remains
unknown. Instances are paged: continue until there is no next cursor rather than
assuming the first page contains every recipient.
Preview, confirm and track¶
Group remediation prepares a durable snapshot of every member, including all-hands messages with more than 20,000 recipients. Preparation may need several passes. The preview shows its snapshot time, selected count, action and frozen parameters. No confirmation is available until preparation finishes. Newly arriving copies after the snapshot require a separate preview.
Confirm the complete preview to start execution. Confirmation is bound to the organization, authenticated actor, group, action, parameters and manifest. A ready preview expires 45 minutes after its snapshot; prepare a new preview rather than confirming stale information. Confirming again after execution starts resumes the same job and does not create another intent.
Execution processes bounded chunks and survives worker restarts. Track the job until it reaches a terminal phase, and inspect succeeded, skipped, withheld and failed counts. Withheld is not successful remediation. The normal enforcement, exclusion and mailbox protection rules still apply; an explicit force request requires the same deliberate consent as individual remediation. Retention can remove a selected copy before execution, and provider failures can leave a partial outcome. Review those outcomes before retrying.
Microsoft may accept quarantine or restore before completing it. The group job stays running while that provider result is pending; acceptance does not increase its succeeded or failed counts. Continue polling the same job instead of creating another intent. Each recipient has up to 90 minutes from its first recorded pending result to reach a terminal provider outcome. An unconfirmed result after that window counts as failed, even if Microsoft later completes the action. Inspect the provider state before retrying such a member.
The console can resume a job from its URL. Paused browser polling does not cancel the durable server job; refresh its status. See Bulk Remediation for individual and campaign scopes.
Group disposition uses the same preview and confirmation flow, requiring both
mailsec.act and mailsec.set. Choose malicious, spam, graymail, benign or
simulation, or clear the existing disposition, with an optional note of at most
1,024 characters. Confirmation uses the frozen value and note and checks current
permission. It records the decision through the ordinary disposition path,
including history and disposition events, without changing engine verdicts or
running remediation automations. Newly delivered copies keep their own disposition.
From the command line¶
limacharlie mailsec group list --severity high --severity critical --disposition none
limacharlie mailsec group list --all --since 2026-09-01T00:00:00Z
limacharlie mailsec group get <GROUP_ID>
limacharlie mailsec message list --group-id <GROUP_ID>
limacharlie mailsec group preview <GROUP_ID> --action quarantine_message --reason "Incident review"
limacharlie mailsec group preview <GROUP_ID> --action set_disposition --disposition benign --note "Reviewed"
limacharlie mailsec group status <JOB_ID>
limacharlie mailsec group confirm <JOB_ID> --confirmation <TOKEN>
Preview and confirm wait for the job by default; --no-wait returns it at once.
Reuse the printed --preview-id when retrying the same preview. A failed or
withheld recipient outcome exits non-zero. See Command Line Interface.
Routes¶
All routes are under /v1/mailsec/{oid}. See API Reference
for the shared conventions.
| Route | Does |
|---|---|
GET /groups |
The flagged triage queue, newest last-seen first. Filters: verdict, severity, disposition (or none) repeatable, user_reported, since/until (last-seen time, RFC 3339 or Unix seconds), all=true for every group, cursor, limit. Values OR within a filter and AND across filters; the cursor is bound to the filter set. Requires mailsec.get |
GET /groups/{group_id} |
One consistent aggregate of every indexed copy: first/last seen, counts, maximum verdict and severity, placement and disposition summaries, representative message and campaign. Requires mailsec.get |
GET /messages?group_id={group_id} |
The group's recipient copies, paged like any message list |
POST /groups/{group_id}/actions/preview |
Prepare a durable snapshot of every copy. Body: preview_id (caller UUID, reused on retry), action (a remediation action or set_disposition), optional reason, text, force; for set_disposition, disposition or clear: true, and optional note. Requires mailsec.act, plus mailsec.set for set_disposition |
GET /group-actions/{job_id} |
Preparation or execution progress: phase, snapshot time, counts of succeeded, skipped, withheld and failed. The confirmation token appears only once the manifest is complete. Requires mailsec.get |
POST /group-actions/{job_id}/confirm |
Execute the complete preview with {"confirmation": ...}, from the same authenticated actor that prepared it. Repeating it resumes the same job. Requires mailsec.act |
Opt-in Cases detection pack¶
In Email Security → Protection setup, install the Cases pack after enabling
Cases. The pack creates ordinary dr-general rules with your credentials. It
only reports detections; it does not change verdicts, dispositions or placement.
Installation needs permission to call the extension and read/write detection
rules. Removal also needs detection-rule delete permission.
The pack reports:
EMAIL_ANALYSIS_COMPLETEwhen the final verdict is malicious or suspicious, severity is at least medium, or the message was user-reported.EMAIL_USER_REPORTfrom a human reporter. Automated senders are excluded.
Copies classified benign, graymail or simulation are excluded from both triggers. Closing a Case alone does not dismiss its messages. Set the group disposition when dismissing a retained Case; future unclassified copies can still report and reopen it.
| Severity | Detection priority |
|---|---|
| informational | 1 |
| low | 1 |
| medium | 3 |
| high | 6 |
| critical | 9 |
| unknown or missing | 1, with unknown severity retained |
Global suppression limits duplicates for the same group and severity across mailbox sensors and both triggers for 30 days. A higher severity can report again and raise the priority of the same retained case. Explicit case identity keeps late detections together independently of ordinary time-based grouping and reopens a closed case when necessary. A manually merged case follows its retained merge target.
Deduplication lasts while that identity's case remains retained. Deliberate case deletion, retention expiry, or a missing, cyclic or excessively long merge mapping allows a fresh case; retired mappings carry an audit reason. A missing group uses the immutable message identity rather than an empty organization-wide key.
Installation and repair show an outcome for each record. Repair adds missing records without overwriting existing rules. Updates preserve disabled state, customer tags and comments, and use conditional writes. A customer-owned record at a reserved pack key is refused. Unavailable metadata stays unknown instead of being treated as an absent rule. Removal targets only pack-owned records in the pack's namespace.