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

# List subscribers

> Paginated list with optional status filter.

<Warning>
  Invalid `status` values return **400 Bad Request** with a descriptive message.
</Warning>


## OpenAPI

````yaml openapi.json GET /subscribers
openapi: 3.1.0
info:
  title: Newsletter Public API V1
  description: >-
    Create, list, update and unsubscribe newsletter subscribers from external
    integrations.
  version: 1.0.0
servers:
  - url: https://app.letterbucket.com/api/v1
    description: Production
security:
  - bearerAuth: []
paths:
  /subscribers:
    get:
      tags:
        - Subscribers
      summary: List subscribers
      description: Paginated list of subscribers, with an optional status filter.
      operationId: listSubscribers
      parameters:
        - name: page
          in: query
          required: false
          description: Page number (1-based).
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          required: false
          description: Items per page. Maximum 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: status
          in: query
          required: false
          description: Filter by subscriber status.
          schema:
            type: string
            enum:
              - active
              - pending
              - unsubscribed
      responses:
        '200':
          description: A paginated list of subscribers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberListResponse'
              example:
                success: true
                data:
                  - id: 019756c2-7f3a-7c2e-9b1d-2a4e6f8c0d11
                    email: user@example.com
                    name: John Doe
                    status: active
                    created_at: '2026-06-11T17:00:00+00:00'
                pagination:
                  page: 1
                  limit: 50
                  total: 320
                  pages: 7
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    SubscriberListResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/Subscriber'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Subscriber:
      type: object
      properties:
        id:
          type: string
          format: uuid
        email:
          type: string
          format: email
        name:
          type: string
          nullable: true
        status:
          type: string
          enum:
            - active
            - pending
            - unsubscribed
        created_at:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total:
          type: integer
        pages:
          type: integer
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        code:
          type: string
          description: Machine-readable error code.
        message:
          type: string
          description: Human-readable description.
        errors:
          type: object
          additionalProperties: true
          description: Optional field-level errors.
  responses:
    BadRequest:
      description: Malformed request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: validation_error
            message: The request contains invalid data.
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: unauthorized
            message: Invalid API key.
    Forbidden:
      description: API access disabled for your plan.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: api_access_disabled
            message: API access is not enabled.
    RateLimited:
      description: Rate limit exceeded or temporary lockout.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            code: rate_limit_exceeded
            message: Too many requests. Please try again later.
            errors:
              retry_after: 42
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key, sent as `Authorization: Bearer sk_...`.'

````