> ## 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 contacts

> Returns a paginated list of stored contacts in the mailing list.



## OpenAPI

````yaml get /contacts
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:
  /contacts:
    get:
      tags:
        - Contacts
      summary: Retrieve contacts
      description: Returns a paginated list of stored contacts in the mailing list.
      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 contacts to return per page.
      responses:
        '200':
          description: A paginated list of contacts
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Contact'
                  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: 1023
      security:
        - apiKey: []
components:
  schemas:
    Contact:
      required:
        - email
      type: object
      properties:
        email:
          type: string
          description: The email of the contact.
          example: john@acme.com
        userId:
          type: string
          description: The user id of the contact.
          example: 123456
        name:
          type: string
          description: The full name of the contact
          example: John Doe
        avatarUrl:
          type: string
          description: The avatar url of the contact
          example: https://example.com/profile_pictures/123456
        languageCode:
          type: string
          description: >-
            The primary language language of this contact, represented by a
            language code.
          example: en-US
        hardBouncedAt:
          type: string
          description: >-
            The date when an attempt to send an email to the contact failed with
            a hard bounce, meaning the email address is invalid and no further
            emails will be send to this contact. You can reset this in the
            dashboard to re-enable sending emails to this contact.
          example: '2024-04-23T18:25:43.511Z'
        subscribedToLists:
          type: array
          items:
            type: string
          description: The array of mailing lists the contact is subscribed to.
          example:
            - onboarding
            - newsletter
        customProperties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CustomContactPropertyValue'
          description: The custom properties set for this contact.
          example:
            company: Acme
            age: 35
    CustomContactPropertyValue:
      type: object
      description: >-
        Represents a custom contact property, which can be a string, number,
        boolean, or date.
      oneOf:
        - type: string
          description: A string property.
        - type: number
          format: double
          description: A number property.
        - type: boolean
          description: A boolean property.
        - type: string
          format: date-time
          description: A date property.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````