openapi: 3.1.0
info:
  title: Palo Alto Networks Email DLP API
  description: >-
    REST API for managing email-specific Data Loss Prevention (DLP)
    incidents through Palo Alto Networks cloud-delivered security
    services. Provides detection, investigation, and verdict management
    for sensitive data found in email messages and attachments. Enables
    security teams to review email DLP violations, update verdicts to
    allow or block message delivery, and retrieve detailed incident
    context including sender, recipient, and data pattern match
    information. Requires an active Enterprise DLP subscription with
    email channel monitoring enabled. Requires SOC_Admin, Superuser,
    or Data_Security_Admin role for access.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api.{region}.dlp.paloaltonetworks.com/v1
  description: Email DLP API production server.
  variables:
    region:
      description: >-
        Deployment region for the Email DLP service. Choose the
        region matching your tenant data residency.
      default: us
      enum:
      - us
      - eu
      - in
      - apac
      - uk
      - jp
      - au
security:
- bearerAuth: []
tags:
- name: Attachments
  description: Email attachment retrieval operations.
- name: Incidents
  description: Email DLP incident management operations.
- name: Recipients
  description: Email recipient retrieval operations.
paths:
  /email-incidents:
    get:
      operationId: listEmailIncidents
      summary: Palo Alto Networks List Email Incidents
      description: >-
        Returns a paginated list of email DLP incidents where sensitive
        data was detected in email messages or attachments. Supports
        filtering by status, time range, and pagination. Each incident
        represents a single email message that triggered one or more
        data pattern matches.
      tags:
      - Incidents
      parameters:
      - name: offset
        in: query
        description: Pagination offset.
        schema:
          type: integer
          default: 0
        example: 0
      - name: limit
        in: query
        description: Maximum number of incidents to return.
        schema:
          type: integer
          default: 100
          maximum: 500
        example: 100
      - name: status
        in: query
        description: Filter incidents by current status.
        schema:
          type: string
          enum:
          - pending
          - allowed
          - blocked
          - quarantined
        example: pending
      - name: start_time
        in: query
        description: Start of time range filter (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2025-03-04T07:46:01Z'
      - name: end_time
        in: query
        description: End of time range filter (ISO 8601 format).
        schema:
          type: string
          format: date-time
        example: '2024-04-23T13:33:45Z'
      responses:
        '200':
          description: Email DLP incidents returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of incidents matching the query.
                  offset:
                    type: integer
                  limit:
                    type: integer
                  incidents:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailDLPIncident'
              examples:
                ListEmailIncidents200Example:
                  summary: Default listEmailIncidents 200 response
                  x-microcks-default: true
                  value:
                    total: 952
                    offset: 886
                    limit: 211
                    incidents:
                    - id: example-id
                      sender: example-sender
                      subject: example-subject
                      status: quarantined
                      severity: high
                      data_patterns: &id001
                      - id: example-id
                        name: Corporate Gateway 08
                        category: advanced
                        match_count: 213
                      - id: example-id
                        name: Branch Firewall 50
                        category: custom
                        match_count: 866
                      match_count: 977
                      timestamp: '2026-05-12T04:25:43Z'
                      has_attachments: true
                      attachment_count: 524
                      direction: inbound
                      action_taken: block
                      reviewed_by: example-reviewed_by
                      reviewed_at: '2026-08-04T23:58:33Z'
                      comment: Alert investigation configured detected investigation network network threat.
                    - id: example-id
                      sender: example-sender
                      subject: example-subject
                      status: quarantined
                      severity: high
                      data_patterns: *id001
                      match_count: 977
                      timestamp: '2026-05-12T04:25:43Z'
                      has_attachments: true
                      attachment_count: 524
                      direction: inbound
                      action_taken: block
                      reviewed_by: example-reviewed_by
                      reviewed_at: '2026-08-04T23:58:33Z'
                      comment: Alert investigation configured detected investigation network network threat.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /email-incidents/{id}:
    get:
      operationId: getEmailIncident
      summary: Palo Alto Networks Get Email Incident Details
      description: >-
        Returns detailed information for a specific email DLP incident
        including sender, recipients, subject, verdict, and data pattern
        matches. Provides full incident context for investigation and
        triage.
      tags:
      - Incidents
      parameters:
      - name: id
        in: path
        required: true
        description: Unique incident identifier.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Email DLP incident returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmailDLPIncident'
              examples:
                GetEmailIncident200Example:
                  summary: Default getEmailIncident 200 response
                  x-microcks-default: true
                  value:
                    id: example-id
                    sender: example-sender
                    subject: example-subject
                    status: quarantined
                    severity: high
                    data_patterns: *id001
                    match_count: 977
                    timestamp: '2026-05-12T04:25:43Z'
                    has_attachments: true
                    attachment_count: 524
                    direction: inbound
                    action_taken: block
                    reviewed_by: example-reviewed_by
                    reviewed_at: '2026-08-04T23:58:33Z'
                    comment: Alert investigation configured detected investigation network network threat.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /email-incidents/{id}/verdict:
    put:
      operationId: updateEmailIncidentVerdict
      summary: Palo Alto Networks Update Email Incident Verdict
      description: >-
        Updates the verdict for a specific email DLP incident. Allows
        security analysts to override the automated verdict by approving
        blocked messages (allow) or blocking previously allowed messages
        (block). Supports adding a comment to document the decision.
      tags:
      - Incidents
      parameters:
      - name: id
        in: path
        required: true
        description: Unique incident identifier.
        schema:
          type: string
        example: example-id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - verdict
              properties:
                verdict:
                  type: string
                  enum:
                  - allow
                  - block
                  description: >-
                    New verdict for the email message. Setting to allow
                    releases a quarantined or blocked message for delivery.
                    Setting to block prevents delivery of a pending message.
                comment:
                  type: string
                  description: Comment explaining the verdict decision.
            examples:
              UpdateEmailIncidentVerdictRequestExample:
                summary: Default updateEmailIncidentVerdict request
                x-microcks-default: true
                value:
                  verdict: allow
                  comment: Firewall suspicious endpoint alert policy traffic.
      responses:
        '200':
          description: Verdict updated successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether the update was successful.
                  incident:
                    $ref: '#/components/schemas/EmailDLPIncident'
              examples:
                UpdateEmailIncidentVerdict200Example:
                  summary: Default updateEmailIncidentVerdict 200 response
                  x-microcks-default: true
                  value:
                    success: false
                    incident:
                      id: example-id
                      sender: example-sender
                      subject: example-subject
                      status: quarantined
                      severity: high
                      data_patterns: *id001
                      match_count: 977
                      timestamp: '2026-05-12T04:25:43Z'
                      has_attachments: true
                      attachment_count: 524
                      direction: inbound
                      action_taken: block
                      reviewed_by: example-reviewed_by
                      reviewed_at: '2026-08-04T23:58:33Z'
                      comment: Alert investigation configured detected investigation network network threat.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /email-incidents/{id}/attachments:
    get:
      operationId: getEmailIncidentAttachments
      summary: Palo Alto Networks Get Email Incident Attachments
      description: >-
        Returns metadata for all attachments associated with a specific
        email DLP incident. Includes attachment filename, content type,
        size, and data pattern match information for each attachment that
        contributed to the incident.
      tags:
      - Attachments
      parameters:
      - name: id
        in: path
        required: true
        description: Unique incident identifier.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Email attachments returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident_id:
                    type: string
                    description: Identifier of the parent incident.
                  attachments:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailAttachment'
              examples:
                GetEmailIncidentAttachments200Example:
                  summary: Default getEmailIncidentAttachments 200 response
                  x-microcks-default: true
                  value:
                    incident_id: '290598'
                    attachments:
                    - filename: Corporate Policy 38
                      content_type: advanced
                      size: 438
                      has_matches: false
                      match_count: 158
                      patterns_matched: &id002
                      - example-patterns_matched_item
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /email-incidents/{id}/recipients:
    get:
      operationId: getEmailIncidentRecipients
      summary: Palo Alto Networks Get Email Incident Recipients
      description: >-
        Returns the list of recipients for the email message associated
        with a specific DLP incident. Includes To, CC, and BCC
        recipients along with their delivery status.
      tags:
      - Recipients
      parameters:
      - name: id
        in: path
        required: true
        description: Unique incident identifier.
        schema:
          type: string
        example: example-id
      responses:
        '200':
          description: Email recipients returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  incident_id:
                    type: string
                    description: Identifier of the parent incident.
                  recipients:
                    type: array
                    items:
                      $ref: '#/components/schemas/EmailRecipient'
              examples:
                GetEmailIncidentRecipients200Example:
                  summary: Default getEmailIncidentRecipients 200 response
                  x-microcks-default: true
                  value:
                    incident_id: '965151'
                    recipients:
                    - email: security-ops@example.com
                      type: cc
                      delivery_status: pending
                    - email: security-ops@example.com
                      type: cc
                      delivery_status: pending
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token for authentication. Requires SOC_Admin, Superuser,
        or Data_Security_Admin role assigned in the Palo Alto Networks
        tenant.
  responses:
    BadRequest:
      description: Invalid request parameters or body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Invalid or expired bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient role permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    EmailDLPIncident:
      type: object
      properties:
        id:
          type: string
          description: Unique incident identifier.
          example: example-id
        sender:
          type: string
          description: Email address of the message sender.
          example: example-sender
        subject:
          type: string
          description: Email message subject line.
          example: example-subject
        status:
          type: string
          enum:
          - pending
          - allowed
          - blocked
          - quarantined
          description: Current status or verdict for the email message.
          example: quarantined
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          - informational
          description: Incident severity based on data pattern sensitivity.
          example: high
        data_patterns:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: example-id
              name:
                type: string
                example: Primary Agent 95
              category:
                type: string
                example: advanced
              match_count:
                type: integer
                example: 353
          description: Data patterns that matched in the email content.
          example: *id001
        match_count:
          type: integer
          description: Total number of data pattern matches across all patterns.
          example: 977
        timestamp:
          type: string
          format: date-time
          description: Timestamp when the incident was detected.
          example: '2026-05-12T04:25:43Z'
        has_attachments:
          type: boolean
          description: Whether the email contained attachments.
          example: true
        attachment_count:
          type: integer
          description: Number of attachments in the email.
          example: 524
        direction:
          type: string
          enum:
          - inbound
          - outbound
          - internal
          description: Direction of the email message.
          example: inbound
        action_taken:
          type: string
          enum:
          - alert
          - block
          - quarantine
          description: Automated action taken on the message.
          example: block
        reviewed_by:
          type: string
          description: Email address of the analyst who reviewed the incident.
          example: example-reviewed_by
        reviewed_at:
          type: string
          format: date-time
          description: Timestamp when the incident was last reviewed.
          example: '2026-08-04T23:58:33Z'
        comment:
          type: string
          description: Comment added during verdict review.
          example: Alert investigation configured detected investigation network network threat.
    EmailAttachment:
      type: object
      properties:
        filename:
          type: string
          description: Attachment filename.
          example: Corporate Policy 38
        content_type:
          type: string
          description: MIME content type of the attachment.
          example: advanced
        size:
          type: integer
          description: Attachment size in bytes.
          example: 438
        has_matches:
          type: boolean
          description: Whether the attachment contained data pattern matches.
          example: false
        match_count:
          type: integer
          description: Number of data pattern matches in the attachment.
          example: 158
        patterns_matched:
          type: array
          items:
            type: string
          description: Names of data patterns that matched in the attachment.
          example: *id002
    EmailRecipient:
      type: object
      properties:
        email:
          type: string
          description: Recipient email address.
          example: security-ops@example.com
        type:
          type: string
          enum:
          - to
          - cc
          - bcc
          description: Recipient type indicating address field.
          example: cc
        delivery_status:
          type: string
          enum:
          - delivered
          - blocked
          - quarantined
          - pending
          description: Delivery status of the message to this recipient.
          example: pending
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code or type.
          example: example-error
        message:
          type: string
          description: Human-readable error message.
          example: Policy network malware on detected configured on incident blocked violation.