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

# Search message groups

`GET /v0/message-groups/search`

Search all message groups

## Query parameters

- `any` string, nullable — Searches every field (performs a case insensitive, OR search in all fields). Not compatible with other search fields.
- `attachment_md5` string, nullable — Search for messages containing an attachment MD5 match
- `attachment_sha1` string, nullable — Search for messages containing an attachment SHA1 match
- `attachment_sha256` string, nullable — Search for messages containing an attachment SHA256 match
- `created_at[gte]` string, date-time, nullable — Inclusive start datetime filter for search, in UTC using the ISO 8601 format (e.g., '2021-03-14T15:09:26Z'). Only message groups with a message processed at or after this time will be returned.
- `created_at[lt]` string, date-time, nullable — Exclusive end datetime filter for search, in UTC using the ISO 8601 format (e.g., '2021-05-04T15:09:26Z'). Only message groups with a message processed before this time will be returned.
- `created_at[lte]` string, date-time, nullable — Deprecated, use created_at[lt]. Exclusive end datetime filter for search, in UTC using the ISO 8601 format (e.g., '2021-05-04T15:09:26Z'). Only message groups with a message processed before this time will be returned.
- `file_name` string, nullable — Search in attachment filenames (case insensitive wildcard match)
- `first_reported_as_phish_at[gte]` string, date-time, nullable — Inclusive start datetime filter for search, in UTC using the ISO 8601 format (e.g., '2021-03-14T15:09:26Z'). Only message groups reported at or after this time will be returned.
- `first_reported_as_phish_at[lt]` string, date-time, nullable — Exclusive end datetime filter for search, in UTC using the ISO 8601 format (e.g., '2021-05-04T15:09:26Z'). Only message groups reported before this time will be returned.
- `from` string, nullable — DEPRECATED: Use 'sender' instead. Search in the From field. (case insensitive wildcard match)
- `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` string, nullable — Search for a mailbox by email address (case insensitive, wildcard match)
- `message_id` string, nullable — Search in the Message-ID header (case insensitive wildcard match)
- `offset` integer, nullable — The (zero-based) offset of the message groups to return
- `sender` string, nullable — Search in the From field (case insensitive wildcard match)
- `states` string[] — Search for messages in any of the given states
- `subject` string, nullable — Search in the message subject (case insensitive wildcard match)
- `to` string, nullable — Search in the To, CC, and Bcc fields (case insensitive wildcard match). If possible, use 'mailbox' and 'type' instead for better performance
- `type` string, nullable — Search for messages by type

## 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)