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

# Retrieve mailing lists

> Returns paginated mailing lists contacts can subscribe to.



## OpenAPI

````yaml get /lists
openapi: 3.0.3
info:
  title: IndiePitcher OpenAPI Spec
  description: >-
    ## Welcome


    IndiePitcher REST API allows you to send emails, manage your contacts, and
    generate portal session to manage user's contact lists.


    Please note that most destructive operations are currently not supported
    through the REST API for sesucurity reasons. Please use the [IndiePitcher
    dashboard](https://app.indiepitcher.com).


    ## Base URL

    All requests contain the following base URL:

    ```

    https://api.indiepitcher.com/v1

    ```


    ## Authentication


    - Create a free account at [IndiePitcher](https://app.indiepitcher.com) to
    get your API key. API keys are tied to a project.

    - After you've generated your API key you can use it to authenticate your
    requests by including it in the `Authorization` header.


    ```http

    Authorization: Bearer sc_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

    ```


    ## SDKs


    SDKs are available for the following languages:

    - [Node.js](https://github.com/IndiePitcher/indiepitcher-node)

    - [Swift](https://github.com/IndiePitcher/indiepitcher-swift) (server-side
    usage only)


    ## Rate Limits


    Rate limits are applied to all requests to the IndiePitcher API. The rate
    limits are as follows:

    - **10 requests per second across API keys tied to a project.**


    After reaching the rate limit, you will receive a `429 Too Many Requests`
    response. The rate limit will reset after 1 second. We recommend using
    endpoints that support batch operations to reduce the number of requests
    made.


    ## Quick Start Guide

    ### Send a simple email


    ```bash

    curl --request POST \
      --url https://api.indiepitcher.com/v1/email/transactional \
      --header 'Authorization: Bearer <token>' \
      --header 'Content-Type: application/json' \
      --data '{
        "to": "john@acme.com",
        "subject": "You have been invited to IndiePitcher",
        "body": "This is a sample body that supports **markdown**. Plain html is also supported.",
        "bodyFormat": "markdown"
      }'
    ```
  version: 1.2.0
  termsOfService: http://indiepitcher.com/terms
  contact:
    email: petr@indiepitcher.com
servers:
  - url: https://api.indiepitcher.com/v1
security: []
tags:
  - name: Email
  - name: Contacts
  - name: Mailing Lists
externalDocs:
  description: Find out more about IndiePitcher
  url: http://docs.indiepitcher.com
paths:
  /lists:
    get:
      tags:
        - Mailing Lists
      summary: Retrieve mailing lists
      description: Returns paginated mailing lists contacts can subscribe to.
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          required: false
          description: Page to fetch, the first page has index 1.
        - in: query
          name: per
          schema:
            type: integer
            default: 10
          required: false
          description: How many lists to return per page.
      responses:
        '200':
          description: A paginated list of mailing lists
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/MailingList'
                  metadata:
                    type: object
                    properties:
                      page:
                        type: integer
                        description: The current page number.
                        example: 1
                      per:
                        type: integer
                        description: The number of contacts per page.
                        example: 10
                      total:
                        type: integer
                        description: The total number of contacts.
                        example: 20
      security:
        - apiKey: []
components:
  schemas:
    MailingList:
      type: object
      properties:
        name:
          type: string
          description: >-
            The unique name of the mailing list meant to be used by the public
            API. Not intended to be shown to the end users, that's what `title`
            is for.
          example: newsletter
        title:
          type: string
          description: A human-readable name of the mailing list.
          example: Newsletter
        numSubscribers:
          type: integer
          description: The number of contacts subscribed to this list.
          example: 1032
      required:
        - name
        - title
        - numSubscribers
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````