Sublime Security Messages API

openapi: 3.2.0
info:
  contact:
    email: support@sublime.security
  title: Multi-Tenancy API (BETA) BinExplode Messages API
  version: '1.0'
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: Messages
paths:
  /v0/messages/analyze:
    post:
      description: 'Analyze a raw message with provided rules and/or active rules in your Sublime organization. Note: All messages will be treated as inbound.'
      operationId: analyzeMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeMessageInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesAnalyzeRawMessageResponse'
          description: OK
      summary: Analyze a raw message
      tags:
      - Messages
  /v0/messages/attachment/image:
    post:
      description: Render image for attachment from the raw base64 encoded bytes
      operationId: getMessageAttachmentImageRaw
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMessageAttachmentImageRawInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesAttachmentImageContent'
          description: OK
      summary: Render image for attachment from the raw base64 encoded bytes
      tags:
      - Messages
  /v0/messages/attack_score:
    post:
      description: Evaluate attack score for a raw message
      operationId: attackScoreForRawMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttackScoreForRawMessageInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlersAttackScoreResponse'
          description: OK
      summary: Evaluate attack score for a raw message
      tags:
      - Messages
  /v0/messages/create:
    post:
      description: Create a new message data model from a raw message
      operationId: createMessage
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMessageInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlersMessage'
          description: OK
      summary: Create message
      tags:
      - Messages
  /v0/messages/groups/{id}/action-state:
    get:
      description: Retrieve details about the state of manual actions for a canonical group
      operationId: getMessageCanonicalGroupActionState
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: Only return action states created after this time
        in: query
        name: created_at__gte
        schema:
          description: Only return action states created after this time
          format: date-time
          type:
          - string
          - 'null'
      - description: The maximum number of action states to return. If the value exceeds the maximum, then the maximum value will be used.
        in: query
        name: limit
        schema:
          default: 10
          description: The maximum number of action states to return. If the value exceeds the maximum, then the maximum value will be used.
          format: int32
          maximum: 50
          type: integer
      - description: The (zero-based) offset of the action states to return
        in: query
        name: offset
        schema:
          default: 0
          description: The (zero-based) offset of the action states to return
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlersGetMessageCanonicalGroupTasksResponse'
          description: OK
      summary: Retrieve details about the state of manual actions for a canonical group
      tags:
      - Messages
  /v0/messages/{id}:
    get:
      description: Retrieve a message
      operationId: getMessage
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: When true, recompute the MDM from the raw EML. For internal use only!
        in: query
        name: recompute_mdm_from_raw
        schema:
          description: When true, recompute the MDM from the raw EML. For internal use only!
          type:
          - boolean
          - 'null'
      - description: When true, any text field over 1MB will be cleared before returning
        in: query
        name: remove_large_text_fields
        schema:
          description: When true, any text field over 1MB will be cleared before returning
          type:
          - boolean
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesMessage'
          description: OK
      summary: Retrieve message
      tags:
      - Messages
  /v0/messages/{id}/actions:
    post:
      description: Perform actions (trash, restore, quarantine, warning banner, move to spam) on an individual message
      operationId: actionMessage
      parameters:
      - description: ID of the message to act on
        in: path
        name: id
        required: true
        schema:
          description: ID of the message to act on
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActionMessageInput'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Perform actions on an individual message
      tags:
      - Messages
  /v0/messages/{id}/analyze:
    post:
      description: Analyze a message by ID with provided rules and/or active rules in your Sublime organization
      operationId: analyzeMessageByID
      parameters:
      - description: The ID of the message
        in: path
        name: id
        required: true
        schema:
          description: The ID of the message
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AnalyzeMessageByIDInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesAnalyzeRawMessageResponse'
          description: OK
      summary: Analyze a message by ID
      tags:
      - Messages
  /v0/messages/{id}/asa_report:
    get:
      description: Retrieve ASA report for a message
      operationId: retrieveASAReport
      parameters:
      - description: Message ID
        in: path
        name: id
        required: true
        schema:
          description: Message ID
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlersAsaReportResponseV0'
          description: OK
      summary: Retrieve ASA report for a message
      tags:
      - Messages
  /v0/messages/{id}/asa_verdict:
    get:
      description: Retrieve ASA verdict for a message
      operationId: retrieveASAVerdict
      parameters:
      - description: Message ID
        in: path
        name: id
        required: true
        schema:
          description: Message ID
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlersAsaVerdictResponseV0'
          description: OK
      summary: Retrieve ASA verdict for a message
      tags:
      - Messages
  /v0/messages/{id}/attachment/{hash}/image:
    get:
      description: Retrieve image of PDF attachment by md5 hash
      operationId: getMessageAttachmentImage
      parameters:
      - description: MD5 hash of the attachment to retrieve
        in: path
        name: hash
        required: true
        schema:
          description: MD5 hash of the attachment to retrieve
          type: string
      - description: Sublime Message ID
        in: path
        name: id
        required: true
        schema:
          description: Sublime Message ID
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesAttachmentImageContent'
          description: OK
      summary: Retrieve image of PDF attachment by md5 hash
      tags:
      - Messages
  /v0/messages/{id}/attack_score:
    get:
      description: Evaluate attack score against an existing message
      operationId: attackScoreForMessage
      parameters:
      - description: Message ID
        in: path
        name: id
        required: true
        schema:
          description: Message ID
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HandlersAttackScoreResponse'
          description: OK
      summary: Evaluate attack score against an existing message
      tags:
      - Messages
  /v0/messages/{id}/eml:
    get:
      description: Retrieve the raw EML for the message
      operationId: getMessageEML
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
      summary: Retrieve raw EML
      tags:
      - Messages
  /v0/messages/{id}/image:
    get:
      description: Retrieve an image of the message
      operationId: getMessageImage
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: When true, recompute the MDM from the raw EML. For internal use only!
        in: query
        name: recompute_mdm_from_raw
        schema:
          description: When true, recompute the MDM from the raw EML. For internal use only!
          type:
          - boolean
          - 'null'
      - description: When true, any text field over 1MB will be cleared before returning
        in: query
        name: remove_large_text_fields
        schema:
          description: When true, any text field over 1MB will be cleared before returning
          type:
          - boolean
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesMessageImage'
          description: OK
      summary: Retrieve image of message
      tags:
      - Messages
  /v0/messages/{id}/image_link:
    get:
      description: Retrieve a temporary link to the image of the message
      operationId: getMessageImageLink
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: Period link should be valid for. Default is 15 minutes, max 7 days.
        in: query
        name: link_duration_seconds
        schema:
          description: Period link should be valid for. Default is 15 minutes, max 7 days.
          format: int32
          maximum: 604800
          type:
          - integer
          - 'null'
      - allowEmptyValue: true
        description: When true, link will always be presigned against Sublime. When false, the link may be to S3 directly.
        in: query
        name: platform_link
        schema:
          description: When true, link will always be presigned against Sublime. When false, the link may be to S3 directly.
          type: boolean
      - description: When true, recompute the MDM from the raw EML. For internal use only!
        in: query
        name: recompute_mdm_from_raw
        schema:
          description: When true, recompute the MDM from the raw EML. For internal use only!
          type:
          - boolean
          - 'null'
      - description: When true, any text field over 1MB will be cleared before returning
        in: query
        name: remove_large_text_fields
        schema:
          description: When true, any text field over 1MB will be cleared before returning
          type:
          - boolean
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesMessageImageLink'
          description: OK
      summary: Retrieve a temporary link to the image of message
      tags:
      - Messages
  /v0/messages/{id}/justification:
    post:
      description: Set message contents access justification for a message for the user associated with the API key being used
      operationId: SetMessageAccessJustification
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetMessageAccessJustificationInput'
      responses:
        '200':
          description: OK
      summary: Set access justification
      tags:
      - Messages
  /v0/messages/{id}/message_data_model:
    get:
      description: Retrieve the message's Message Data Model. If there is no justification, it will be redacted.
      operationId: getMessageDataModel
      parameters:
      - in: path
        name: id
        required: true
        schema:
          format: uuid
          type: string
      - description: When true, recompute the MDM from the raw EML. For internal use only!
        in: query
        name: recompute_mdm_from_raw
        schema:
          description: When true, recompute the MDM from the raw EML. For internal use only!
          type:
          - boolean
          - 'null'
      - description: When true, any text field over 1MB will be cleared before returning
        in: query
        name: remove_large_text_fields
        schema:
          description: When true, any text field over 1MB will be cleared before returning
          type:
          - boolean
          - 'null'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mdm_serviceMessageDataModel'
          description: OK
      summary: Retrieve the message's Message Data Model
      tags:
      - Messages
  /v0/messages/{id}/restore:
    post:
      description: Restore a previously-trashed message. "For an Office 365 message source, the 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 the message."
      operationId: restoreMessage
      parameters:
      - description: ID of the message to restore
        in: path
        name: id
        required: true
        schema:
          description: ID of the message to restore
          format: uuid
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Restore a previously-trashed message
      tags:
      - Messages
  /v0/messages/{id}/trash:
    post:
      description: Trash a message. For an Office 365 message source, the message will be moved to the "Recoverable Items" folder. For a Google Workspace message source, the "Trash" label will be added to the message.
      operationId: trashMessage
      parameters:
      - description: ID of the message to trash
        in: path
        name: id
        required: true
        schema:
          description: ID of the message to trash
          format: uuid
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Handler_typesTaskAccepted'
          description: Accepted
      summary: Trash message
      tags:
      - Messages
components:
  schemas:
    CreateMessageInput:
      properties:
        canonical_id:
          description: The canonical ID of the message, if known
          type:
          - string
          - 'null'
        external_created_at:
          description: Timestamp the message created at according to the external source
          type:
          - string
          - 'null'
        external_message_id:
          description: ID of the message according to the external source
          type:
          - string
          - 'null'
        external_thread_id:
          description: ID of the thread the message belongs to according to the external source
          type:
          - string
          - 'null'
        folder:
          description: The mailbox folder the message is in
          type:
          - string
          - 'null'
        labels:
          description: Labels applied to the message by the mailbox
          items:
            type: string
          type: array
        mailbox_email_address:
          description: The email address of the mailbox containing this message
          format: email
          type:
          - string
          - 'null'
        message_type:
          $ref: '#/components/schemas/Mdm_serviceMessageType'
        raw_message:
          description: The full base64 encoded raw eml message
          format: byte
          type: string
        route_type:
          description: The directional route type of the message
          type:
          - string
          - 'null'
      required:
      - raw_message
      type: object
    Mdm_serviceSPFSummary:
      description: Summary of the SPF check
      properties:
        details:
          $ref: '#/components/schemas/Mdm_serviceSPF'
        error:
          description: Whether the SPF check errored
          type:
          - boolean
          - 'null'
        pass:
          description: Whether the SPF check passed
          type:
          - boolean
          - 'null'
        received_hop:
          description: The lowest hop at which the SPF check was made
          format: int32
          type: integer
      type: object
    Mdm_serviceThread:
      description: The current text thread of the message
      properties:
        banners:
          description: All warning banners found in the body of the message.
          items:
            $ref: '#/components/schemas/Mdm_serviceBanner'
          type: array
        links:
          description: All links found in the given thread, unique by the target and display text/url.
          items:
            $ref: '#/components/schemas/Mdm_serviceLink'
          type: array
        preamble:
          description: The preamble text from the thread, typically the headers of a reply or forward. Things like From, Sent, Subject, saved as one big multiline string. This doesn't include banners.
          type: string
        text:
          description: The text content from the latest reply/forward in a message thread. This typically excludes content from forwarded messages and warning banners.
          type: string
      type: object
    Mdm_serviceLink:
      properties:
        display_text:
          description: The text of a hyperlink, if it's not a URL
          type: string
        display_url:
          $ref: '#/components/schemas/Mdm_serviceURL'
        href_url:
          $ref: '#/components/schemas/Mdm_serviceURL'
        mismatched:
          description: Whether the display URL and href URL root domains are mismatched (i.e. .href_url.domain.root_domain != .display_url.domain.root_domain, where both are not null and valid domains)
          type:
          - boolean
          - 'null'
        parser:
          description: The parser that was used to derived the link
          enum:
          - plain
          - hyperlink
          type: string
        visible:
          description: Whether the link is visible to a human when previewing an email or page
          type:
          - boolean
          - 'null'
      type: object
    Mdm_serviceReceivedFrom:
      description: The 'from' section of the Received header, relating to a server in a prior hop
      properties:
        raw:
          description: The raw string of 'from' section
          type: string
      type: object
    Mdm_serviceMessageType:
      description: Override on message types, defined from the perspective of your organization
      properties:
        inbound:
          description: Message was sent from someone outside your organization, to *at least one* recipient inside your organization
          type: boolean
        internal:
          description: Message was sent from someone inside your organization, to *at least one* recipient inside your organization. Messages *must be authenticated* by either SPF or DKIM to be treated as internal.
          type: boolean
        outbound:
          description: Message was sent from someone inside your organization, to *at least one* recipient outside your organization
          type: boolean
      type: object
    Mdm_serviceRewriteDetails:
      description: Information about an original URL that was unfurled from rewrite detection
      properties:
        encoders:
          description: List of detected URL rewrite encoders while unraveling the URL
          items:
            enum:
            - adobe
            - appspot
            - aws_ses
            - azurecomm
            - azure_safelink
            - barracuda
            - bing_open_redirect
            - branch_io
            - checkpoint
            - cisco
            - cloudflare
            - convertkit
            - deref_mail
            - doubleclick
            - edgepilot
            - esvalabs
            - exactag
            - exclaimer
            - facebook
            - fireeye
            - fortimail
            - generic_desturl
            - generic_logout_redirect
            - go_acoustic
            - google_amp
            - google_amp_project
            - google_adservices
            - google_meet_redirect
            - google_notifications
            - google_open_redirect
            - google_tag_manager
            - google_travel_redirect
            - google_translate_open_redirect
            - google_user_content
            - href_li
            - indeed_open_redirect
            - inky
            - instagram
            - mailgun
            - mailjet
            - mandrill
            - messagegears
            - microsoft
            - microsoft_dynamics
            - microsoft_oauth_redirect
            - monday_tracker
            - postmark
            - ppcprotect
            - proofpoint
            - pylonlinks
            - securence
            - sophos
            - sqclick
            - squarespace
            - sublime
            - titanhq
            - topsec
            - trend_micro
            - vtiger
            - wix
            - yahoo
            - youtube_set_sid
            type: string
          type: array
        original:
          description: Original URL without any unraveling URL rewrites
          type: string
      required:
      - original
      type: object
    TypesMessageType:
      description: The types of the message
      properties:
        inbound:
          description: Message was sent from someone outside your organization, to *at least one* recipient inside your organization
          type: boolean
        internal:
          description: Message was sent between two or more participants inside your organization
          type: boolean
        outbound:
          description: Message was sent from someone inside your organization, to *at least one* recipient outside your organization
          type: boolean
      type: object
    Handler_typesMessageImageLink:
      properties:
        expires_in:
          description: Approximate duration of link in seconds
          format: int32
          type: integer
        url:
          description: Temporary link to image
          type: string
      required:
      - expires_in
      - url
      type: object
    Mdm_serviceBanner:
      properties:
        links:
          description: All links found in the banner, unique by the target and display text/url.
          items:
            $ref: '#/components/schemas/Mdm_serviceLink'
          type: array
        text:
          description: The text content from the warning banner.
          type: string
      type: object
    Handler_typesTaskAccepted:
      properties:
        task_id:
          description: Task ID. Use the /v0/tasks/:id endpoint to check the task status.
          format: uuid
          type: string
      required:
      - task_id
      type: object
    Handler_typesAnalyzeResponseRule:
      properties:
        error:
          description: Error message, if success == false
          type:
          - string
          - 'null'
        execution_time:
          description: Execution time in seconds
          format: double
          type:
          - number
          - 'null'
        external_errors:
          description: External errors that occurred during evaluation
          items:
            type: string
          type: array
        matched:
          description: Whether the rule matched the provided message
          type:
          - boolean
          - 'null'
        rule:
          $ref: '#/components/schemas/Handler_typesRuleSimplePublicID'
        success:
          description: Whether execution was successful or errored
          type: boolean
      required:
      - execution_time
      - matched
      - success
      type: object
    Mdm_serviceDomain:
      description: Domain parsed from X-Authenticated-Domain or X-Authenticated-Sender headers, which represents the domain used for sender authentication, typically the domain of the sending organization. This field provides additional context for analyzing the legitimacy of the sender
      properties:
        domain:
          description: The fully qualified domain name (FQDN). This may not *always* be routable, e.g. when an email address contains a domain that is just a TLD with no SLD, e.g. foo@WIN-bar
          format: hostname
          type: string
        punycode:
          description: Interpreted punycode if the domain starts with xn--. For example, if 'domain' is 'xn--ublimesecurity-4xc.com' then 'punycode' is śublimesecurity.com
          type: string
        root_domain:
          description: The root domain, including the TLD
          format: hostname
          type: string
        sld:
          description: Second-level domain, e.g. 'windows' for the domain 'windows.net'
          type: string
        subdomain:
          description: Subdomain, e.g. 'drive' for the domain 'drive.google.com'
          type: string
        tld:
          description: The domain's top-level domain. E.g. the TLD of google.com is 'com'
          type: string
        valid:
          description: Whether the domain is valid
          type: boolean
      required:
      - domain
      type: object
    Handler_typesAnalyzeResponseQuery:
      properties:
        error:
          description: Error message, if success == false
          type:
          - string
          - 'null'
        execution_time:
          description: Execution time in seconds
          format: double
          type:
          - number
          - 'null'
        external_errors:
          description: External errors that occurred during evaluation
          items:
            type: string
          type: array
        query:
          $ref: '#/components/schemas/Handler_typesQuerySimpleMeta'
        result:
          description: Result of the query evaluation
        success:
          description: Whether execution was successful or errored
          type: boolean
      required:
      - execution_time
      - success
      type: object
    Handler_typesQuerySimpleMeta:
      description: Metadata about the query evaluated against the message
      properties:
        name:
          description: Query name
          type:
          - string
          - 'null'
        severity:
          description: Severity associated with the query
          type:
          - string
          - 'null'
        source:
          description: Query source
          type:
          - string
          - 'null'
      type: object
    Mdm_serviceReceivedVia:
      description: The 'via' section of the Received header, denoting transport
      properties:
        raw:
          description: The raw string of 'via' section
          type: string
      type: object
    Handler_typesMessageImage:
      properties:
        data:
          description: Base64-encoded image data
          format: byte
          type: string
        is_empty_body:
          description: If the message is missing a body. In this case an empty PNG is returned.
          type: boolean
        mime_type:
          description: MIME type of the image
          type: string
      type: object
    Mdm_serviceHopField:
      properties:
        name:
          description: The name of the field
          type: string
        position:
          description: This field's position along the entire list of header fields
          format: int32
          type: integer
        value:
          description: The value contained within the field
          type: string
      required:
      - name
      - position
      type: object
    Mdm_serviceMessageDataModel:
      description: Full data model of the message
      properties:
        _errors:
          description: Non-fatal errors while parsing MDM
          items:
            additionalProperties:
              type: string
            type: object
          type: array
        _meta:
          $ref: '#/components/schemas/Mdm_serviceMetadata'
        attachments:
          description: Attachments
          items:
            $ref: '#/components/schemas/Mdm_serviceAttachment'
          type: array
        body:
          $ref: '#/components/schemas/Mdm_serviceBody'
        external:
          $ref: '#/components/schemas/Mdm_serviceExternal'
        headers:
          $ref: '#/components/schemas/Mdm_serviceHeaders'
        mailbox:
          $ref: '#/components/schemas/Mdm_serviceMailboxExtended'
        recipients:
          $ref: '#/components/schemas/Mdm_serviceRecipients'
        sender:
          $ref: '#/components/schemas/Mdm_serviceSenderMailbox'
        subject:
          $ref: '#/components/schemas/Mdm_serviceSubject'
        type:
          $ref: '#/components/schemas/Mdm_serviceMessageType'
      required:
      - _meta
      - headers
      - recipients
      - sender
      - type
      type: object
    Mdm_serviceIP:
      description: X-Originating-IP header, which identifies the originating IP address of the sender client
      properties:
        ip:
          description: The IP in canonical form
          type: string
        translation:
          $ref: '#/components/schemas/Mdm_serviceIPTranslation'
        version:
          description: The version of IP (i.e., 4 or 6), null for backward compatibility.
          format: int32
          type:
          - integer
          - 'null'
      required:
      - ip
      type: object
    Mdm_serviceMailbox:
      description: Organizer mailbox with email and display name
      properties:
        display_name:
          description: Display name
          type: string
        email:
          $ref: '#/components/schemas/Mdm_serviceEmailAddress'
      required:
      - email
      type: object
    TypesPreview:
      description: Preview of key details from the message header
      properties:
        attachment_sha256

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