---
title: "List message groups"
method: GET
path: "/v0/message-groups"
tags: ["Message Groups"]
---

# List message groups

`GET /v0/message-groups`

List message groups

## Query parameters

- `attachment_name__is` string[] — Filters result to only message groups with the provided attachment name
- `attachment_sha256__is` string[] — Filters result to only message groups with the provided attachment SHA256
- `attack_score_verdict__is` string[] — Filters result to only message groups with the provided attack score verdict
- `attack_surface_reduction__filter` string, bool, nullable — Filters result to only message groups that have flagged (ONLY) rules with the 'Attack surface reduction' tag
- `canonical_id__is` string[] — Filters result to only message groups with the provided canonical ID
- `created_at__gte` string, date-time, nullable — Inclusive start datetime filter, in UTC using the ISO 8601 format (e.g., '2021-03-14T15:09:26Z'). Only message groups that contain a message processed at or after this time will be returned.
- `created_at__lt` string, date-time, nullable — Exclusive end datetime filter, in UTC using the ISO 8601 format (e.g., '2021-05-04T15:09:26Z'). Only message groups that contain a message processed before this time will be returned.
- `first_message_reported_at[gte]` string, date-time, nullable — DEPRECATED: Use first_message_reported_at__gte
- `first_message_reported_at__gte` string, date-time, nullable — Filters result to only message groups with a message first reported at or after the provided time. Datetime must be in UTC using the ISO 8601 format (e.g., '2021-03-14T15:09:26Z').
- `flagged` boolean, nullable — Filters result to only message groups with at least one flagged message
- `flagged_rule_id__is` string[] — Filters result to only message groups with the provided flagged rule ID
- `flagged_rule_severity__is` string[] — Filters result to only message groups with the provided flagged rule severity
- `historically_flagged_rule_id__is` string[] — Filters result to only message groups with the provided historically flagged rule ID
- `historically_flagged_rule_severity__is` string[] — Filters result to only message groups with the provided historically flagged rule severity
- `last_message_created_at[gte]` string, date-time, nullable — DEPRECATED: Use created_at__gte instead
- `limit` integer, nullable — The maximum number of message groups to return. If the value exceeds the maximum, then the maximum value will be used.
- `mailbox_email__is` string[] — Filters result to only message groups with the provided mailbox email
- `offset` integer, nullable — The (zero-based) offset of the message groups to return
- `recipient_email__is` string[] — Filters result to only message groups with the provided recipient email
- `reported_as_phish_by__is` string[] — Filters result to only message groups with the provided reporter
- `reviewed` boolean, nullable — Filters result to only message groups which have or have not been reviewed
- `sender_display_name__is` string[] — Filters result to only message groups with the provided sender display name
- `sender_domain__is` string[] — Filters result to only message groups with the provided sender domain
- `sender_email__is` string[] — Filters result to only message groups with the provided sender email
- `spam__is` string[] — Filters result to only message groups with the provided spam status
- `subject__is` string[] — Filters result to only message groups with the provided subject
- `user_reported` boolean, nullable — Filters result to only message groups with at least one reported message
- `vendor_id__is` string[] — Filters result to only message groups with the provided vendor

## Response `200`

OK

- HandlerTypesV0ListMessageGroupsResponse
  - `count` integer, required — Count of messages groups for this page
  - `message_groups` HandlerTypesMessageGroupV0[] — Array of messages groups matching the search
    - `classification` string, nullable — Classification of the message group
    - `flagged_rules` HandlerTypesFlaggedRuleV0[] — Flagged rules from the message
      - `id` string — ID of the flagged rule
      - `name` string — Name of the flagged rule
      - `tags` string[] — List of tags for the flagged rule
    - `id` string, required — Canonical ID of the group
    - `message_links_clicked` HandlerTypesMessageGroupEventLinksClickedV0[] — Message link clicked events
      - `clicks` HandlerTypesMessageGroupEventLinkClick[] — Click events for the URL
        - `clicked_at` string, date-time — The time that the link was clicked
        - `client_ip` string — The originating client IP for the click
        - `mailbox_display_name` string, nullable — Display name of mailbox that performed the action
        - `mailbox_email_address` string, nullable — Mailbox email address that performed the action
        - `mailbox_external_id` string, nullable — External ID of the mailbox that performed the action
        - `message_id` string — ID of the Sublime message for which the action occurred
        - `user_agent` string — The originating user-agent for the click
      - `url` string — URL that was clicked
    - `messages` HandlerTypesMessagePreviewV0[] — Message previews
      - `created_at` string, date-time — Time this message was added to Sublime
      - `delivered` boolean — Whether or not the message has been delivered
      - `forward_recipients` string[] — Email addresses this message was forwarded to by the recipient mailbox
      - `forwarded_at` string, date-time, nullable — Time this message was forwarded by the recipient mailbox. A null value indicates that it has not yet been forwarded
      - `id` string, required — Sublime message ID
      - `mailbox` HandlerTypesMailbox, required — Mailbox that the email bomb was found in
        - `email` string, required — Mailbox email address
        - `external_id` string, nullable — ID of the mailbox in the source system (e.g., Office 365 or Google Workspace)
        - `id` string, uuid, required — Mailbox ID
      - `read_at` string, date-time, nullable — Time this message was read in the user's mailbox. A null value indicates that it has not yet been marked read
      - `recipients` HandlerTypesRecipient[], required — Details of the message recipients
        - `email` string, required — Email address
      - `replied_at` string, date-time, nullable — Time that this message was replied to by the recipient mailbox. A null value indicates that it has not yet been replied to by the recipient
      - `sender` HandlerTypesSender, required — Details of the message sender
        - `display_name` string — Display name
        - `email` string, required — Email address
      - `subject` string, required — Subject of the message
    - `organization_id` string — ID of the group's organization
    - `review_comment` string, nullable — Comment describing reason for action
    - `review_label` string, nullable — Message group label
    - `review_status` string, nullable — Message group status
    - `state` string, nullable — Message group state
    - `user_reports` HandlerTypesMessageReportV0[] — User reports of the message
      - `channel` string — Channel used to report the group
      - `reported_at` string, date-time — Time the group was reported
      - `reported_by_message_id` string, nullable — ID of the reporting message (the user forward)
      - `reporter` string — Email address of the user who reported the group
  - `stats_limit_exceeded` boolean — Indicates if 'total' is a lower bound
  - `total` integer, required — Total number of messages groups matching the search

---

[API](https://skmtc.net/sublime/apis/sublime-platform-api.md) · [All operations](https://skmtc.net/sublime/apis/sublime-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sublime/sublime-platform-api/revisions/d5df82850357/schema)