openapi: 3.1.0
info:
  title: PMSS API Documentation
  version: 2.0.0
  description:
    "PMSS API provides scanning, classification, and recommended actions for SMS and MMS messages, ensuring compliance and effective message processing."
tags:
  - name: Authorization
    description: Endpoints for managing authentication tokens.
  - name: Message Scanning
    description: Endpoints for scanning SMS and MM4 messages.
servers:
  - url: https://api-us.pmss.proofpoint.com
    description: Production API - US
  - url: https://api-eu.pmss.proofpoint.com
    description: Production API - EU
paths:
  /authorize/v1:
    post:
      summary: Get Authentication Token
      description: Returns authorized token for scan requests.
      tags:
        - Authorization
      operationId: requestToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - client_id
                - client_secret
                - grant_type
              properties:
                client_id:
                  type: string
                  description: The client ID issued to the application.
                client_secret:
                  type: string
                  description: The client secret issued to the application.
                grant_type:
                  type: string
                  enum:
                    - client_credentials
                  description: The grant type, must be 'client_credentials'.
      responses:
        '200':
          description: Authorization successful.
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                    example: eyJhbGciOiJIUzI1...
                  expires_in:
                    type: integer
                    example: 86400
                  token_type:
                    type: string
                    example: Bearer
        '400':
          description: Bad request due to missing or invalid parameters.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        example: 'Missing required fields: client_id, client_secret, and grant_type'
        '401':
          description: Unauthorized request due to invalid or expired credentials.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        example: Invalid or expired token. Please re-authenticate.
        '403':
          description: Forbidden request due to insufficient permissions or invalid request format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        example: The requested resource does not exist.
        '429':
          description: Rate limits
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        enum:
                          - API rate limit exceeded
                    required:
                      - code
                      - message
        '501':
          description: The server does not recognize the request method or cannot parse it.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 501
                      message:
                        type: string
                        example: Unable to parse request.
        '503':
          description: The server is currently unable to service the request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 503
                      message:
                        type: string
                        example: Unable to service request.
  /scan/v1/sms/{type}:
    post:
      summary: Scan SMS Message
      tags:
        - Message Scanning
      operationId: scanSms
      description: "Scans an SMS message for compliance and classification. Please pay close attention to the various examples and the various acceptable formats for the From value."
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - ao
              - at
              - mo
              - mt
          description: "Indicates the category of SMS message to be scanned."
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/json
          description: "Requires the request body to be formatted in JSON."
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            example: "Bearer <token>"
          description: 'Authentication token in the format: `Bearer {token}`.'
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/json
          description: "Requires the response to be returned in JSON format."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: AO Type; Short-Code Sender
                  description: "Messages originating from an application."
                  type: object
                  properties:
                    dcs:
                      type: integer
                      enum:
                        - 0
                        - 3
                        - 4
                        - 8
                      description: "Data coding scheme: For 'ao'/'at': 0/3 for Latin-1 (max 140 bytes), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters); for 'mo'/'mt': 0 for GSM 7-bit (max 160 characters), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters). Influences maximum body size limit."
                      example: 0
                    encoding:
                      type: string
                      enum:
                        - relaxed
                        - strict
                        - info
                      description: "Encoding size enforcement, default is 'relaxed'."
                    encode_option:
                      type: string
                      enum:
                        - utf16le
                        - utf16be
                      description: "For messages with DCS 8, override UTF-16 with UTF-16le or UTF-16be."
                    account_id:
                      type: string
                      description: "Unique identifier for the account; mandatory for 'ao' type."
                      example: 123456
                    account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of account creation, in epoch seconds."
                      example: 1738257512
                    sub_account_id:
                      type: string
                      description: "Unique identifier for the sub-account."
                      example: 123456
                    sub_account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sub-account creation, in epoch seconds."
                      example: 1738257512
                    sender_class:
                      oneOf:
                        - type: integer
                          minimum: 1
                          maximum: 100
                          example: 10
                        - type: string
                          example: promotional
                      description: "Classification of the sender; numeric values must range from 1 to 100; otherwise, any descriptive string is permitted (e.g., 'promotional', 'transactional')."
                    message_id:
                      type: string
                      description: "Unique identifier for the customer message."
                      example: "c5o1032iaj942fja23410jf0b0a"
                    message_sent:
                      type: integer
                      format: int64
                      description: "Timestamp when the message was sent, in epoch seconds."
                      example: 1738257512
                    category:
                      type: string
                      enum:
                        - alcohol
                        - firearms
                        - gambling
                        - pharma
                        - political
                        - tobacco
                        - other
                    brand_id:
                      type: string
                      description: "Identifier for the campaign brand."
                      example: "ACME-4321"
                    brand_name:
                      type: string
                      description: "Name of the campaign brand."
                      example: "Acme, Inc."
                    campaign_id:
                      type: string
                      description: "Identifier for the message campaign."
                      example: "anvils2025"
                    campaign_name:
                      type: string
                      description: "Name of the message campaign."
                      example: "Anvil Specials"
                    src_ip:
                      type: string
                      description: "Source IP address of the sender."
                      example: "192.168.1.1; both IPv4 & IPv6 are supported."
                    from:
                      type: string
                      description: "Short Code sender; between 3 - 8 digits."
                      example: "90210"
                    from_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sender number creation, in epoch seconds."
                      example: 1738257512
                    to:
                      type: string
                      description: "Recipient's phone number in E.164 format (e.g., +15559876543), short code (e.g., 12345), or hashed address (alphanumeric string up to 40 characters); mandatory."
                      example: "+15559876543"
                    body:
                      type: string
                      description: "Base64-encoded message content."
                      example: "QW52aWwgU3BlY2lhbCwgY2FsbCBub3ch"
                  required:
                    - account_id
                    - from
                    - to
                    - dcs
                    - body
                - title: AO Type; E.164 Sender
                  description: "Messages terminated by an application, originated by a mobile device, or terminated to a mobile device."
                  type: object
                  properties:
                    dcs:
                      type: integer
                      enum:
                        - 0
                        - 3
                        - 4
                        - 8
                      description: "Data coding scheme: For 'ao'/'at': 0/3 for Latin-1 (max 140 bytes), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters); for 'mo'/'mt': 0 for GSM 7-bit (max 160 characters), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters). Influences maximum body size limit."
                      example: 0
                    account_id:
                      type: string
                      description: "Unique identifier for the account; optional for 'at', 'mo', and 'mt' types."
                      example: "Acct-123"
                    account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of account creation, in epoch seconds; optional for 'at', 'ao', 'mo', and 'mt' types."
                      example: 1738257512
                    sub_account_id:
                      type: string
                      description: "Unique identifier for the sub-account."
                      example: "Sub-Acct-456"
                    sub_account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sub-account creation, in epoch seconds; optional for 'at', 'ao', 'mo', and 'mt' types."
                      example: 1738257512
                    sender_class:
                      oneOf:
                        - type: integer
                          minimum: 1
                          maximum: 100
                          example: 10
                        - type: string
                          example: promotional
                      description: "Classification of the sender; numeric values must range from 1 to 100; otherwise, any descriptive string is permitted (e.g., 'promotional', 'transactional')."
                    message_id:
                      type: string
                      description: "Unique identifier for the customer message."
                      example: "c5o1032iaj942fja23410jf0b0a"
                    message_sent:
                      type: integer
                      format: int64
                      description: "Timestamp when the message was sent, in epoch seconds."
                      example: 1738257512
                    brand_id:
                      type: string
                      description: "Identifier for the campaign brand."
                    brand_name:
                      type: string
                      description: "Name of the campaign brand."
                    campaign_id:
                      type: string
                      description: "Identifier for the message campaign."
                    campaign_name:
                      type: string
                      description: "Name of the message campaign."
                    src_ip:
                      type: string
                      description: "Source IP address of the sender."
                      example: "192.168.1.1"
                    from:
                      type: string
                      description: Sender in E.164 format. Must have leading +.
                      example: "+15551234567"
                    from_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sender number creation, in epoch seconds."
                      example: 1738257512
                    to:
                      type: string
                      description: "Recipient's phone number in E.164 format (e.g., +15559876543), short code (e.g., 12345), or hashed address (alphanumeric string up to 40 characters); mandatory."
                      example: "+15559876543"
                    body:
                      type: string
                      description: "Base64-encoded message content. For 'at': dcs 0/3 (Latin-1, 140 bytes), dcs 4 (8-bit binary, 140 bytes), dcs 8 (UTF-16, 70 characters). For 'mo'/'mt': dcs 0 (GSM 7-bit, 160 characters), dcs 4 (8-bit binary, 140 bytes), dcs 8 (UTF-16, 70 characters)."
                      example: "SGVsbG8gZnJvbSB0aGUgb3RoZXIgc2lkZS4="
                  required:
                    - from
                    - to
                    - dcs
                    - body
                - title: AO Type; Short Code Sender; Brand & Campaign Details
                  description: "Generally AO messages with Brand and Campaign details."
                  type: object
                  properties:
                    dcs:
                      type: integer
                      enum:
                        - 0
                        - 3
                        - 4
                        - 8
                      description: "Data coding scheme: For 'ao'/'at': 0/3 for Latin-1 (max 140 bytes), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters); for 'mo'/'mt': 0 for GSM 7-bit (max 160 characters), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters). Influences maximum body size limit."
                      example: 0
                    encoding:
                      type: string
                      enum:
                        - relaxed
                        - strict
                        - info
                      description: "Encoding size enforcement, default is 'relaxed'."
                    encode_option:
                      type: string
                      enum:
                        - utf16le
                        - utf16be
                      description: "For messages with DCS 8, override UTF-16 with UTF-16le or UTF-16be."
                    account_id:
                      type: string
                      description: "Unique identifier for the account; optional for 'at', 'mo', and 'mt' types."
                      example: "Acct-987"
                    account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of account creation, in epoch seconds; optional for 'at', 'ao', 'mo', and 'mt' types."
                      example: 1738257512
                    sub_account_id:
                      type: string
                      description: "Unique identifier for the sub-account."
                      example: "Sub-Acct-765"
                    sub_account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sub-account creation, in epoch seconds; optional for 'at', 'ao', 'mo', and 'mt' types."
                      example: 1738257512
                    sender_class:
                      oneOf:
                        - type: integer
                          minimum: 1
                          maximum: 100
                          example: 10
                        - type: string
                          example: promotional
                      description: "Classification of the sender; numeric values must range from 1 to 100; otherwise, any descriptive string is permitted (e.g., 'promotional', 'transactional')."
                    message_id:
                      type: string
                      description: "Unique identifier for the customer message."
                      example: "c5o1032iaj942fja23410jf0b0a"
                    message_sent:
                      type: integer
                      format: int64
                      description: "Timestamp when the message was sent, in epoch seconds."
                      example: 1738257512
                    brand_id:
                      type: string
                      description: "Identifier for the campaign brand."
                      example: "AcmeBrand-543"
                    brand_name:
                      type: string
                      description: "Name of the campaign brand."
                      example: "Acme Magnets"
                    campaign_id:
                      type: string
                      description: "Identifier for the message campaign."
                    campaign_name:
                      type: string
                      description: "Name of the message campaign."
                    src_ip:
                      type: string
                      description: "Source IP address of the sender."
                      example: "192.168.1.1"
                    from:
                      type: string
                      description: "Short Code sender; between 3 - 8 digits"
                      example: "90210"
                    from_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sender number creation, in epoch seconds."
                      example: 1738257512
                    to:
                      type: string
                      description: "Recipient's phone number in E.164 format (e.g., +15559876543), short code (e.g., 12345), or hashed address (alphanumeric string up to 40 characters); mandatory."
                      example: "+15559876543"
                    body:
                      type: string
                      description: "Base64-encoded message content. For 'at': dcs 0/3 (Latin-1, 140 bytes), dcs 4 (8-bit binary, 140 bytes), dcs 8 (UTF-16, 70 characters). For 'mo'/'mt': dcs 0 (GSM 7-bit, 160 characters), dcs 4 (8-bit binary, 140 bytes), dcs 8 (UTF-16, 70 characters)."
                      example: "SGVhdnkgTWFnbmV0IFNwZWNpYWwh"
                  required:
                    - from
                    - to
                    - dcs
                    - body
                    - brand_id
                    - brand_name
                    - campaign_id
                    - campaign_name
                - title: AO Type; SMS Sender ID; Sub-Acct Details
                  description: Messages sent by the child account of a parent.
                  type: object
                  properties:
                    dcs:
                      type: integer
                      enum:
                        - 0
                        - 3
                        - 4
                        - 8
                      description: "Data coding scheme: For 'ao'/'at': 0/3 for Latin-1 (max 140 bytes), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters); for 'mo'/'mt': 0 for GSM 7-bit (max 160 characters), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters). Influences maximum body size limit."
                      example: 0
                    encoding:
                      type: string
                      enum:
                        - relaxed
                        - strict
                        - info
                      description: "Encoding size enforcement, default is 'relaxed'."
                    encode_option:
                      type: string
                      enum:
                        - utf16le
                        - utf16be
                      description: "For messages with DCS 8, override UTF-16 with UTF-16le or UTF-16be."
                    account_id:
                      type: string
                      description: "Unique identifier for the account; optional for 'at', 'mo', and 'mt' types."
                      example: "Acct-353"
                    account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of account creation, in epoch seconds; optional for 'at', 'mo', and 'mt' types."
                      example: 1738257512
                    sub_account_id:
                      type: string
                      description: "Unique identifier for the sub-account."
                      example: "Sub-Acct-883"
                    sub_account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sub-account creation, in epoch seconds; optional for 'at', 'ao', 'mo', and 'mt' types."
                      example: 1738257512
                    sender_class:
                      oneOf:
                        - type: integer
                          minimum: 1
                          maximum: 100
                          example: 10
                        - type: string
                          example: promotional
                      description: "Classification of the sender; numeric values must range from 1 to 100; otherwise, any descriptive string is permitted (e.g., 'promotional', 'transactional')."
                    message_id:
                      type: string
                      description: "Unique identifier for the customer message."
                      example: "guY9ub3W4Yx5hguYTuAdQx"
                    message_sent:
                      type: integer
                      format: int64
                      description: "Timestamp when the message was sent, in epoch seconds."
                      example: 1738257512
                    brand_id:
                      type: string
                      description: "Identifier for the campaign brand."
                      example: "Acme-Explosives-123"
                    brand_name:
                      type: string
                      description: "Name of the campaign brand."
                      example: "Acme TNT"
                    campaign_id:
                      type: string
                      description: "Identifier for the message campaign."
                      example: "ACMETNT-462"
                    campaign_name:
                      type: string
                      description: "Name of the message campaign."
                      example: "TNT SPECIAL!"
                    src_ip:
                      type: string
                      description: "Source IP address of the sender."
                      example: "192.168.1.1"
                    from:
                      type: string
                      description: "Alphanumeric Sender IDs can have 3-11 characters, including letters (a-z, A-Z) and digits (0-9). Special character support varies by country; some allow them, others do not. PMSS accepts all characters, but consider downstream limitations."
                      example: "ACME"
                    from_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sender number creation, in epoch seconds."
                      example: 1738257512
                    to:
                      type: string
                      description: "Recipient's phone number in E.164 format (e.g., +15559876543), short code (e.g., 12345), or hashed address (alphanumeric string up to 40 characters); mandatory."
                      example: "+18888675309"
                    body:
                      type: string
                      description: "Base64-encoded message content. For 'at': dcs 0/3 (Latin-1, 140 bytes), dcs 4 (8-bit binary, 140 bytes), dcs 8 (UTF-16, 70 characters). For 'mo'/'mt': dcs 0 (GSM 7-bit, 160 characters), dcs 4 (8-bit binary, 140 bytes), dcs 8 (UTF-16, 70 characters)."
                      example: "SmVubnksIGNoZWNrIG91dCBvdXIgaW5zYW5lIGRlYWxzIG9uIFROVCE="
                  required:
                    - from
                    - to
                    - dcs
                    - body
                    - account_id
                    - account_age
                    - sub_account_id
                    - sub_account_age
            examples:
              AO; DCS 0 (Latin 1); Acct & Brand Details:
                summary: "Example: AO; E.164 Sender; DCS 0 (Latin-1)"
                description: "Sample Application Originated message using DCS 0 (Latin-1, maximum 140 bytes)."
                value:
                  dcs: 0
                  account_id: "Acme123"
                  account_age: 1738257512
                  sender_class: "promotional"
                  message_id: "guY9ub3W4Yx5hguYTuAdQx"
                  message_sent: 1738257512
                  brand_id: "AcmeTNT462"
                  brand_name: "Acme TNT"
                  campaign_id: "ACMETNT321"
                  campaign_name: "TNT SPECIAL!"
                  src_ip: "192.168.1.1"
                  from: "+15551234567"
                  from_age: 17384757548
                  to: "+18888675309"
                  body: "SmVubnksIGNoZWNrIG91dCBvdXIgaW5zYW5lIGRlYWxzIG9uIFROVCE="
              MO; DCS 0 (GSM 7-bit); Acct & Brand Details:
                summary: MO Message Example (GSM 7-bit)
                description: "Sample Mobile Originated message using DCS 0 (GSM 7-bit, maximum 160 characters)."
                value:
                  dcs: 0
                  sender_class: "promotional"
                  message_id: "hAUqub9dLYx5hhAV6uBCzK"
                  message_sent: 1738257512
                  src_ip: "192.168.1.1"
                  from: "+15551234567"
                  to: "+15559876543"
                  body: "SGVsbG8gZnJvbSB0aGUgb3RoZXIgc2lkZS4="
      responses:
        '200':
          description: The message was processed successfully.
          content:
            application/json:
              schema:
                oneOf:
                  - title: Allow Response
                    description: Indicates that the message should be allowed.
                    type: object
                    properties:
                      response:
                        type: object
                        properties:
                          code:
                            type: integer
                            example: 200
                          action:
                            type: string
                            enum:
                              - allow
                            description: Directs that the message should be allowed.
                      to_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      from_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                    required:
                      - response
                  - title: Block Response
                    description: Indicates that the message is prohibited from proceeding.
                    type: object
                    properties:
                      response:
                        type: object
                        properties:
                          code:
                            type: integer
                            example: 200
                          reason:
                            type: array
                            items:
                              type: string
                            description: Details the reasons for prohibiting the message.
                            example: policy_violation
                          action:
                            type: string
                            enum:
                              - block
                            description: Directs that the message should be blocked.
                        required:
                          - code
                          - reason
                          - action
                      to_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      from_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                    required:
                      - response
                  - title: Responses with Encoding Details
                    description: Indicates the message encoding size details.
                    type: object
                    properties:
                      response:
                        type: object
                        properties:
                          code:
                            type: integer
                            example: 200
                          reason:
                            type: array
                            items:
                              type: string
                            description: Details the reasons for prohibiting the message.
                            example: policy_violation
                          action:
                            type: string
                            enum:
                              - block
                              - allow
                            description: Indicates what action should be taken with the message.
                      to_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      from_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      encoding_info:
                        type: object
                        properties:
                          valid:
                            type: boolean
                            enum:
                              - false
                              - true
                          encoding:
                            type: string
                            example: US
                          max_length:
                            type: integer
                            example: 1400
                          length:
                            type: integer
                            example: 3000
                    required:
                      - response
        '400':
          description: The request contains invalid parameters or malformed data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        enum:
                          - "Invalid {type} in the path."
                          - "Invalid request: body is required."
                          - "IP address is missing or empty."
                          - "Invalid IP address format."
                          - "Non-routable IP address."
                          - "Missing or invalid 'from' field."
                          - "Missing or empty 'from' field."
                          - "'from' field exceeds 15 characters."
                          - "'from' field contains invalid characters. Only standard keyboard characters (printable ASCII) are allowed."
                          - "'from' field contains invalid escape sequences (e.g., \\n, \\t, \\r). Only standard keyboard characters are allowed."
                          - "Missing or invalid 'to' field."
                          - "SMS/SMS Long messages must have only one recipient."
                          - "Missing or empty 'to' field."
                          - "'to' field exceeds 40 characters."
                          - "'to' field contains invalid characters. Only standard keyboard characters (printable ASCII) are allowed."
                          - "'to' field contains invalid escape sequences (e.g., \\n, \\t, \\r). Only standard keyboard characters are allowed."
                          - "This endpoint does not support multi-part SMS."
                          - "Missing required 'dcs' field for SMS messages."
                          - "The 'body' field must be base64 encoded."
                          - "Invalid 'dcs' value '<dcs>' for type '<type>'. Valid values: [<valid_values>]."
                          - "Invalid GSM 7-bit character: <char>"
                          - "Packed GSM 7-bit exceeds 140 bytes"
                          - "Message body exceeds <encoding_type> limit of <max_limit> <unit> for type '<type>' (got <actual> <unit>)."
                          - "Missing or invalid 'account_id' for 'ao' message_class."
                          - "Valid 'account_id' must be provided when 'account_age' is included."
                          - "Missing or empty 'account_age' field."
                          - "Invalid 'account_age': must be a number containing only digits."
                          - "Invalid 'account_age': must be a valid epoch timestamp."
                          - "Missing or empty 'from_age' field."
                          - "Invalid 'from_age': must be a number containing only digits."
                          - "Invalid 'from_age': must be a valid epoch timestamp."
                          - "Valid 'account_id' must be provided when 'sub_account_id' is included."
                          - "Valid 'sub_account_id' must be provided when 'sub_account_age' is included."
                          - "Missing or empty 'sub_account_age' field."
                          - "Invalid 'sub_account_age': must be a number containing only digits."
                          - "Invalid 'sub_account_age': must be a valid epoch timestamp."
                          - "Invalid 'sender_class' value '<value>'. Must be between 1 and 100 when numeric."
                          - "'encode_option' is only valid for UTF-16 messages with DCS 8."
                          - "Invalid 'encode_option' '<value>'. Must be either 'utf16le' or 'utf16be'."
                          - "Invalid 'category' field: must be a non-empty string."
                          - "Invalid 'category' field: must be one of [<valid_categories>]. Got '<supplied_category>'."
                    required:
                      - code
                      - message
        '401':
          description: The request lacks proper authorization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        enum:
                          - Authorization header is missing.
                          - Authorization header is malformed.
                          - The provided JWT is invalid.
                          - JWT is missing the required 'customer' field.
                    required:
                      - code
                      - message
        '403':
          description: The request lacks sufficient permissions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        enum:
                          - Insufficient permissions to access this endpoint.
                    required:
                      - code
                      - message
        '429':
          description: Rate limits
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        enum:
                          - API rate limit exceeded
                    required:
                      - code
                      - message
  /scan/v1/sms/long/{type}:
    post:
      summary: Scan Long SMS Message
      description: Performs a compliance and classification scan on a multi-part SMS message.
      tags:
        - Message Scanning
      operationId: scanLongSMS
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - ao
              - at
              - mo
              - mt
          description: Indicates the category of multi-part SMS message to be scanned.
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/json
          description: Requires the request body to be formatted in JSON.
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            example: Bearer <token>
          description: "Authentication token in the format: `Bearer {token}`."
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/json
          description: Requires the response to be returned in JSON format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: AO Type; Short-Code Sender
                  description: "Messages originating from an application."
                  type: object
                  properties:
                    dcs:
                      type: integer
                      enum:
                        - 0
                        - 3
                        - 4
                        - 8
                      description: "Data coding scheme: For 'ao'/'at': 0/3 for Latin-1 (max 140 bytes), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters); for 'mo'/'mt': 0 for GSM 7-bit (max 160 characters), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters). Influences maximum body size limit."
                      example: 0
                    encoding:
                      type: string
                      enum:
                        - relaxed
                        - strict
                        - info
                      description: "Encoding size enforcement, default is 'relaxed'."
                    encode_option:
                      type: string
                      enum:
                        - utf16le
                        - utf16be
                      description: "For messages with DCS 8, override UTF-16 with UTF-16le or UTF-16be."
                    account_id:
                      type: string
                      description: "Unique identifier for the account; mandatory for 'ao' type."
                      example: 123456
                    account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of account creation, in epoch seconds."
                      example: 1738257512
                    sub_account_id:
                      type: string
                      description: "Unique identifier for the sub-account."
                      example: 123456
                    sub_account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sub-account creation, in epoch seconds."
                      example: 1738257512
                    sender_class:
                      oneOf:
                        - type: integer
                          minimum: 1
                          maximum: 100
                          example: 10
                        - type: string
                          example: promotional
                      description: "Classification of the sender; numeric values must range from 1 to 100; otherwise, any descriptive string is permitted (e.g., 'promotional', 'transactional')."
                    message_id:
                      type: string
                      description: "Unique identifier for the customer message."
                      example: "c5o1032iaj942fja23410jf0b0a"
                    message_sent:
                      type: integer
                      format: int64
                      description: "Timestamp when the message was sent, in epoch seconds."
                      example: 1738257512
                    category:
                      type: string
                      enum:
                        - alcohol
                        - firearms
                        - gambling
                        - pharma
                        - political
                        - tobacco
                        - other
                    brand_id:
                      type: string
                      description: "Identifier for the campaign brand."
                      example: "ACME-4321"
                    brand_name:
                      type: string
                      description: "Name of the campaign brand."
                      example: "Acme, Inc."
                    campaign_id:
                      type: string
                      description: "Identifier for the message campaign."
                      example: "anvils2025"
                    campaign_name:
                      type: string
                      description: "Name of the message campaign."
                      example: "Anvil Specials"
                    src_ip:
                      type: string
                      description: "Source IP address of the sender."
                      example: "192.168.1.1; both IPv4 & IPv6 are supported."
                    from:
                      type: string
                      description: "Short Code sender; between 3 - 8 digits."
                      example: "90210"
                    from_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sender number creation, in epoch seconds."
                      example: 1738257512
                    to:
                      type: string
                      description: "Recipient's phone number in E.164 format (e.g., +15559876543), short code (e.g., 12345), or hashed address (alphanumeric string up to 40 characters); mandatory."
                      example: "+15559876543"
                    body:
                      type: string
                      description: "Base64-encoded message content."
                      example: "QW52aWwgU3BlY2lhbCwgY2FsbCBub3ch"
                    sar_msg_ref_num:
                      type: integer
                      minimum: 0
                      maximum: 65535
                      description: "SAR message reference number, ranging from 0 to 65535."
                      example: 123456
                    sar_total_segments:
                      type: integer
                      minimum: 1
                      maximum: 65535
                      description: "Number of segments in the multi-part message, ranging from 1 to 65535."
                      example: 3
                    sar_segment_seq:
                      type: integer
                      minimum: 1
                      maximum: 65535
                      description: "Sequence number of the current message segment, ranging from 1 to 65535."
                      example: 2
                  required:
                    - account_id
                    - from
                    - to
                    - dcs
                    - body
                    - sar_msg_ref_num
                    - sar_total_segments
                    - sar_segment_seq
                - title: AO Type; E.164 Sender
                  description: "Messages terminated by an application, originated by a mobile device, or terminated to a mobile device."
                  type: object
                  properties:
                    dcs:
                      type: integer
                      enum:
                        - 0
                        - 3
                        - 4
                        - 8
                      description: "Data coding scheme: For 'ao'/'at': 0/3 for Latin-1 (max 140 bytes), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters); for 'mo'/'mt': 0 for GSM 7-bit (max 160 characters), 4 for 8-bit binary (max 140 bytes), 8 for UTF-16/UCS2 (max 70 characters). Influences maximum body size limit."
                      example: 0
                    account_id:
                      type: string
                      description: "Unique identifier for the account; optional for 'at', 'mo', and 'mt' types."
                      example: "Acct-123"
                    account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of account creation, in epoch seconds; optional for 'at', 'mo', and 'mt' types."
                      example: 1738257512
                    sub_account_id:
                      type: string
                      description: "Unique identifier for the sub-account."
                      example: "Sub-Acct-456"
                    sub_account_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sub-account creation, in epoch seconds; optional for 'at', 'ao', 'mo', and 'mt' types."
                      example: 1738257512
                    sender_class:
                      oneOf:
                        - type: integer
                          minimum: 1
                          maximum: 100
                          example: 10
                        - type: string
                          example: promotional
                      description: "Classification of the sender; numeric values must range from 1 to 100; otherwise, any descriptive string is permitted (e.g., 'promotional', 'transactional')."
                    message_id:
                      type: string
                      description: "Unique identifier for the customer message."
                      example: "c5o1032iaj942fja23410jf0b0a"
                    message_sent:
                      type: integer
                      format: int64
                      description: "Timestamp when the message was sent, in epoch seconds."
                      example: 1738257512
                    brand_id:
                      type: string
                      description: "Identifier for the campaign brand."
                    brand_name:
                      type: string
                      description: "Name of the campaign brand."
                    campaign_id:
                      type: string
                      description: "Identifier for the message campaign."
                    campaign_name:
                      type: string
                      description: "Name of the message campaign."
                    src_ip:
                      type: string
                      description: "Source IP address of the sender."
                      example: "192.168.1.1"
                    from:
                      type: string
                      description: "Sender in E.164 format. Must have leading +."
                      example: "+15551234567"
                    from_age:
                      type: integer
                      format: int64
                      description: "Timestamp of sender number creation, in epoch seconds."
                      example: 1738257512
                    to:
                      type: string
                      description: "Recipient's phone number in E.164 format (e.g., +15559876543), short code (e.g., 12345), or hashed address (alphanumeric string up to 40 characters); mandatory."
                      example: "+15559876543"
                    body:
                      type: string
                      description: "Base64-encoded message content. For 'at': dcs 0/3 (Latin-1, 140 bytes), dcs 4 (8-bit binary, 140 bytes), dcs 8 (UTF-16, 70 characters). For 'mo'/'mt': dcs 0 (GSM 7-bit, 160 characters), dcs 4 (8-bit binary, 140 bytes), dcs 8 (UTF-16, 70 characters)."
                      example: "SGVsbG8gZnJvbSB0aGUgb3RoZXIgc2lkZS4="
                    sar_msg_ref_num:
                      type: integer
                      minimum: 0
                      maximum: 65535
                      description: "SAR message reference number, ranging from 0 to 65535."
                      example: 123456
                    sar_total_segments:
                      type: integer
                      minimum: 1
                      maximum: 65535
                      description: "Number of segments in the multi-part message, ranging from 1 to 65535."
                      example: 3
                    sar_segment_seq:
                      type: integer
                      minimum: 1
                      maximum: 65535
                      description: "Sequence number of the current message segment, ranging from 1 to 65535."
                      example: 2
                  required:
                    - from
                    - to
                    - dcs
                    - body
                    - sar_msg_ref_num
                    - sar_total_segments
                    - sar_segment_seq

            examples:
              AO; DCS 0 (Latin 1); Acct & Brand Details:
                summary: "Example: AO; E.164 Sender; DCS 0 (Latin-1)"
                description: "Sample Application Originated message using DCS 0 (Latin-1, maximum 140 bytes)."
                value:
                  dcs: 0
                  account_id: "Acme123"
                  account_age: 1738257512
                  sender_class: "promotional"
                  message_id: "guY9ub3W4Yx5hguYTuAdQx"
                  message_sent: 1738257512
                  brand_id: "AcmeTNT462"
                  brand_name: "Acme TNT"
                  campaign_id: "ACMETNT321"
                  campaign_name: "TNT SPECIAL!"
                  src_ip: "192.168.1.1"
                  from: "+15551234567"
                  from_age: 17384757548
                  to: "+18888675309"
                  sar_msg_ref_num: 35142
                  sar_total_segments: 3
                  sar_segment_seq: 2
                  body: "SmVubnksIGNoZWNrIG91dCBvdXIgaW5zYW5lIGRlYWxzIG9uIFROVCE="
              MO; DCS 0 (GSM 7-bit); Acct & Brand Details:
                summary: MO Message Example (GSM 7-bit)
                description: "Sample Mobile Originated message using DCS 0 (GSM 7-bit, maximum 160 characters)."
                value:
                  dcs: 0
                  sender_class: "promotional"
                  message_id: "hAUqub9dLYx5hhAV6uBCzK"
                  message_sent: 1738257512
                  src_ip: "192.168.1.1"
                  from: "+15551234567"
                  to: "+15559876543"
                  sar_msg_ref_num: 11428
                  sar_total_segments: 2
                  sar_segment_seq: 1
                  body: "SGVsbG8gZnJvbSB0aGUgb3RoZXIgc2lkZS4="
      responses:
        '200':
          description: The message was processed successfully.
          content:
            application/json:
              schema:
                oneOf:
                  - title: Allow Response
                    description: Indicates that the message should be allowed.
                    type: object
                    properties:
                      response:
                        type: object
                        properties:
                          code:
                            type: integer
                            example: 200
                          action:
                            type: string
                            enum:
                              - allow
                            description: Directs that the message should be allowed.
                      to_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      from_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                    required:
                      - response
                  - title: Block Response
                    description: Indicates that the message is prohibited from proceeding.
                    type: object
                    properties:
                      response:
                        type: object
                        properties:
                          code:
                            type: integer
                            example: 200
                          reason:
                            type: array
                            items:
                              type: string
                            description: Details the reasons for prohibiting the message.
                            example: policy_violation
                          action:
                            type: string
                            enum:
                              - block
                            description: Directs that the message should be blocked.
                        required:
                          - code
                          - reason
                          - action
                      to_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      from_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                    required:
                      - response
                  - title: Responses with Encoding Details
                    description: Indicates the message encoding size details.
                    type: object
                    properties:
                      response:
                        type: object
                        properties:
                          code:
                            type: integer
                            example: 200
                          reason:
                            type: array
                            items:
                              type: string
                            description: Details the reasons for prohibiting the message.
                            example: policy_violation
                          action:
                            type: string
                            enum:
                              - block
                              - allow
                            description: Indicates what action should be taken with the message.
                      to_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      from_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      encoding_info:
                        type: object
                        properties:
                          valid:
                            type: boolean
                            enum:
                              - false
                              - true
                          encoding:
                            type: string
                            example: US
                          max_length:
                            type: integer
                            example: 1400
                          length:
                            type: integer
                            example: 3000
                    required:
                      - response
        '400':
          description: The request contains invalid parameters or malformed data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        enum:
                          - "Invalid {type} in the path."
                          - "Invalid request: body is required."
                          - "IP address is missing or empty"
                          - "Invalid IP address format"
                          - "Non-routable IP address"
                          - "Missing or invalid 'from' field."
                          - "Missing or empty 'from' field."
                          - "'from' field exceeds 15 characters."
                          - "'from' field contains invalid characters. Only standard keyboard characters (printable ASCII) are allowed."
                          - "'from' field contains invalid escape sequences (e.g., \\n, \\t, \\r). Only standard keyboard characters are allowed."
                          - "Missing or invalid 'to' field."
                          - "SMS/SMS Long messages must have only one recipient."
                          - "Missing or empty 'to' field."
                          - "'to' field exceeds 40 characters."
                          - "'to' field contains invalid characters. Only standard keyboard characters (printable ASCII) are allowed."
                          - "'to' field contains invalid escape sequences (e.g., \\n, \\t, \\r). Only standard keyboard characters are allowed."
                          - "Missing required 'dcs' field for SMS messages."
                          - "Missing required SAR fields (sar_msg_ref_num, sar_total_segments, sar_segment_seqnum)."
                          - "Invalid sar_msg_ref_num: must be a number between 0 and 65535."
                          - "Invalid sar_total_segments: must be a number between 1 and 255."
                          - "Invalid sar_segment_seqnum: must be a number between 1 and sar_total_segments (<sar_total_segments>)."
                          - "The 'body' field must be base64 encoded."
                          - "Invalid 'dcs' value '<dcs>' for type '<type>'. Valid values: [<valid_values>]."
                          - "Invalid GSM 7-bit character: <char>"
                          - "Packed GSM 7-bit exceeds 134 bytes"
                          - "Message body exceeds <encoding_type> limit of <max_limit> <unit> for type '<type>' (got <actual> <unit>)."
                          - "Missing or invalid 'account_id' for 'ao' message_class."
                          - "Valid 'account_id' must be provided when 'account_age' is included."
                          - "Missing or empty 'account_age' field."
                          - "Invalid 'account_age': must be a number containing only digits."
                          - "Invalid 'account_age': must be a valid epoch timestamp in seconds (0 to 2147483647, approximately 1970 to 2038). Got <value>."
                          - "Missing or empty 'from_age' field."
                          - "Invalid 'from_age': must be a number containing only digits."
                          - "Invalid 'from_age': must be a valid epoch timestamp in seconds (0 to 2147483647, approximately 1970 to 2038). Got <value>."
                          - "Valid 'account_id' must be provided when 'sub_account_id' is included."
                          - "Valid 'sub_account_id' must be provided when 'sub_account_age' is included."
                          - "Missing or empty 'sub_account_age' field."
                          - "Invalid 'sub_account_age': must be a number containing only digits."
                          - "Invalid 'sub_account_age': must be a valid epoch timestamp in seconds (0 to 2147483647, approximately 1970 to 2038). Got <value>."
                          - "Invalid 'sender_class' value '<value>'. Must be between 1 and 100 when numeric."
                          - "'encode_option' is only valid for UTF-16 messages with DCS 8"
                          - "Invalid 'encode_option' '<value>'. Must be either 'utf16le' or 'utf16be'"
                          - "Invalid 'category' field: must be a non-empty string."
                          - "Invalid 'category' field: must be one of [<valid_categories>]. Got '<supplied_category>'."
                    required:
                      - code
                      - message
        '401':
          description: The request lacks proper authorization.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        enum:
                          - Authorization header is missing.
                          - Authorization header is malformed.
                          - The provided JWT is invalid.
                          - JWT is missing the required 'customer' field.
                    required:
                      - code
                      - message
        '403':
          description: The request lacks sufficient permissions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        enum:
                          - Insufficient permissions to access this endpoint.
                    required:
                      - code
                      - message
        '429':
          description: Rate limits
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        enum:
                          - API rate limit exceeded
                    required:
                      - code
                      - message
  /scan/v1/mm4/{type}:
    post:
      summary: Scan MMS Message
      description: Processes an MMS (MM4) message for compliance and classification. The message body must be a base64-encoded MM4 payload, with a maximum size of 10MB after decoding (approximately 13.98MB when base64-encoded due to encoding overhead).
      tags:
        - Message Scanning
      operationId: scanMMS4
      parameters:
        - name: type
          in: path
          required: true
          schema:
            type: string
            enum:
              - ao
              - at
              - mo
              - mt
            description: Specifies the type of MM4 message being scanned; must match the 'type' field in the request body.
        - name: Content-Type
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/json
          description: Specifies that the request body is in JSON format.
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            example: Bearer <token>
          description: "Authentication token in the format: 'Bearer {token}'."
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            enum:
              - application/json
          description: Specifies that the response must be in JSON format.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - title: AO Message Type
                  description: Application Originated MM4 Messages
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - ao
                      description: Message type, must be 'ao' for this schema.
                    account_id:
                      type: string
                      description: Account ID; mandatory for 'ao' messages.
                      example: abc123
                    account_sub_id:
                      type: string
                      description: Sub-Account ID; optional.
                      example: sub123
                    account_age:
                      type: integer
                      format: int64
                      description: Account creation timestamp in epoch seconds; mandatory.
                      example: 1234567890
                    from_age:
                      type: integer
                      format: int64
                      description: Sender timestamp creation in epoch seconds; mandatory.
                      example: 1234567890
                    sender_class:
                      oneOf:
                        - type: integer
                          minimum: 1
                          maximum: 100
                          example: 100
                        - type: string
                          example: promotional
                      description: Class of sender; if numeric, must be between 1 and 100; otherwise, any string is permitted (e.g., 'suspect', 'bulk_senders').
                    message_id:
                      type: string
                      description: Customer message ID.
                      example: abc123
                    message_sent:
                      type: integer
                      format: int64
                      description: Timestamp of message transmission in epoch seconds.
                      example: 1234567890
                    category:
                      type: string
                      enum:
                        - alcohol
                        - firearms
                        - gambling
                        - pharma
                        - political
                        - tobacco
                        - other
                    brand_id:
                      type: string
                      description: Campaign brand ID.
                      example: Brand123
                    brand_name:
                      type: string
                      description: Campaign brand name.
                    campaign_id:
                      type: string
                      description: Message campaign ID.
                      example: ac123
                    campaign_name:
                      type: string
                      description: Message campaign name.
                    src_ip:
                      type: string
                      description: Source IP address of the message.
                      example: 192.168.1.1
                    body:
                      type: string
                      description: Base64-encoded MM4 message body; maximum size is 10MB after base64 decoding (approx 13.98MB when base64-encoded). The decoded payload must include 'From' field and at least one 'To' or 'Sender' field with E.164 numbers (e.g., '+141234567890'), optionally followed by '/TYPE=YES@domain').
                      example: SGVsbG8gZnJvbSB0aGUgb3RoZXIgc2lkZQ==
                  required:
                    - type
                    - account_id
                    - body
                - title: AT, MO, or MT Message Types
                  description: Application Terminated, Mobile Originated, and Mobile Terminated MM4 Messages.
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - at
                        - mo
                        - mt
                      description: Message type, must be 'at', 'mo', or 'mt' for this schema.
                    account_id:
                      type: string
                      description: Account ID; optional for 'at', 'mo', or 'mt'.
                      example: abc123
                    account_sub_id:
                      type: string
                      description: Sub-account ID; optional.
                      example: sub123
                    account_age:
                      type: integer
                      format: int64
                      description: Account creation timestamp in epoch seconds; optional for 'at', 'mo', or 'mt'.
                      example: 1234567890
                    from_age:
                      type: integer
                      format: int64
                      description: Sender creation timestamp in epoch seconds; optional.
                      example: 1234567890
                    sender_class:
                      oneOf:
                        - type: integer
                          minimum: 1
                          maximum: 100
                          example: 100
                        - type: string
                          example: promotional
                      description: Class of sender; optional; if numeric, must be between 1 and 100; otherwise, any string is permitted (e.g., 'suspect', 'bulk_senders').
                    message_id:
                      type: string
                      description: Customer message identifier.
                      example: xyz456
                    message_sent:
                      type: integer
                      format: int64
                      description: Timestamp of message transmission in epoch seconds.
                      example: 1234567890
                    brand_id:
                      type: string
                      description: Campaign brand identifier.
                      example: Brand456
                    brand_name:
                      type: string
                      description: Campaign brand name.
                      example: Beta
                    campaign_id:
                      type: string
                      description: Message campaign identifier.
                      example: cm456
                    campaign_name:
                      type: string
                      description: Message campaign name.
                      example: CampaignPromo
                    src_ip:
                      type: string
                      description: Source IP address of the message.
                      example: 192.168.1.2
                    body:
                      type: string
                      description: Base64-encoded MM4 message body; maximum size is 10MB after base64 decoding (approx 13.98MB when base64-encoded). The decoded payload must include 'From' field and at least one 'To' or 'Sender' field with E.164 numbers (e.g., '+141234567890'), optionally followed by '/TYPE=YES@domain').
                      example: SGVsbG8gZnJvbSB0aGUgb3RoZQ==
                  required:
                    - type
                    - body
            examples:
              AO; Acct & Brand Details:
                summary: "Example: AO"
                description: "Sample Application Originated message."
                value:
                  account_id: "Acme123"
                  account_age: 1738257512
                  sender_class: "promotional"
                  message_id: "guY9ub3W4Yx5hguYTuAdQx"
                  message_sent: 1738257512
                  brand_id: "AcmeTNT462"
                  brand_name: "Acme TNT"
                  campaign_id: "ACMETNT321"
                  campaign_name: "TNT SPECIAL!"
                  src_ip: "192.168.1.1"
                  from_age: 17384757548
                  body: "dGhpcyBzaG91bGQgYmUgdGhlIGJhc2U2NCBlbmNvZGVkIG1tNCBtZXNzYWdlIHcvIGZ1bGwgaGVhZGVyczsgdGhlIEZyb20gYW5kIFRvIGFyZSBleHRyYWN0ZWQgZnJvbSB0aGUgbWVzc2FnZSBib2R5"
              MO:
                summary: MO MM4 Message Example
                description: "Sample Mobile Originated MM4 message."
                value:
                  dcs: 0
                  sender_class: "default"
                  message_id: "hAUqub9dLYx5hhAV6uBCzK"
                  message_sent: 1738257512
                  src_ip: "192.168.1.1"
                  body: "dGhpcyBzaG91bGQgYmUgdGhlIGJhc2U2NCBlbmNvZGVkIG1tNCBtZXNzYWdlIHcvIGZ1bGwgaGVhZGVyczsgdGhlIEZyb20gYW5kIFRvIGFyZSBleHRyYWN0ZWQgZnJvbSB0aGUgbWVzc2FnZSBib2R5"
      responses:
        '200':
          description: The message was processed successfully.
          content:
            application/json:
              schema:
                oneOf:
                  - title: Allow Response
                    description: Indicates that the message should be allowed.
                    type: object
                    properties:
                      response:
                        type: object
                        properties:
                          code:
                            type: integer
                            example: 200
                          action:
                            type: string
                            enum:
                              - allow
                            description: Directs that the message should be allowed.
                      to_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      from_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                    required:
                      - response
                  - title: Block Response
                    description: Indicates that the message is prohibited from proceeding.
                    type: object
                    properties:
                      response:
                        type: object
                        properties:
                          code:
                            type: integer
                            example: 200
                          reason:
                            type: array
                            items:
                              type: string
                            description: Details the reasons for prohibiting the message.
                            example: policy_violation
                          action:
                            type: string
                            enum:
                              - block
                            description: Directs that the message should be blocked.
                        required:
                          - code
                          - reason
                          - action
                      to_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                      from_meta:
                        type: object
                        properties:
                          ccode:
                            type: string
                            example: US
                    required:
                      - response
        '400':
          description: The request contains invalid parameters or malformed data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 400
                      message:
                        type: string
                        enum:
                          - "Invalid {type} in the path"
                          - "Invalid 'category' field: must be a non-empty string."
                          - "Invalid 'category' field: must be one of [<valid_categories>]. Got <query_category>."
                          - "Missing or invalid 'type' in request body"
                          - "Invalid 'type' in request body"
                          - "IP address is missing or empty."
                          - "Invalid IP address format."
                          - "Non-routable IP address."
                          - "Missing or invalid 'account_id' for 'ao' message_class."
                          - "Invalid 'account_age' for 'ao' message_class."
                          - "Invalid 'from_age' for 'ao' message_class."
                          - "Missing 'account_age' must be supplied with 'account_id'."
                          - "Missing 'account_id' must be supplied with 'account_age'."
                          - "Invalid 'account_age' for message class <message_class>."
                          - "Invalid 'from_age' for message class <message_class>."
                          - "Valid 'account_id' must be provided when 'sub_account_id' is included."
                          - "Missing 'sub_account_age' when 'sub_account_id' is provided."
                          - "Invalid 'sub_account_age' when 'sub_account_id' is provided."
                          - "Missing reg data: 'brand_id', 'brand_name', 'campaign_id' and 'campaign_name' are all required when one is supplied."
                          - "Invalid 'sender_class' value 'X'. Must be between 1 and 100 when numeric"
                          - "Failed to decode base64 message body."
                          - "No valid E.164 numbers extracted from message body."
                          - "Category validation failed: Invalid 'category' field: must be a non-empty string."
                          - "Category validation failed: Invalid 'category' field: must be one of [<valid_categories>]. Got <query_category>."
                    required:
                      - code
                      - message
        '401':
          description: Authentication failed due to an invalid or missing authorization token.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 401
                      message:
                        type: string
                        enum:
                          - "Customer identifier not available."
                    required:
                      - code
                      - message
        '403':
          description: The request was denied due to insufficient permissions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 403
                      message:
                        type: string
                        enum:
                          - Insufficient permissions to access this endpoint
                    required:
                      - code
                      - message
        '413':
          description: The request payload exceeds the size limit of 10MB after base64 decoding. Due to base64 encoding overhead (approximately 33%), this corresponds to a maximum encoded size of approximately 13.98MB.
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 413
                      message:
                        type: string
                        enum:
                          - "Payload too large. Maximum allowed size is 10MB (base64 encoded)."
                    required:
                      - code
                      - message
              examples:
                oversized_payload:
                  summary: Payload Exceeds Size Limit
                  description: Returned when the base64-encoded MM4 payload exceeds approximately 13.98MB, which decodes to more than 10MB.
                  value:
                    response:
                      code: 413
                      message: Payload too large. Maximum allowed size is 10MB (base64 encoded).
        '429':
          description: Rate limits
          content:
            application/json:
              schema:
                type: object
                properties:
                  response:
                    type: object
                    properties:
                      code:
                        type: integer
                        example: 429
                      message:
                        type: string
                        enum:
                          - API rate limit exceeded
                    required:
                      - code
                      - message
