openapi: 3.0.3
info:
  title: SparkPost Events DKIM Keys Subaccounts API
  description: Retrieve detailed per-message event data covering deliveries, bounces, clicks, opens, and other engagement events for individual messages.
  version: 1.0.0
  contact:
    name: SparkPost Developer Support
    url: https://developers.sparkpost.com/api/events/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: https://api.sparkpost.com/api/v1
  description: SparkPost Production API
security:
- ApiKeyAuth: []
tags:
- name: Subaccounts
paths:
  /subaccounts:
    post:
      operationId: createSubaccount
      summary: Create a Subaccount
      description: Create a new subaccount with optional API key setup for multi-tenant email deployments.
      tags:
      - Subaccounts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubaccountRequest'
      responses:
        '200':
          description: Subaccount created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubaccountCreateResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      operationId: listSubaccounts
      summary: List Subaccounts
      description: Retrieve a paginated list of all subaccounts with optional filtering.
      tags:
      - Subaccounts
      parameters:
      - name: option
        in: query
        required: false
        description: Filter by feature option (e.g., deliverability)
        schema:
          type: string
          enum:
          - deliverability
      - name: cursor
        in: query
        required: false
        description: Pagination cursor
        schema:
          type: string
      - name: per_page
        in: query
        required: false
        description: Results per page (max 100, default 25)
        schema:
          type: integer
          maximum: 100
          default: 25
      - name: sort_by
        in: query
        required: false
        description: Field to sort by
        schema:
          type: string
          enum:
          - created_at
          - updated_at
          - id
          - name
          default: created_at
      - name: order
        in: query
        required: false
        description: Sort order
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      - name: ip_pool
        in: query
        required: false
        description: Filter by IP pool ID
        schema:
          type: string
      - name: status
        in: query
        required: false
        description: Filter by account status
        schema:
          type: string
          enum:
          - active
          - suspended
          - terminated
      - name: name
        in: query
        required: false
        description: Filter by partial name match
        schema:
          type: string
      - name: ids
        in: query
        required: false
        description: Comma-separated list of subaccount IDs to retrieve
        schema:
          type: string
      responses:
        '200':
          description: Paginated list of subaccounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubaccountsListResponse'
  /subaccounts/summary:
    get:
      operationId: getSubaccountsSummary
      summary: Retrieve Subaccounts Summary
      description: Retrieve the total count of subaccounts.
      tags:
      - Subaccounts
      responses:
        '200':
          description: Subaccounts summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: object
                    properties:
                      total:
                        type: integer
  /subaccounts/{id}:
    get:
      operationId: getSubaccount
      summary: Retrieve a Subaccount
      description: Retrieve details about a specific subaccount by its ID.
      tags:
      - Subaccounts
      parameters:
      - name: id
        in: path
        required: true
        description: Subaccount ID
        schema:
          type: integer
      responses:
        '200':
          description: Subaccount details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubaccountResponse'
    put:
      operationId: updateSubaccount
      summary: Update a Subaccount
      description: Update configuration for an existing subaccount including status and IP pool.
      tags:
      - Subaccounts
      parameters:
      - name: id
        in: path
        required: true
        description: Subaccount ID
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubaccountUpdateRequest'
      responses:
        '200':
          description: Subaccount updated
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    SubaccountResponse:
      type: object
      properties:
        results:
          $ref: '#/components/schemas/SubaccountDetails'
    SubaccountsListResponse:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/SubaccountDetails'
        total_count:
          type: integer
        links:
          type: object
          properties:
            next:
              type: string
    SubaccountUpdateRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 64
        status:
          type: string
          enum:
          - active
          - suspended
          - terminated
        ip_pool:
          type: string
          description: Set to empty string to unassign current IP pool
        options:
          type: object
          properties:
            deliverability:
              type: boolean
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              description:
                type: string
    SubaccountRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          maxLength: 64
          description: Display name for the subaccount
        ip_pool:
          type: string
          description: IP Pool ID for mail deliveries
        setup_api_key:
          type: boolean
          default: true
          description: Whether to create an API key for this subaccount
        key_label:
          type: string
          description: Label for the API key (required if setup_api_key is true)
        key_grants:
          type: array
          items:
            type: string
          description: Permission grants for the API key (required if setup_api_key is true)
        key_valid_ips:
          type: array
          items:
            type: string
          description: IP addresses allowed to use the API key
        options:
          type: object
          properties:
            deliverability:
              type: boolean
              description: Enable deliverability features for this subaccount
    SubaccountCreateResponse:
      type: object
      properties:
        results:
          type: object
          properties:
            subaccount_id:
              type: integer
            key:
              type: string
              description: API key for the subaccount (shown only on creation)
            label:
              type: string
            short_key:
              type: string
    SubaccountDetails:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        status:
          type: string
        compliance_status:
          type: string
        ip_pool:
          type: string
        options:
          type: object
          properties:
            deliverability:
              type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization