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

# List conversations

> The organization's conversations on one channel, newest first: email threads of its mailboxes (`channel=email`), or LinkedIn chats of its seats (`channel=linkedin`). Narrow them by `folder`, `campaignId`, dates and `search`; an email list by `mailbox` and `repliesOnly`, a LinkedIn list by `accountId`.

For the next page, send the page's `pagination.nextCursor` as `cursor`, with the same filters. Later pages keep the first page's `pageSize`; only a missing `nextCursor` marks the end.

Free. **Scope:** campaigns. Read-only keys may call it.



## OpenAPI

````yaml /openapi.json get /v1/conversations
openapi: 3.1.0
info:
  title: outbound.dev API
  version: v1
  description: Find people and companies, and see what every call costs, with one API key.
servers:
  - url: https://api.outbound.dev
security: []
tags:
  - name: People
    description: >-
      Search people with filters, a saved search or a plain-language query,
      count matches and look up filter values.
  - name: Companies
    description: >-
      Search companies, count matches, name one company by its name, domain or
      LinkedIn page, and list its people.
  - name: Saved searches
    description: Keep a search under a title and run it again, for people or for companies.
  - name: Lists
    description: >-
      Keep people or companies in lists: create and change lists, page through
      their rows, and add or remove people.
  - name: Folders
    description: Group lists of one kind into folders.
  - name: Enrichment
    description: >-
      Find people's work emails and phone numbers: one person, a batch of
      people, or a list.
  - name: Jobs
    description: >-
      Long tasks a call started: their progress, what they produced and what
      they were charged, and stopping them.
  - name: Accounts
    description: >-
      Connect the mailboxes and LinkedIn seats that campaigns and the inbox send
      from, and look after them.
  - name: Campaigns
    description: >-
      Email and LinkedIn campaigns: their steps, the people they enroll, their
      queue of messages, templates, the knowledge hubs and writing styles AI
      steps are written from, the tracking domain their links go through, and
      the lists every campaign leaves out.
  - name: Inbox
    description: >-
      Read and answer the conversations of your mailboxes and LinkedIn seats,
      and send new messages and invitations.
  - name: Account
    description: >-
      The calling key and its organization, its rate limits, and revoking the
      key.
  - name: Billing
    description: The balance, the ledger of every change to it, and the price list.
  - name: Usage and requests
    description: >-
      Calls and spend by day, and the record of every request of the last 30
      days.
paths:
  /v1/conversations:
    get:
      tags:
        - Inbox
      summary: List conversations
      description: >-
        The organization's conversations on one channel, newest first: email
        threads of its mailboxes (`channel=email`), or LinkedIn chats of its
        seats (`channel=linkedin`). Narrow them by `folder`, `campaignId`, dates
        and `search`; an email list by `mailbox` and `repliesOnly`, a LinkedIn
        list by `accountId`.


        For the next page, send the page's `pagination.nextCursor` as `cursor`,
        with the same filters. Later pages keep the first page's `pageSize`;
        only a missing `nextCursor` marks the end.


        Free. **Scope:** campaigns. Read-only keys may call it.
      operationId: getConversations
      parameters:
        - name: channel
          in: query
          required: true
          description: '`email` or `linkedin`.'
          schema:
            type: string
            enum:
              - email
              - linkedin
        - name: pageSize
          in: query
          required: false
          description: Conversations per page.
          schema:
            type: integer
            default: 25
            minimum: 1
            maximum: 100
        - name: cursor
          in: query
          required: false
          description: >-
            The `pagination.nextCursor` of the page before. Later pages keep the
            first page's size.
          schema:
            type: string
            minLength: 1
            maxLength: 200
        - name: folder
          in: query
          required: false
          description: >-
            Email: `inbox` (the default), `sent`, `unread`, `favorite`,
            `archived`, `spam` or `trash`. LinkedIn: `inbox` (the default, every
            chat) or `unread`.
          schema:
            type: string
            enum:
              - inbox
              - sent
              - unread
              - favorite
              - archived
              - spam
              - trash
        - name: campaignId
          in: query
          required: false
          description: Only the conversations of one campaign.
          schema:
            type: string
            minLength: 24
            maxLength: 24
            pattern: ^[0-9a-fA-F]+$
        - name: since
          in: query
          required: false
          description: >-
            Only conversations with a message at or after this ISO 8601
            date-time.
          schema:
            type: string
            format: date-time
        - name: to
          in: query
          required: false
          description: >-
            Only conversations with a message at or before this ISO 8601
            date-time, not before `since`.
          schema:
            type: string
            format: date-time
        - name: search
          in: query
          required: false
          description: >-
            Email: matches names, addresses, the subject and the text. LinkedIn:
            matches the other person's name.
          schema:
            type: string
            minLength: 1
            maxLength: 200
        - name: mailbox
          in: query
          required: false
          description: 'Email only: one mailbox, or up to 20 separated by commas.'
          schema:
            type: string
            minLength: 1
            maxLength: 6420
        - name: repliesOnly
          in: query
          required: false
          description: >-
            Email only: true keeps the conversations where the other side wrote
            back.
          schema:
            type: boolean
        - name: accountId
          in: query
          required: false
          description: 'LinkedIn only: one seat, by its `id`.'
          schema:
            type: string
            minLength: 1
            maxLength: 100
      responses:
        '200':
          description: One page of conversations, newest first.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-Charged-Usd:
              $ref: '#/components/headers/ChargedUsd'
            X-Balance-Usd:
              $ref: '#/components/headers/BalanceUsd'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      description: >-
                        An email thread or a LinkedIn chat. A field without a
                        value is absent.
                      required:
                        - id
                        - channel
                      properties:
                        id:
                          type: string
                          description: The conversation's id, for the same `channel`.
                        channel:
                          type: string
                          enum:
                            - email
                            - linkedin
                        mailbox:
                          type: string
                          description: 'Email: the mailbox the thread is in.'
                        subject:
                          type: string
                          description: Email.
                        participants:
                          type: array
                          description: >-
                            Email: the senders' addresses. LinkedIn: the other
                            side, as `{ name, linkedinUrl }`.
                          items: {}
                        messageCount:
                          type: integer
                          description: Email.
                        unreadCount:
                          type: integer
                        labels:
                          type: array
                          items:
                            type: string
                            enum:
                              - interested
                              - not_interested
                          description: 'Email: the labels its emails carry.'
                        accountId:
                          type: string
                          description: 'LinkedIn: the seat the chat is on.'
                        campaignId:
                          type: string
                          description: 'LinkedIn: the campaign that started the chat.'
                        lastMessage:
                          type: object
                          properties:
                            messageId:
                              type: string
                              description: Email.
                            direction:
                              type: string
                              enum:
                                - sent
                                - received
                              description: Email.
                            from:
                              type: object
                              properties:
                                name:
                                  type: string
                                address:
                                  type: string
                              description: Email.
                            text:
                              type: string
                              description: >-
                                Up to 200 characters, without the quoted
                                history.
                            subject:
                              type: string
                              description: 'LinkedIn: an InMail''s subject.'
                            sentAt:
                              type: string
                              format: date-time
                  pagination:
                    type: object
                    required:
                      - pageSize
                      - total
                    properties:
                      pageSize:
                        type: integer
                      nextCursor:
                        type: string
                        description: >-
                          Send as `cursor` for the next page. Absent on the last
                          page.
                      total:
                        type: integer
                        description: Everything that matches, across every page.
              example:
                data:
                  - id: c210cDptYXlhQGZlcm53YXkuY286MTg5YzQ
                    channel: email
                    mailbox: maya@fernway.co
                    subject: Your Lisbon fleet
                    participants:
                      - maya@fernway.co
                      - ana.costa@example.com
                    messageCount: 2
                    unreadCount: 1
                    labels:
                      - interested
                    lastMessage:
                      messageId: 18f3c2a9b7d41e02
                      direction: received
                      from:
                        name: Ana Costa
                        address: ana.costa@example.com
                      text: Happy to talk on Thursday.
                      sentAt: '2026-11-14T15:20:00.000Z'
                pagination:
                  pageSize: 25
                  total: 1
        '429':
          $ref: '#/components/responses/RateLimited'
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/ServerError'
      security:
        - apiKey: []
components:
  headers:
    RequestId:
      description: The request's id. Quote it when you write to support.
      schema:
        type: string
        example: req_6a1f0c2b9d4e8a7f3c5b2e10
    ChargedUsd:
      description: What this call cost, in US dollars as an exact six-decimal string.
      schema:
        type: string
        example: '0.005000'
    BalanceUsd:
      description: >-
        The organization's balance after this call, in US dollars as an exact
        six-decimal string.
      schema:
        type: string
        example: '9.995000'
    RateLimitLimit:
      description: >-
        The calls allowed in the window of the route's limit with the fewest
        calls left.
      schema:
        type: integer
        example: 20
    RateLimitRemaining:
      description: The calls left in that window.
      schema:
        type: integer
        example: 19
    RateLimitReset:
      description: Seconds until that window resets.
      schema:
        type: integer
        example: 42
    RetryAfter:
      description: Seconds to wait before calling again.
      schema:
        type: integer
        example: 42
  responses:
    RateLimited:
      description: >-
        Too many calls. Wait the seconds in Retry-After, then call again. When
        the limit reached does not say when it resets, such as a mail provider's
        own limit on a mailbox, Retry-After is 60. The RateLimit headers
        describe this API's own limits, so they come only with a 429 one of
        those gave. The body is empty.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
    Error:
      description: The request was refused. The body names the reason in `error.code`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: >-
        Something failed on our side and nothing was charged. Retry with
        backoff; quote X-Request-Id if it persists. The body is empty.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
  schemas:
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - doc_url
          properties:
            code:
              type: string
              description: >-
                Stable and machine-readable: branch on it. It never changes
                meaning.
            message:
              type: string
              description: >-
                A human-readable explanation for logs. It may be reworded at any
                time.
            param:
              type: string
              description: The request field the error is about, when there is one.
            doc_url:
              type: string
              description: The code's entry in the errors reference.
            request_id:
              type: string
              description: >-
                The request's id, as in the X-Request-Id header. Quote it to
                support.
      example:
        error:
          code: insufficient_balance
          message: Your balance cannot cover this call. Add funds and try again.
          doc_url: https://docs.outbound.dev/errors#insufficient_balance
          request_id: req_6a1f0c2b9d4e8a7f3c5b2e10
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        An API key from the console, starting `ob_live_`, sent as
        `Authorization: Bearer <key>`.

````

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