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

# List contacts

> Newest first, cursor-paged. Requires `read`.



## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/contacts
openapi: 3.1.0
info:
  title: Sendbaze API
  version: '1.0'
  description: >
    Transactional email and SMS for Africa. Send from your own domain through
    Amazon SES in Cape Town.

    Every send returns an id immediately; delivery is reported by webhook and in
    the dashboard logs.
  contact:
    name: Sendbaze support
    email: support@sendbaze.com
    url: https://www.sendbaze.com
servers:
  - url: https://api.sendbaze.com
security:
  - bearerAuth: []
tags:
  - name: Emails
  - name: Templates
  - name: Domains
  - name: Suppressions
  - name: Webhooks
  - name: SMS
  - name: Contacts
  - name: Senders
  - name: Usage
paths:
  /v1/contacts:
    get:
      tags:
        - Contacts
      summary: List contacts
      description: Newest first, cursor-paged. Requires `read`.
      operationId: listContacts
      parameters:
        - name: q
          in: query
          description: Substring of the email, the phone or an attribute value.
          schema:
            type: string
            maxLength: 254
        - name: optedOut
          in: query
          description: Only contacts opted out of marketing on this channel.
          schema:
            type: string
            enum:
              - email
              - sms
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: A page of contacts
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - nextCursor
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ContactSummary'
                  nextCursor:
                    type:
                      - string
                      - 'null'
components:
  parameters:
    Cursor:
      name: cursor
      in: query
      description: The `nextCursor` of the previous page.
      schema:
        type: string
  schemas:
    ContactSummary:
      type: object
      required:
        - id
        - email
        - phone
        - attributes
        - marketing
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          example: ct_01j9x7k2r4m8q3v5n6b7c8d9e0
        email:
          type:
            - string
            - 'null'
        phone:
          type:
            - string
            - 'null'
        attributes:
          $ref: '#/components/schemas/ContactAttributes'
        marketing:
          type: object
          required:
            - email
            - sms
          properties:
            email:
              $ref: '#/components/schemas/MarketingStatus'
            sms:
              $ref: '#/components/schemas/MarketingStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    ContactAttributes:
      type: object
      description: >-
        Your own flat fields, up to 40 keys of lower-case letters, digits and
        underscores; values up to 500 characters. `first_name` fills
        `{{first_name}}` in sends.
      additionalProperties:
        type: string
        maxLength: 500
      example:
        first_name: Thandi
        city: Pretoria
    MarketingStatus:
      type: object
      required:
        - consented
        - optedOutAt
      properties:
        consented:
          type: boolean
          description: An unrevoked marketing consent exists on this channel.
        optedOutAt:
          type:
            - string
            - 'null'
          format: date-time
          description: Set when the person opted out (STOP
          unsubscribe link: null
          or by hand); marketing is refused.: null
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key from the dashboard. `sk_live_…` sends; `sk_test_…` validates
        and returns ids without sending.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.