> ## Documentation Index
> Fetch the complete documentation index at: https://ahasend.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List Sub Accounts

> Returns a cursor-paginated list of sub accounts under the parent account. Soft-deleted sub accounts are not included; usage billed for sub accounts deleted during the current period is reported by the usage endpoint's `removed_sub_accounts` aggregate.

<Info>
  **Platform Partner feature:** Sub Accounts is part of our Platform Partner capabilities and is currently in early access. [Contact us](https://ahasend.com/contact) to enable it on your account.
</Info>


## OpenAPI

````yaml openapi.yaml GET /v2/accounts/{account_id}/sub-accounts
openapi: 3.1.0
info:
  title: AhaSend API v2
  description: >
    The AhaSend API v2 allows you to send transactional emails, manage domains,
    webhooks, routes, API keys, and view statistics.


    ## Authentication

    All API requests must be authenticated using a Bearer token in the
    Authorization header:

    ```

    Authorization: Bearer aha-sk-64-CHARACTER-RANDOM-STRING

    ```


    ## Scopes

    API keys have specific scopes that control access to different resources and
    actions:


    ### Message Scopes

    - `messages:send:all` - Send messages from any domain in the account

    - `messages:send:{domain}` - Send messages from a specific domain

    - `messages:cancel:all` - Cancel messages from any domain

    - `messages:cancel:{domain}` - Cancel messages from a specific domain

    - `messages:read:all` - Read messages from any domain

    - `messages:read:{domain}` - Read messages from a specific domain


    ### Domain Scopes

    - `domains:read` - Read all domains

    - `domains:write` - Create and update domains

    - `domains:delete:all` - Delete any domain

    - `domains:delete:{domain}` - Delete a specific domain


    ### Account Scopes

    - `accounts:read` - Read account information

    - `accounts:write` - Update account settings

    - `accounts:billing` - Access billing information

    - `accounts:members:read` - Read account members

    - `accounts:members:add` - Add account members

    - `accounts:members:update` - Update account members

    - `accounts:members:remove` - Remove account members


    ### Webhook Scopes

    - `webhooks:read:all` - Read all webhooks

    - `webhooks:read:{domain}` - Read webhooks for a specific domain

    - `webhooks:write:all` - Create and update webhooks

    - `webhooks:write:{domain}` - Create and update webhooks for a specific
    domain

    - `webhooks:delete:all` - Delete any webhook

    - `webhooks:delete:{domain}` - Delete webhooks for a specific domain


    ### Route Scopes

    - `routes:read:all` - Read all routes

    - `routes:read:{domain}` - Read routes for a specific domain

    - `routes:write:all` - Create and update routes

    - `routes:write:{domain}` - Create and update routes for a specific domain

    - `routes:delete:all` - Delete any route

    - `routes:delete:{domain}` - Delete routes for a specific domain


    ### Suppression Scopes

    - `suppressions:read` - Read suppressions

    - `suppressions:write` - Create suppressions

    - `suppressions:delete` - Delete suppressions

    - `suppressions:wipe` - Delete all suppressions (dangerous)


    ### SMTP Credentials Scopes

    - `smtp-credentials:read:all` - Read all SMTP credentials

    - `smtp-credentials:read:{domain}` - Read SMTP credentials for a specific
    domain

    - `smtp-credentials:write:all` - Create SMTP credentials

    - `smtp-credentials:write:{domain}` - Create SMTP credentials for a specific
    domain

    - `smtp-credentials:delete:all` - Delete any SMTP credentials

    - `smtp-credentials:delete:{domain}` - Delete SMTP credentials for a
    specific domain


    ### Statistics Scopes

    - `statistics-transactional:read:all` - Read all transactional statistics

    - `statistics-transactional:read:{domain}` - Read transactional statistics
    for a specific domain


    ### API Key Scopes

    - `api-keys:read` - Read API keys

    - `api-keys:write` - Create and update API keys

    - `api-keys:delete` - Delete API keys


    ### Sub-Account Scopes

    - `sub-accounts:read` - List and read sub accounts under the parent

    - `sub-accounts:write` - Create and update sub accounts

    - `sub-accounts:delete` - Soft-delete sub accounts

    - `sub-accounts:suspend` - Suspend and unsuspend sub accounts

    - `sub-accounts:usage` - Read per-sub-account usage and allocated cost

    - `sub-account-api-keys:read` - List and read API keys owned by sub accounts

    - `sub-account-api-keys:write` - Create and update API keys owned by sub
    accounts

    - `sub-account-api-keys:delete` - Delete API keys owned by sub accounts


    ## Rate Limiting

    - General API endpoints: 100 requests per second, 200 burst

    - Statistics endpoints: 1 request per second, 1 burst


    ## Pagination

    List endpoints use cursor-based pagination with the following parameters:

    - `limit`: Maximum number of items to return (default: 100, max: 100)

    - `cursor`: Pagination cursor for the next page


    ## Time Formats

    All timestamps must be in RFC3339 format, e.g., `2023-12-25T10:30:00Z`


    ## Idempotency

    POST requests support idempotency through the optional `Idempotency-Key`
    header. When provided:

    - The same request can be safely retried multiple times

    - Duplicate requests return the same response with `Idempotent-Replayed:
    true`

    - In-progress requests return HTTP 409 with `Idempotent-Replayed: false` and
    a `Retry-After` header

    - Completed outcomes (2xx and 4xx) are stored and replayed; server errors
    (5xx) are not stored, so retrying with the same key re-executes the request

    - Reusing a key with a different request payload, or against a different
    endpoint or resource, returns HTTP 422

    - Idempotency keys for non-secret responses expire after 24 hours

    - API-key create endpoints return a one-time `secret_key`; their encrypted
    idempotency replay responses expire after 5 minutes and replay the same
    `secret_key` during that window


    ## IP Allow Lists

    Each API key can carry an `ip_allow_list`: a set of source IPs that restrict
    where the key may authenticate from.

    - Entries are CIDR blocks (e.g. `203.0.113.0/24`) or bare IPv4/IPv6
    addresses (stored as a `/32` or `/128`). They are canonicalized and
    de-duplicated; the allow-all prefixes `0.0.0.0/0` and `::/0` are rejected,
    and at most 100 entries are allowed after de-duplication (a longer list is
    rejected with HTTP 400).

    - An empty list (the default) places no restriction.

    - When the list is non-empty, any authenticated request whose client IP is
    not covered by an entry is rejected with HTTP 403 on every v2 endpoint,
    regardless of the key's scopes.

    - Manage the list with the `ip_allow_list` field on the API-key create and
    update endpoints (including the sub-account API-key endpoints).

    - When a key updates its own `ip_allow_list` to a value that excludes the
    caller's current IP, the update is rejected with HTTP 409 to prevent
    self-lockout. Updating a sub-account key from a parent key has no such
    guard.
  version: 2.0.0
  contact:
    email: support@ahasend.com
  license:
    name: MIT
    identifier: MIT
servers:
  - url: https://api.ahasend.com
    description: Production server
security:
  - BearerAuth: []
tags:
  - name: Utility
    description: Utility endpoints for health checks and diagnostics
  - name: API Keys
    description: Manage API keys for authentication and access control
  - name: Domains
    description: Manage sending domains
  - name: Messages
    description: Send and manage transactional messages
  - name: Accounts
    description: Manage account settings and members
  - name: Suppressions
    description: Manage email suppressions
  - name: Routes
    description: Manage inbound email routing
  - name: Webhooks
    description: Manage webhook notifications
  - name: SMTP Credentials
    description: Manage SMTP authentication credentials
  - name: Statistics
    description: Access transactional email statistics
  - name: Message Events
    description: Webhooks for outbound message delivery events
  - name: Suppression Events
    description: Webhooks for suppression list changes
  - name: Domain Events
    description: Webhooks for domain configuration issues
  - name: Route Events
    description: Webhooks for inbound email routing
paths:
  /v2/accounts/{account_id}/sub-accounts:
    get:
      tags:
        - Sub Accounts
      summary: List Sub Accounts
      description: >-
        Returns a cursor-paginated list of sub accounts under the parent
        account. Soft-deleted sub accounts are not included; usage billed for
        sub accounts deleted during the current period is reported by the usage
        endpoint's `removed_sub_accounts` aggregate.
      operationId: listSubAccounts
      parameters:
        - name: account_id
          in: path
          required: true
          description: Parent account ID
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Maximum number of items to return (1-100)
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
        - name: after
          in: query
          description: >-
            Pagination cursor for the next page. Provide the value from
            `next_cursor` in the response.
          schema:
            type: string
        - name: before
          in: query
          description: >-
            Pagination cursor for the previous page. Provide the value from
            `previous_cursor` in the response.
          schema:
            type: string
      responses:
        '200':
          description: List of sub accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSubAccountsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Parent account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth:
            - sub-accounts:read
      x-code-samples:
        - lang: go
          label: AhaSend Go SDK
          source: |
            package main

            import (
              "context"
              "fmt"
              "log"

              "github.com/AhaSend/ahasend-go"
              "github.com/AhaSend/ahasend-go/api"
              "github.com/AhaSend/ahasend-go/models/common"
              "github.com/google/uuid"
            )

            func main() {
              // Create API client with authentication
              client := api.NewAPIClient(
                api.WithAPIKey("aha-sk-your-64-character-key"),
              )

              accountID := uuid.New()

              // Create context for the API call
              ctx := context.Background()

              // List sub accounts (limit results to 50 per page)
              response, httpResp, err := client.SubAccountsAPI.ListSubAccounts(ctx, accountID, &common.PaginationParams{Limit: ahasend.Int32(50)})
              if err != nil {
                log.Fatalf("Error listing sub accounts: %v", err)
              }

              if httpResp.StatusCode == 200 {
                fmt.Printf("✅ Sub accounts listed! Status: %d\n", httpResp.StatusCode)
                fmt.Printf("Found %d sub accounts\n", len(response.Data))
                for _, sub := range response.Data {
                  fmt.Printf("- ID: %s, Name: %s, Status: %s\n", sub.ID, sub.Name, sub.Status)
                }
              } else {
                fmt.Printf("❌ Unexpected status code: %d\n", httpResp.StatusCode)
              }
            }
components:
  schemas:
    PaginatedSubAccountsResponse:
      type: object
      required:
        - object
        - data
        - pagination
      properties:
        object:
          type: string
          enum:
            - list
          description: Object type identifier
        data:
          type: array
          items:
            $ref: '#/components/schemas/SubAccount'
          description: Array of sub accounts
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
    ErrorResponse:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Error description
      example:
        message: Error message
    SubAccount:
      type: object
      required:
        - object
        - id
        - parent_account_id
        - name
        - website
        - status
        - monthly_credit
        - created_at
        - domain_count
        - member_count
        - last_activity_at
      properties:
        object:
          type: string
          enum:
            - sub_account
          description: Object type identifier
        id:
          type: string
          format: uuid
          description: Unique identifier for the sub account
        parent_account_id:
          type: string
          format: uuid
          description: Parent account ID
        created_at:
          type: string
          format: date-time
          description: When the sub account was created
        name:
          type: string
          description: Sub account name
        website:
          type: string
          format: fqdn
          maxLength: 255
          description: Account website domain
        status:
          type: string
          enum:
            - active
            - suspended
            - parent-suspended
            - deleted
          description: Current sub-account status
        monthly_credit:
          type: integer
          format: int64
          minimum: 0
          description: Optional monthly cap; 0 means no cap
        domain_count:
          type: integer
          format: int64
          minimum: 0
          description: Number of domains owned by the sub account
        member_count:
          type: integer
          format: int64
          minimum: 0
          description: Number of direct members on the sub account
        last_activity_at:
          type: string
          format: date-time
          nullable: true
          description: Last recorded sub-account email activity
      example:
        object: sub_account
        id: 2f3c5d2a-9ef8-4c91-a5f4-79990c8c1d3a
        parent_account_id: 9d0cf9d0-4f5e-4674-bcf1-8ec39968b6e1
        name: Acme Subsidiary
        website: acme.example.com
        status: active
        monthly_credit: 0
        created_at: '2024-01-01T00:00:00Z'
        domain_count: 2
        member_count: 3
        last_activity_at: '2024-01-15T12:00:00Z'
    PaginationInfo:
      type: object
      required:
        - has_more
      properties:
        has_more:
          type: boolean
          description: Whether more items exist after the last item of this page
        next_cursor:
          type: string
          description: Pass as `after` to fetch the next page
        previous_cursor:
          type: string
          description: >-
            Pass as `before` to fetch the previous page; absent on a `before`
            page when the start of the list has been reached
      example:
        has_more: true
        next_cursor: eyJpZCI6MTIzNH0=
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: aha-sk-64-CHARACTER-RANDOM-STRING
      description: API key for authentication

````