Sublime Security Message Groups API

openapi: 3.0.1
info:
  contact:
    email: support@sublime.security
  title: Multi-Tenancy API (BETA) BinExplode Message Groups API
  version: ''
servers:
- url: '{scheme}://{server}'
  variables:
    scheme:
      default: https
      enum:
      - http
      - https
    server:
      default: platform.sublime.security
      description: Base URL of your Sublime deployment
security:
- bearerAuth: []
tags:
- name: Message Groups
paths:
  /v0/message-groups:
    get:
      description: List message groups
      operationId: listMessageGroups
      parameters:
      - description: Filters result to only message groups with the provided attachment name
        explode: true
        in: query
        name: attachment_name__is
        schema:
          description: Filters result to only message groups with the provided attachment name
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided attachment SHA256
        explode: true
        in: query
        name: attachment_sha256__is
        schema:
          description: Filters result to only message groups with the provided attachment SHA256
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided attack score verdict
        explode: true
        in: query
        name: attack_score_verdict__is
        schema:
          description: Filters result to only message groups with the provided attack score verdict
          items:
            enum:
            - unknown
            - likely_benign
            - suspicious
            - malicious
            - graymail
            - spam
            type: string
          type: array
        style: form
      - description: Filters result to only message groups that have flagged (ONLY) rules with the 'Attack surface reduction' tag
        in: query
        name: attack_surface_reduction__filter
        schema:
          description: Filters result to only message groups that have flagged (ONLY) rules with the 'Attack surface reduction' tag
          format: bool
          nullable: true
          type: string
      - description: Filters result to only message groups with the provided canonical ID
        explode: true
        in: query
        name: canonical_id__is
        schema:
          description: Filters result to only message groups with the provided canonical ID
          items:
            type: string
          type: array
        style: form
      - description: 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.
        in: query
        name: created_at__gte
        schema:
          description: 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.
          format: date-time
          nullable: true
          type: string
      - description: 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.
        in: query
        name: created_at__lt
        schema:
          description: 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.
          format: date-time
          nullable: true
          type: string
      - description: 'DEPRECATED: Use first_message_reported_at__gte'
        in: query
        name: first_message_reported_at[gte]
        schema:
          description: 'DEPRECATED: Use first_message_reported_at__gte'
          format: date-time
          nullable: true
          type: string
      - description: 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').
        in: query
        name: first_message_reported_at__gte
        schema:
          description: 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').
          format: date-time
          nullable: true
          type: string
      - description: Filters result to only message groups with at least one flagged message
        in: query
        name: flagged
        schema:
          description: Filters result to only message groups with at least one flagged message
          format: bool
          nullable: true
          type: boolean
      - description: Filters result to only message groups with the provided flagged rule ID
        explode: true
        in: query
        name: flagged_rule_id__is
        schema:
          description: Filters result to only message groups with the provided flagged rule ID
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided flagged rule severity
        explode: true
        in: query
        name: flagged_rule_severity__is
        schema:
          description: Filters result to only message groups with the provided flagged rule severity
          items:
            enum:
            - informational
            - low
            - medium
            - high
            - critical
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided historically flagged rule ID
        explode: true
        in: query
        name: historically_flagged_rule_id__is
        schema:
          description: Filters result to only message groups with the provided historically flagged rule ID
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided historically flagged rule severity
        explode: true
        in: query
        name: historically_flagged_rule_severity__is
        schema:
          description: Filters result to only message groups with the provided historically flagged rule severity
          items:
            enum:
            - informational
            - low
            - medium
            - high
            - critical
            type: string
          type: array
        style: form
      - description: 'DEPRECATED: Use created_at__gte instead'
        in: query
        name: last_message_created_at[gte]
        schema:
          description: 'DEPRECATED: Use created_at__gte instead'
          format: date-time
          nullable: true
          type: string
      - description: The maximum number of message groups to return. If the value exceeds the maximum, then the maximum value will be used.
        in: query
        name: limit
        schema:
          description: The maximum number of message groups to return. If the value exceeds the maximum, then the maximum value will be used.
          format: int32
          maximum: 500
          nullable: true
          type: integer
      - description: Filters result to only message groups with the provided mailbox email
        explode: true
        in: query
        name: mailbox_email__is
        schema:
          description: Filters result to only message groups with the provided mailbox email
          items:
            type: string
          type: array
        style: form
      - description: The (zero-based) offset of the message groups to return
        in: query
        name: offset
        schema:
          description: The (zero-based) offset of the message groups to return
          format: int32
          nullable: true
          type: integer
      - description: Filters result to only message groups with the provided recipient email
        explode: true
        in: query
        name: recipient_email__is
        schema:
          description: Filters result to only message groups with the provided recipient email
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided reporter
        explode: true
        in: query
        name: reported_as_phish_by__is
        schema:
          description: Filters result to only message groups with the provided reporter
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups which have or have not been reviewed
        in: query
        name: reviewed
        schema:
          description: Filters result to only message groups which have or have not been reviewed
          format: bool
          nullable: true
          type: boolean
      - description: Filters result to only message groups with the provided sender display name
        explode: true
        in: query
        name: sender_display_name__is
        schema:
          description: Filters result to only message groups with the provided sender display name
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided sender domain
        explode: true
        in: query
        name: sender_domain__is
        schema:
          description: Filters result to only message groups with the provided sender domain
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided sender email
        explode: true
        in: query
        name: sender_email__is
        schema:
          description: Filters result to only message groups with the provided sender email
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided spam status
        explode: true
        in: query
        name: spam__is
        schema:
          description: Filters result to only message groups with the provided spam status
          items:
            enum:
            - spam
            - not_spam
            - mixed
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with the provided subject
        explode: true
        in: query
        name: subject__is
        schema:
          description: Filters result to only message groups with the provided subject
          items:
            type: string
          type: array
        style: form
      - description: Filters result to only message groups with at least one reported message
        in: query
        name: user_reported
        schema:
          description: Filters result to only message groups with at least one reported message
          format: bool
          nullable: true
          type: boolean
      - description: Filters result to only message groups with the provided vendor
        explode: true
        in: query
        name: vendor_id__is
        schema:
          description: Filters result to only message groups with the provided vendor
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesV0ListMessageGroupsResponse'
          description: OK
      summary: List message groups
      tags:
      - Message Groups
  /v0/message-groups/dismiss:
    post:
      description: Dismiss all messages in multiple groups, including future messages.
      operationId: dismissMultipleMessageGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DismissMultipleMessageGroupsInput'
      responses:
        '200':
          description: OK
      summary: Dismiss multiple message groups
      tags:
      - Message Groups
  /v0/message-groups/hunt:
    post:
      deprecated: true
      description: 'DEPRECATED: Hunt using MQL to find message groups. Please use the POST /v0/hunt-jobs endpoint instead.'
      operationId: huntMessageGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HuntMessageGroupsInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: OK
      summary: Hunt message groups
      tags:
      - Message Groups
  /v0/message-groups/hunt/{id}:
    get:
      deprecated: true
      description: 'DEPRECATED: Retrieve the results of a completed hunt. Please use the GET /v0/hunt-jobs/:id endpoint instead.'
      operationId: getHuntResults
      parameters:
      - description: Task ID
        in: path
        name: id
        required: true
        schema:
          description: Task ID
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesGetHuntResponse'
          description: OK
      summary: Get results of a hunt
      tags:
      - Message Groups
  /v0/message-groups/move-to-graymail:
    post:
      description: Move to Graymail all messages in multiple groups, including future messages.
      operationId: graymailMultipleMessageGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraymailMultipleMessageGroupsInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Graymail multiple message groups
      tags:
      - Message Groups
  /v0/message-groups/quarantine:
    post:
      description: Quarantine all messages in multiple groups, including future messages.
      operationId: quarantineMultipleMessageGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuarantineMultipleMessageGroupsInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Quarantine multiple message groups
      tags:
      - Message Groups
  /v0/message-groups/restore:
    post:
      description: Restore all previously-trashed messages in multiple groups and turn off automatic trashing of future messages in the groups. "For an Office 365 message source, each message will be put back in the folder it was in before. For a Google Workspace message source, any applied labels (e.g. "Trash") will be removed from each message."
      operationId: restoreMultipleMessageGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreMultipleMessageGroupsInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Restore multiple message groups
      tags:
      - Message Groups
  /v0/message-groups/review:
    post:
      description: Review, classify and take actions on message groups
      operationId: reviewMessageGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReviewMessageGroupsInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlersReviewMessagesResponse'
          description: Accepted
      summary: Review message groups
      tags:
      - Message Groups
  /v0/message-groups/search:
    get:
      description: Search all message groups
      operationId: searchMessageGroups
      parameters:
      - description: Searches every field (performs a case insensitive, OR search in all fields). Not compatible with other search fields.
        in: query
        name: any
        schema:
          description: Searches every field (performs a case insensitive, OR search in all fields). Not compatible with other search fields.
          nullable: true
          type: string
      - description: Search for messages containing an attachment MD5 match
        in: query
        name: attachment_md5
        schema:
          description: Search for messages containing an attachment MD5 match
          maxLength: 32
          minLength: 32
          nullable: true
          type: string
      - description: Search for messages containing an attachment SHA1 match
        in: query
        name: attachment_sha1
        schema:
          description: Search for messages containing an attachment SHA1 match
          maxLength: 40
          minLength: 40
          nullable: true
          type: string
      - description: Search for messages containing an attachment SHA256 match
        in: query
        name: attachment_sha256
        schema:
          description: Search for messages containing an attachment SHA256 match
          maxLength: 64
          minLength: 64
          nullable: true
          type: string
      - description: 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.
        in: query
        name: created_at[gte]
        schema:
          description: 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.
          format: date-time
          nullable: true
          type: string
      - description: 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.
        in: query
        name: created_at[lt]
        schema:
          description: 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.
          format: date-time
          nullable: true
          type: string
      - description: 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.
        in: query
        name: created_at[lte]
        schema:
          description: 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.
          format: date-time
          nullable: true
          type: string
      - description: Search in attachment filenames (case insensitive wildcard match)
        in: query
        name: file_name
        schema:
          description: Search in attachment filenames (case insensitive wildcard match)
          nullable: true
          type: string
      - description: 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.
        in: query
        name: first_reported_as_phish_at[gte]
        schema:
          description: 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.
          format: date-time
          nullable: true
          type: string
      - description: 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.
        in: query
        name: first_reported_as_phish_at[lt]
        schema:
          description: 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.
          format: date-time
          nullable: true
          type: string
      - description: 'DEPRECATED: Use ''sender'' instead. Search in the From field. (case insensitive wildcard match)'
        in: query
        name: from
        schema:
          description: 'DEPRECATED: Use ''sender'' instead. Search in the From field. (case insensitive wildcard match)'
          nullable: true
          type: string
      - description: The maximum number of message groups to return. If the value exceeds the maximum, then the maximum value will be used.
        in: query
        name: limit
        schema:
          description: The maximum number of message groups to return. If the value exceeds the maximum, then the maximum value will be used.
          format: int32
          maximum: 500
          nullable: true
          type: integer
      - description: Search for a mailbox by email address (case insensitive, wildcard match)
        in: query
        name: mailbox
        schema:
          description: Search for a mailbox by email address (case insensitive, wildcard match)
          nullable: true
          type: string
      - description: Search in the Message-ID header (case insensitive wildcard match)
        in: query
        name: message_id
        schema:
          description: Search in the Message-ID header (case insensitive wildcard match)
          nullable: true
          type: string
      - description: The (zero-based) offset of the message groups to return
        in: query
        name: offset
        schema:
          description: The (zero-based) offset of the message groups to return
          format: int32
          nullable: true
          type: integer
      - description: Search in the From field (case insensitive wildcard match)
        in: query
        name: sender
        schema:
          description: Search in the From field (case insensitive wildcard match)
          nullable: true
          type: string
      - description: Search for messages in any of the given states
        explode: true
        in: query
        name: states
        schema:
          description: Search for messages in any of the given states
          items:
            type: string
          type: array
        style: form
      - description: Search in the message subject (case insensitive wildcard match)
        in: query
        name: subject
        schema:
          description: Search in the message subject (case insensitive wildcard match)
          nullable: true
          type: string
      - description: Search in the To, CC, and Bcc fields (case insensitive wildcard match). If possible, use 'mailbox' and 'type' instead for better performance
        in: query
        name: to
        schema:
          description: Search in the To, CC, and Bcc fields (case insensitive wildcard match). If possible, use 'mailbox' and 'type' instead for better performance
          nullable: true
          type: string
      - description: Search for messages by type
        in: query
        name: type
        schema:
          description: Search for messages by type
          nullable: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesV0ListMessageGroupsResponse'
          description: OK
      summary: Search message groups
      tags:
      - Message Groups
  /v0/message-groups/siem-summary:
    get:
      description: Returns a paginated, reduced-field summary of flagged message groups intended for SIEM ingestion. Array fields are bounded to keep payloads under typical SIEM batch limits.
      operationId: getMessageGroupSIEMSummary
      parameters:
      - description: Opaque pagination cursor returned in the previous response's cursor field.
        in: query
        name: cursor
        schema:
          description: Opaque pagination cursor returned in the previous response's cursor field.
          nullable: true
          type: string
      - description: The maximum number of message groups to return.
        in: query
        name: limit
        schema:
          default: 100
          description: The maximum number of message groups to return.
          format: int32
          maximum: 1000
          minimum: 1
          type: integer
      - description: Inclusive lower bound on the sort timestamp (newest_created_at for type=flagged, first_reported_as_phish_at for type=reported).
        in: query
        name: timestamp__gte
        schema:
          description: Inclusive lower bound on the sort timestamp (newest_created_at for type=flagged, first_reported_as_phish_at for type=reported).
          format: date-time
          nullable: true
          type: string
      - description: Exclusive upper bound on the sort timestamp (newest_created_at for type=flagged, first_reported_as_phish_at for type=reported).
        in: query
        name: timestamp__lt
        schema:
          description: Exclusive upper bound on the sort timestamp (newest_created_at for type=flagged, first_reported_as_phish_at for type=reported).
          format: date-time
          nullable: true
          type: string
      - description: 'Which timestamp the endpoint sorts/filters on: ''flagged'' uses newest_created_at, ''reported'' uses first_reported_as_phish_at.'
        in: query
        name: type
        schema:
          default: flagged
          description: 'Which timestamp the endpoint sorts/filters on: ''flagged'' uses newest_created_at, ''reported'' uses first_reported_as_phish_at.'
          enum:
          - flagged
          - reported
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesMessageGroupSIEMSummaryResponse'
          description: OK
      summary: Get SIEM-oriented summary of flagged message groups
      tags:
      - Message Groups
  /v0/message-groups/trash:
    post:
      description: Trash all messages in multiple groups, including future messages. For an Office 365 message source, each message will be moved to the "Recoverable Items" folder. For a Google Workspace message source, the "Trash" label will be added to each message.
      operationId: trashMultipleMessageGroups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TrashMultipleMessageGroupsInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Trash multiple message groups
      tags:
      - Message Groups
  /v0/message-groups/{id}:
    get:
      description: Retrieve the details of a single message group.
      operationId: getMessageGroup
      parameters:
      - description: Canonical ID of the message group to retrieve
        in: path
        name: id
        required: true
        schema:
          description: Canonical ID of the message group to retrieve
          type: string
      - description: Sort previews with these message IDs at the top
        explode: true
        in: query
        name: sort_previews_message_id__is
        schema:
          description: Sort previews with these message IDs at the top
          items:
            type: string
          type: array
        style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesMessageGroupV0'
          description: OK
      summary: Get a single message group
      tags:
      - Message Groups
  /v0/message-groups/{id}/dismiss:
    post:
      description: Dismiss all messages in a group, including future messages.
      operationId: dismissMessageCanonicalGroup
      parameters:
      - description: Canonical ID of the message group to dismiss
        in: path
        name: id
        required: true
        schema:
          description: Canonical ID of the message group to dismiss
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DismissMessageCanonicalGroupInput'
      responses:
        '200':
          description: OK
      summary: Dismiss message group
      tags:
      - Message Groups
  /v0/message-groups/{id}/quarantine:
    post:
      description: Quarantine all messages in a group, including future messages.
      operationId: quarantineMessageCanonicalGroup
      parameters:
      - description: Canonical ID of the message group to quarantine
        in: path
        name: id
        required: true
        schema:
          description: Canonical ID of the message group to quarantine
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuarantineMessageCanonicalGroupInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Quarantine message group
      tags:
      - Message Groups
  /v0/message-groups/{id}/restore:
    post:
      description: Restore all previously-trashed or quarantined messages in a group and turn off automatic trashing/quarantining of future messages in the group. "For an Office 365 message source, each message will be put back in the folder it was in before. For a Google Workspace message source, any applied labels (e.g. "Trash") will be removed from each message."
      operationId: restoreMessageCanonicalGroup
      parameters:
      - description: Canonical ID of the message group to restore
        in: path
        name: id
        required: true
        schema:
          description: Canonical ID of the message group to restore
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestoreMessageCanonicalGroupInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Restore message group
      tags:
      - Message Groups
  /v0/message-groups/{id}/share-with-sublime:
    post:
      description: Share a message with the Sublime team
      operationId: shareWithSublimePublic
      parameters:
      - description: Canonical ID of the message group to share
        in: path
        name: id
        required: true
        schema:
          description: Canonical ID of the message group to share
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ShareWithSublimePublicInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Share a message with Sublime
      tags:
      - Message Groups
  /v0/message-groups/{id}/trash:
    post:
      description: Trash all messages in a group, including future messages. For an Office 365 message source, each message will be moved to the "Recoverable Items" folder. For a Google Workspace message source, the "Trash" label will be added to each message.
      operationId: trashMessageCanonicalGroup
      parameters:
      - descripti

# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sublime-security/refs/heads/main/openapi/sublime-security-message-groups-api-openapi.yml