> ## Documentation Index > Fetch the complete documentation index at: https://inbound.new/docs/llms.txt > Use this file to discover all available pages before exploring further. # List inbox threads > List email threads (conversations) for your inbox with cursor-based pagination. This is the primary endpoint for building an inbox UI. **What is a Thread?** A thread groups related emails together based on the In-Reply-To and References headers, similar to how Gmail groups conversations. Each thread contains both inbound (received) and outbound (sent) messages. **Use with /mail/threads/:id:** Use this endpoint to list threads, then use `GET /mail/threads/:id` to fetch all messages in a specific thread. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/inbound/openapi.documented.yml get /api/e2/mail/threads openapi: 3.1.0 info: title: Inbound Email API description: >+ # Inbound API The Inbound API allows you to manage email infrastructure programmatically - domains, email addresses, webhooks, and more. ## Authentication All API requests require a Bearer token in the Authorization header: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ https://inbound.new/api/e2/domains ``` ## Base URL ``` https://inbound.new/api/e2 ``` ## Quick Start 1. **Create a domain** - Register your domain with Inbound 2. **Configure DNS** - Add the provided DNS records to your domain 3. **Create an email address** - Set up addresses to receive emails 4. **Create an endpoint** - Configure where emails are delivered (webhook, forwarding, etc.) version: 2.0.0 servers: - url: https://inbound.new description: Production API server security: - bearerAuth: [] tags: - name: Webhooks description: Webhooks sent by Inbound to your configured endpoints when events occur. - name: Emails description: >- Send, list, and manage emails. Supports immediate sending, scheduling, replies, and retry functionality. - name: Mail description: >- Inbox and thread views for received emails. Filter by domain, address, or search. - name: Domains description: >- Manage domains for sending and receiving emails. Domains must be verified via DNS before use. - name: Endpoints description: >- Configure where incoming emails are delivered - webhooks, email forwarding, or custom handlers. - name: Email Addresses description: Create and manage email addresses on your verified domains. - name: Attachments description: Download email attachments using authenticated requests. paths: /api/e2/mail/threads: get: tags: - Inbox summary: List inbox threads description: >- List email threads (conversations) for your inbox with cursor-based pagination. This is the primary endpoint for building an inbox UI. **What is a Thread?** A thread groups related emails together based on the In-Reply-To and References headers, similar to how Gmail groups conversations. Each thread contains both inbound (received) and outbound (sent) messages. **Use with /mail/threads/:id:** Use this endpoint to list threads, then use `GET /mail/threads/:id` to fetch all messages in a specific thread. operationId: getApiE2MailThreads parameters: - name: domain in: query required: false schema: description: >- Filter threads by domain. Accepts domain ID (e.g., 'dom_xxx') or domain name (e.g., 'example.com'). Returns threads where any participant email matches the domain. type: string - name: address in: query required: false schema: description: >- Filter threads by email address. Accepts address ID (e.g., 'addr_xxx') or raw email address (e.g., 'user@example.com'). Returns threads where the address is a participant. type: string - name: limit in: query required: false schema: description: Maximum number of threads to return (1-100). Default is 25. default: '25' type: string - name: cursor in: query required: false schema: description: >- Cursor for pagination. Pass the thread ID from `pagination.next_cursor` of the previous response to get the next page. type: string - name: search in: query required: false schema: description: >- Search query to filter threads by subject or participant emails. Case-insensitive partial match. type: string - name: unread in: query required: false schema: description: >- Filter by unread status. Set to 'true' to only return threads with unread messages. default: 'false' type: string responses: '200': description: Response for status 200 content: application/json: schema: type: object properties: threads: description: >- Array of thread objects matching the query, sorted by last message date (newest first) type: array items: type: object properties: id: description: Unique identifier for the thread type: string root_message_id: description: >- RFC 2822 Message-ID of the first message in the thread type: string normalized_subject: nullable: true anyOf: - description: >- Normalized subject line (stripped of Re:, Fwd:, etc.) used for thread grouping type: string - type: 'null' participant_emails: description: >- Array of all unique email addresses that have participated in this thread type: array items: type: string participant_names: description: >- Array of formatted participant names in the format 'First Last ' or just 'email@domain.com' if no name is available type: array items: type: string message_count: description: >- Total number of messages in the thread (both inbound and outbound) type: number last_message_at: description: >- ISO 8601 timestamp of the most recent message in the thread type: string created_at: description: >- ISO 8601 timestamp when the thread was created (first message received) type: string latest_message: nullable: true anyOf: - type: object properties: id: description: Unique identifier of the message type: string type: description: >- Whether the message was received (inbound) or sent (outbound) anyOf: - const: inbound type: string - const: outbound type: string subject: nullable: true anyOf: - description: Subject line of the message type: string - type: 'null' from_text: description: >- Formatted sender information (name and/or email) type: string text_preview: nullable: true anyOf: - description: >- First 200 characters of the message body as a preview type: string - type: 'null' is_read: description: >- Whether the message has been read (always true for outbound) type: boolean has_attachments: description: Whether the message has any attachments type: boolean date: nullable: true anyOf: - description: >- ISO 8601 timestamp of when the message was sent/received type: string - type: 'null' required: - id - type - from_text - is_read - has_attachments - type: 'null' has_unread: description: Whether the thread has any unread inbound messages type: boolean is_archived: description: Whether the thread has been archived type: boolean unread_count: description: Number of unread messages in the thread type: number required: - id - root_message_id - participant_emails - participant_names - message_count - last_message_at - created_at - has_unread - is_archived pagination: description: Pagination metadata for cursor-based pagination type: object properties: limit: description: Number of results per page type: number has_more: description: >- Whether there are more threads available after this page type: boolean next_cursor: nullable: true anyOf: - description: >- Cursor to pass as the `cursor` parameter to fetch the next page. Null if no more results. type: string - type: 'null' required: - limit - has_more filters: description: Applied filters for this query type: object properties: search: description: Applied search query type: string unread_only: description: Whether filtering for unread threads only type: boolean domain: description: Applied domain filter (resolved domain name) type: string address: description: Applied address filter (resolved email address) type: string required: - threads - pagination - filters '400': description: Response for status 400 content: application/json: schema: type: object properties: error: description: Error message describing what went wrong type: string required: - error '401': description: Response for status 401 content: application/json: schema: type: object properties: error: description: Error message describing what went wrong type: string required: - error '500': description: Response for status 500 content: application/json: schema: type: object properties: error: description: Error message describing what went wrong type: string required: - error x-codeSamples: - lang: JavaScript source: |- import Inbound from 'inboundemail'; const client = new Inbound({ apiKey: process.env['INBOUND_API_KEY'], // This is the default and can be omitted }); const mail = await client.mail.list(); console.log(mail.filters); components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- Your Inbound API key. Include it in the Authorization header as: Bearer ````