> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reply.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Filter inbox threads
> _Requires the `inbox:read` scope (or a broader one that includes it)._
Use this endpoint when you need the inbox threads matching specific criteria — a search term, channel, owner, sequence, email or LinkedIn account, contact, category, date range, source, or only those flagged with meeting intent. Every filter field is optional, and an empty body matches the same set as the plain thread listing. Results are paged with the top and skip query parameters.
## OpenAPI
````yaml /api-reference/bundled.yaml post /v3/inbox/threads/filter
openapi: 3.1.0
info:
version: 3.0.0
title: Reply API
description: API for managing email sequences, contacts, and automation workflows
servers:
- url: https://api.reply.io
security:
- bearerAuth: []
tags:
- name: User Account
description: Account information and authentication verification
- name: Accounts
description: Manage accounts (companies/organizations)
- name: AI Prompts
description: >-
Manage the AI prompts used to configure sequence steps, and preview the
output a prompt produces
- name: AI SDR Insights
description: Read AI SDR insights for sequence contacts
- name: AI SDR Intent Signals
description: >-
Read Reply industry IDs and technology slugs used in AI SDR intent-signal
configuration (typeahead)
- name: AI SDR Sequences
description: >-
Manage AI SDR sequences and their AI SDR-specific settings — create, read
settings, partial update, autopilot enable/disable/force-start, approval
mode, generated step types, and playbook/knowledge-base connections
- name: AI SDR Web Search
description: Find contacts via AI-driven web search and review past searches
- name: Attachments
description: >-
Upload file attachments used across email templates, sequence steps, and
direct emails
- name: Account Lists
description: Manage account lists and account membership
- name: Background Jobs
description: >-
Track and cancel asynchronous background operations (e.g., email
validation)
- name: Custom Fields
description: Manage custom contact fields
- name: Direct Outreach
description: >-
Send one-off outreach directly to a contact outside of any sequence —
direct emails and LinkedIn connection requests, messages, InMails, and
voice messages
- name: Contact Blacklist Rules
description: Manage blacklist rules for domains, emails, and email exceptions
- name: Contact Enrichment
description: >-
Enrich contacts with emails, phone numbers, LinkedIn data, and AI-filled
custom fields
- name: Contact Lists
description: Manage contact lists and contact membership
- name: Contacts
description: Manage individual contacts
- name: Email Accounts
description: Manage email accounts used for sending and receiving
- name: Email Templates
description: Manage email templates and template folders
- name: Email Validations
description: Estimate and schedule asynchronous email validation jobs
- name: Holiday Calendars
description: Manage holiday calendars for scheduling
- name: Inbox
description: >-
Manage inbox threads and per-team thread categories — list/filter, read
state, replies, category assignment, and meeting-intent flagging
- name: LinkedIn Accounts
description: Manage LinkedIn accounts for outreach
- name: Live Data
description: >-
Find new contacts via Live Data searches and read typeahead values for the
Live Data / Autopilot filter sidebar
- name: AI SDR Knowledge Bases
description: >-
Manage AI SDR knowledge bases — collections of documents, links, reply
handlers, and reengagement cards that inform the agent's responses
- name: AI SDR Offers
description: >-
Manage AI SDR offers — bundles of company-context inputs (ICP, pain
points, value propositions, etc.) used to personalize outreach
- name: AI SDR Pending Approvals
description: >-
Review, send, regenerate, and provide feedback on AI-generated messages
awaiting human approval
- name: AI SDR Playbooks
description: >-
Manage AI SDR playbooks — tone, voice, and style guides applied during
personalized message generation
- name: Reports
description: >-
Generate and access performance reports across email, calls, tasks,
LinkedIn, and team performance
- name: Schedules
description: Manage email send schedules and timing
- name: Settings
description: Manage team and user settings
- name: Sequence Contacts
description: Manage contacts within sequences
- name: Sequence Email Accounts
description: Manage email accounts linked to sequences
- name: Sequence Folders
description: Organize sequences into folders
- name: Sequence LinkedIn Accounts
description: Manage LinkedIn accounts linked to sequences
- name: AI SDR Sequence Preview
description: >-
Read and regenerate per-contact previews of the messages a sequence will
send, and provide feedback on preview messages
- name: Sequence Steps
description: Manage individual steps in sequences
- name: Sequence Templates
description: Manage sequence templates
- name: Sequences
description: Manage email automation sequences
- name: AI SDR Strategist
description: Trigger AI Strategist runs
- name: Tasks
description: Manage tasks and to-do items
- name: Webhooks
description: Manage webhook subscriptions and inspect delivery history
paths:
/v3/inbox/threads/filter:
post:
tags:
- Inbox
summary: Filter inbox threads
description: >-
_Requires the `inbox:read` scope (or a broader one that includes
it)._
Use this endpoint when you need the inbox threads matching specific
criteria — a search term, channel, owner, sequence, email or LinkedIn
account, contact, category, date range, source, or only those flagged
with meeting intent. Every filter field is optional, and an empty body
matches the same set as the plain thread listing. Results are paged with
the top and skip query parameters.
operationId: FilterInboxThreads
parameters:
- in: query
name: top
schema:
type: integer
minimum: 1
maximum: 1000
- in: query
name: skip
schema:
type: integer
minimum: 0
requestBody:
required: true
content:
application/json:
schema:
type: object
title: Inbox Thread Filter Request
description: >-
Filter criteria for `POST /v3/inbox/threads/filter`. All fields
are optional — omit a field to skip that filter.
properties:
search:
type: string
nullable: true
description: >-
Free-text search across subject, body preview, and contact
identifiers.
ownerUserId:
type: integer
nullable: true
minimum: 1
description: >-
Restrict to threads owned by the given user. The target must
be a member of the caller's team; otherwise the request
fails with 400 `inboxThread.invalidInput`.
sequenceIds:
type: array
nullable: true
items:
type: integer
minimum: 1
emailAccountIds:
type: array
nullable: true
items:
type: integer
format: int64
minimum: 1
linkedInAccountIds:
type: array
nullable: true
items:
type: integer
minimum: 1
contactIds:
type: array
nullable: true
items:
type: integer
minimum: 1
channels:
type: array
nullable: true
items:
type: string
enum:
- email
- linkedIn
description: >-
Restrict to threads on the given channels. `unknown` is
rejected by validation.
categoryIds:
type: array
nullable: true
items:
type: integer
minimum: 1
onlyWithMeetingIntent:
type: boolean
nullable: true
source:
type: string
nullable: true
enum:
- inbox
- sent
- unread
- aiDraft
description: |-
Predefined source bucket:
- `inbox` — all threads with at least one inbound message.
- `sent` — threads where the latest activity is outbound.
- `unread` — only unread threads.
- `aiDraft` — threads with a pending AI-drafted reply.
from:
type: string
format: date-time
nullable: true
to:
type: string
format: date-time
nullable: true
description: >-
Upper bound on `lastActivityDate`. Must be strictly after
`from` when both are supplied.
example:
channels:
- email
onlyWithMeetingIntent: true
from: '2026-04-01T00:00:00Z'
to: '2026-04-30T23:59:59Z'
responses:
'200':
description: Filtered threads page
content:
application/json:
schema:
type: object
required:
- items
- hasMore
properties:
items:
type: array
items:
type: object
title: Inbox Thread List Item
description: >-
Lightweight thread shape returned from list and filter
endpoints — omits the message body history in favour of
a `bodyPreview`.
required:
- id
- channel
- isRead
- lastActivityDate
- isLastMessagePlanned
- contact
- hasMeetingIntent
- status
properties:
id:
type: integer
channel:
type: string
enum:
- unknown
- email
- linkedIn
isRead:
type: boolean
subject:
type: string
nullable: true
description: >-
Subject of the last message in the thread (email
only).
bodyPreview:
type: string
nullable: true
description: Truncated body of the last message in the thread.
lastActivityDate:
type: string
format: date-time
isLastMessagePlanned:
type: boolean
description: >-
True when the last message in the thread is a
scheduled outbound message that has not yet been
sent.
contact:
type: object
title: Inbox Thread Contact
description: >-
Contact party on the other end of an inbox thread.
Two shapes are possible, distinguished by the
`isDeleted` flag:
- **Live contact** (`isDeleted: false`) — `id` and
`ownerId` reference the live contact record;
`fullName`, `email`, `linkedInProfileUrl`, `phone`,
`companyName`, `title` come from the live record
(any may still be `null` if the corresponding field
is unset on the contact, e.g. `email` is `null` for
a LinkedIn-only contact).
- **Deleted contact** (`isDeleted: true`) — the
underlying contact record has been removed, so `id`
and `ownerId` are `null`. The remaining identifying
fields (`fullName`, `email`, `linkedInProfileUrl`,
`phone`, `companyName`, `title`) are populated from
the snapshot stored on the thread when it was
created — typically enough for the user to recognise
*who* the thread was with even though the contact no
longer exists in their workspace.
required:
- isDeleted
properties:
id:
type: integer
nullable: true
description: >-
Contact id. `null` when the contact has been
deleted.
ownerId:
type: integer
nullable: true
description: >-
User id of the contact's owner. `null` when the
contact has been deleted.
fullName:
type: string
nullable: true
description: >-
Display name. May still be populated from the
thread snapshot when the contact has been
deleted.
email:
type: string
nullable: true
description: >-
Contact email address. `null` for LinkedIn-only
contacts.
linkedInProfileUrl:
type: string
nullable: true
description: >-
LinkedIn profile URL. `null` for email-only
contacts.
phone:
type: string
nullable: true
companyName:
type: string
nullable: true
title:
type: string
nullable: true
isDeleted:
type: boolean
description: >-
`true` when the underlying contact record has
been deleted from the workspace. In that case
`id` and `ownerId` are `null` and the remaining
identifying fields reflect the snapshot stored
on the thread when the message arrived; `false`
when the contact is still present and `id` /
`ownerId` reference the live record.
sequence:
type: object
allOf:
- type: object
title: Inbox Thread Sequence
description: >-
Minimal sequence reference attached to an inbox
thread.
required:
- id
- name
properties:
id:
type: integer
name:
type: string
nullable: true
category:
type: object
allOf:
- type: object
title: Inbox Thread Category Reference
description: >-
Minimal category reference embedded in thread
responses.
required:
- id
- name
properties:
id:
type: integer
name:
type: string
nullable: true
hasMeetingIntent:
type: boolean
status:
type: object
title: Inbox Thread Status
description: >-
Aggregated thread state, derived from the latest
message.
required:
- state
properties:
state:
type: string
enum:
- ok
- needsAttention
description: >-
Thread-level status:
- `ok` — nothing requires user attention.
- `needsAttention` — the latest outbound message
failed to send and the thread needs review.
hasMore:
type: boolean
example:
items:
- id: 58217
channel: email
isRead: false
subject: 'Re: Pricing for Q3 rollout'
bodyPreview: Thanks — does Tuesday at 10am work for a quick call?
lastActivityDate: '2026-04-29T14:32:11Z'
isLastMessagePlanned: false
contact:
id: 9821
ownerId: 42
fullName: Daria Kovalenko
email: daria.kovalenko@northwind.example
linkedInProfileUrl: https://www.linkedin.com/in/daria-kovalenko
phone: '+380501234567'
companyName: Northwind Logistics
title: VP of Operations
isDeleted: false
sequence:
id: 314
name: Q3 Outbound — Logistics ICP
category:
id: 7
name: Hot Leads
hasMeetingIntent: true
status:
state: ok
hasMore: false
'400':
description: >-
Body validation failure, or a business-rule rejection (e.g. invalid
pagination, invalid input).
content:
application/problem+json:
schema:
oneOf:
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
errors:
type: array
description: >-
List of field-level validation errors. Always
non-empty when this
envelope is returned. Each entry pins a single
offending field
via JSON Pointer plus a sanitized detail
string.
items:
type: object
title: Validation Error
description: A single field-level validation error.
properties:
pointer:
type: string
description: >-
JSON Pointer (RFC 6901) to the offending
field — e.g.
`/steps/0/subject`.
* An empty string (`""`) means the error
applies to the whole
request body (e.g. body is missing or unparseable).
* For route or query parameter failures
the pointer is the parameter
name (e.g. `id`, `top`).
example: /steps/0/subject
detail:
type: string
description: >-
Sanitized, human-readable explanation of
this field's error. One of a
small set of templates — `"Field is
required."`, `"Value has an
invalid type."`, `"Value has an invalid
format."`, `"Request body is
not valid JSON."`, `"The request body is
required and cannot be
empty."` — or a FluentValidator message
on body endpoints.
example: Field is required.
title: Validation Problem
description: >-
Input-validation error response at 400. Returned when
the request body
fails binding, FluentValidator rules, or when
route/query parameter
attribute validation (`[Range]`, `[Required]`) fails.
Route, query, and
body errors are combined into a single `errors[]`
array — clients should
not assume one error per request.
- example:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /name
detail: Field is required.
- allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned
by middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this
envelope and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the
form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling;
use `detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a
given resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced
error slug.
Emitted for most 4xx responses (business 400, 403,
404, 409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Bad Request
status: 400
detail: Pagination parameters are invalid.
code: sequence.invalidPagination
examples:
validation_failed:
summary: Body validation failure (FluentValidator)
value:
title: Validation failed
status: 400
detail: The request body contains validation errors.
errors:
- pointer: /to
detail: '''to'' must be after ''from''.'
business_invalid_pagination:
summary: Invalid pagination
value:
title: Bad Request
status: 400
detail: Invalid pagination parameters.
code: inboxThread.invalidPagination
'401':
description: >-
Unauthorized. The response body is empty; check the
`WWW-Authenticate` header for the expected scheme.
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- example:
title: Unauthorized
status: 401
detail: Authentication credentials are missing or invalid.
'403':
description: Inbox feature is not available for this user or team.
content:
application/problem+json:
schema:
allOf:
- allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized
(auth middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope
and add additional
fields — see `business-problem.model.yaml` (adds
`code` slug) and
`validation-problem.model.yaml` (adds `errors[]`
array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
- type: object
properties:
code:
type: string
description: >-
Stable, machine-readable error slug in the form
`"."`.
* `resource` is the camelCased domain — e.g.
`sequence`,
`contact`, `inboxThread`, `blacklistDomainRule`.
* `variant` is the camelCased specific failure
mode — e.g.
`notFound`, `forbidden`, `duplicateName`, `globalRuleReadOnly`.
Use `code` for programmatic error handling; use
`detail` for
user-facing messages. Slugs are stable across
server-side enum
reorderings and never change meaning under a given
resource.
pattern: ^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)+$
example: sequence.notFound
title: Business Problem
description: >-
Domain error response carrying a stable, namespaced error
slug.
Emitted for most 4xx responses (business 400, 403, 404,
409, …) and
for 503 when a downstream dependency is unavailable.
- example:
title: Forbidden
status: 403
detail: You do not have permission to access this resource.
code: sequence.forbidden
example:
title: Forbidden
status: 403
detail: Inbox feature is not available for this user.
code: inboxThread.forbidden
'429':
description: Too Many Requests
headers:
Retry-After:
description: Seconds to wait before retrying
schema:
type: integer
minimum: 1
content:
application/problem+json:
schema:
allOf:
- type: object
title: Problem Details
description: >-
Bare RFC 9457 problem-details envelope. Returned by
middleware-level errors
that don't carry domain context: 401 Unauthorized (auth
middleware),
429 Too Many Requests (rate-limit middleware), and
route-level 404 / 405 /
415 (framework middleware).
Business and validation responses extend this envelope and
add additional
fields — see `business-problem.model.yaml` (adds `code`
slug) and
`validation-problem.model.yaml` (adds `errors[]` array).
properties:
title:
type: string
description: Short, human-readable summary of the problem.
status:
type: integer
description: HTTP status code.
minimum: 100
maximum: 599
detail:
type: string
description: >-
Human-readable explanation specific to this
occurrence.
example:
title: Too Many Requests
status: 429
detail: Rate limit exceeded. Retry after 60 seconds.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Authenticate every request with a Bearer token. Pass your Reply API key
in the
`Authorization` header:
```
Authorization: Bearer
```
Get your API key from the Reply dashboard: **Settings → API Key**.
````