openapi: 3.0.3
info:
  title: SparkPost Subaccounts API
  description: Manage subaccounts for multi-tenant or agency deployments, each with isolated sending domains, API keys, suppression lists, and reporting.
  version: 1.0.0
  contact:
    name: SparkPost Developer Support
    url: https://developers.sparkpost.com/api/subaccounts/
  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: []
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:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
  schemas:
    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
    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
    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
    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
    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
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              code:
                type: string
              description:
                type: string