# Add accounts to an account list
Source: https://docs.reply.io/api-reference/account-lists/add-accounts-to-an-account-list
/api-reference/bundled.yaml post /v3/contact-account-lists/{id}/add-accounts
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Add accounts to a list while keeping their other list memberships. Up to 1000 ids per call. Use move-accounts to make it their only list.
# Create an account list
Source: https://docs.reply.io/api-reference/account-lists/create-an-account-list
/api-reference/bundled.yaml post /v3/contact-account-lists
_Requires the `contacts:write` scope (or a broader one that includes it)._
Create an account list to group companies under. The name must be 3 to 128 characters and unique within your team.
# Delete an account list
Source: https://docs.reply.io/api-reference/account-lists/delete-an-account-list
/api-reference/bundled.yaml delete /v3/contact-account-lists/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Delete an account list by id. The accounts stay in Reply and keep their other lists — only membership in this list goes away.
# Get an account list
Source: https://docs.reply.io/api-reference/account-lists/get-an-account-list
/api-reference/bundled.yaml get /v3/contact-account-lists/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get one account list by id, including its name. Account lists are team-wide, so you can fetch any list your team owns.
# List account lists
Source: https://docs.reply.io/api-reference/account-lists/list-account-lists
/api-reference/bundled.yaml get /v3/contact-account-lists
_Requires the `contacts:read` scope (or a broader one that includes it)._
Browse your team's account lists, yours first. Lists are shared team-wide. Paged with the top and skip query parameters.
# Move accounts to an account list
Source: https://docs.reply.io/api-reference/account-lists/move-accounts-to-an-account-list
/api-reference/bundled.yaml post /v3/contact-account-lists/{id}/move-accounts
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Move accounts into a list and out of every other list. Up to 1000 ids per call. Use add-accounts to keep their memberships.
# Update an account list
Source: https://docs.reply.io/api-reference/account-lists/update-an-account-list
/api-reference/bundled.yaml put /v3/contact-account-lists/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Rename an account list. The name is all you can change here, and it must be 3 to 128 characters and unique in your team.
# Add a note to an account
Source: https://docs.reply.io/api-reference/accounts/add-a-note-to-an-account
/api-reference/bundled.yaml post /v3/contact-accounts/{id}/notes
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Record company-level context on an account — CRM facts, funding news, research — so your team and later agent runs can read it back. Every call appends a new note; existing notes are never changed. Returns the stored note with its id.
# Bulk add contacts to an account
Source: https://docs.reply.io/api-reference/accounts/bulk-add-contacts-to-an-account
/api-reference/bundled.yaml post /v3/contact-accounts/{id}/contact-links/bulk
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Link up to 1000 contacts to an account in one call. A contact belongs to one account, so any already linked elsewhere is moved.
# Bulk create accounts
Source: https://docs.reply.io/api-reference/accounts/bulk-create-accounts
/api-reference/bundled.yaml post /v3/contact-accounts/bulk
_Requires the `contacts:write` scope (or a broader one that includes it)._
Create up to 100 accounts in one call. If any item fails validation the whole request is rejected before anything is created. A `customFields` entry that does not resolve or does not fit its field type fails only its own item; the other items are still created. The response is an array with one entry per submitted item, in the order you sent them, carrying either the id of the created account or an error with details. An item whose name matches an account you already have is reported as an error instead of creating a duplicate, and its id is the id of that existing account.
# Bulk delete accounts
Source: https://docs.reply.io/api-reference/accounts/bulk-delete-accounts
/api-reference/bundled.yaml post /v3/contact-accounts/bulk-delete
_Requires the `contacts:write` scope (or a broader one that includes it)._
Delete up to 1000 accounts in one call. The ones you may delete go through; the response lists only the ids that did not.
# Bulk remove contacts from an account
Source: https://docs.reply.io/api-reference/accounts/bulk-remove-contacts-from-an-account
/api-reference/bundled.yaml post /v3/contact-accounts/{id}/contact-links/bulk-delete
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Unlink up to 1000 contacts from an account without deleting them. Each one loses the company details it inherited.
# Create an account
Source: https://docs.reply.io/api-reference/accounts/create-an-account
/api-reference/bundled.yaml post /v3/contact-accounts
**Breaking change from early November 2026.** `linkedProspectsCount` in the response is now `contactsCount`.
_Requires the `contacts:write` scope (or a broader one that includes it)._
Register a company as an account that contacts can link to. Only name is required; every other company field is optional.
# Delete an account
Source: https://docs.reply.io/api-reference/accounts/delete-an-account
/api-reference/bundled.yaml delete /v3/contact-accounts/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Delete one account by id. Its linked contacts are kept and simply left without an account. Use bulk-delete for several.
# Filter accounts
Source: https://docs.reply.io/api-reference/accounts/filter-accounts
/api-reference/bundled.yaml post /v3/contact-accounts/filter
**Breaking change from early November 2026.** Send `conditions` instead of `filters`; a body with `filters` returns 400. `linkedProspectsCount` is now `contactsCount`, in the response and as a `sortBy` value.
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get a narrower set of accounts than plain listing. Search by name or domain, scope to one list, and add up to 20 conditions.
Conditions take the same shape as the contacts filter, joined with AND, one condition per field. `GET /v3/contact-accounts/filter/fields` lists the fields your workspace accepts, with each field's operators, value types and allowed values. An `or` list is accepted when every branch uses `equals` (same as `in`) or every branch uses `contains` (same as `containsAny`); an `and` list takes at most one `in` or `notIn` branch. Stages are matched by name, `ownerUserId` takes user ids, and dates are compared in UTC.
Field names, operators and enum values are matched case-insensitively.
# Get a note of an account
Source: https://docs.reply.io/api-reference/accounts/get-a-note-of-an-account
/api-reference/bundled.yaml get /v3/contact-accounts/{id}/notes/{note_id}
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `contacts:read` scope (or a broader one that includes it)._
Read one note recorded on an account by its id. The note must belong to the account in the path; a note id from another account is not found.
# Get an account
Source: https://docs.reply.io/api-reference/accounts/get-an-account
/api-reference/bundled.yaml get /v3/contact-accounts/{id}
**Breaking change from early November 2026.** `linkedProspectsCount` in the response is now `contactsCount`.
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get one account by id: company details, owner, stage, linked contact count, and the mail provider behind its domain.
# List account filter fields
Source: https://docs.reply.io/api-reference/accounts/list-account-filter-fields
/api-reference/bundled.yaml get /v3/contact-accounts/filter/fields
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `contacts:read` scope (or a broader one that includes it)._
List the fields `POST /v3/contact-accounts/filter` accepts in your workspace, with each field's operators, value types and allowed values. Stage names and custom fields are your workspace's own.
# List accounts
Source: https://docs.reply.io/api-reference/accounts/list-accounts
/api-reference/bundled.yaml get /v3/contact-accounts
**Breaking change from early November 2026.** `linkedProspectsCount` in the response is now `contactsCount`. `sort_by` takes an account field such as `name`, `createdDate` or `contactsCount`, and `sort_direction` takes `asc` or `desc`; any other value, `linkedProspectsCount` included, returns 400.
_Requires the `contacts:read` scope (or a broader one that includes it)._
Browse the accounts you can see — the companies your contacts belong to. Paged with top and skip, with an optional search.
# List contacts for an account
Source: https://docs.reply.io/api-reference/accounts/list-contacts-for-an-account
/api-reference/bundled.yaml get /v3/contact-accounts/{id}/contacts
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the contacts currently linked to an account, paged with top and skip. Each entry carries the email, name, and job title.
# List notes for an account
Source: https://docs.reply.io/api-reference/accounts/list-notes-for-an-account
/api-reference/bundled.yaml get /v3/contact-accounts/{id}/notes
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `contacts:read` scope (or a broader one that includes it)._
Read back the notes recorded on an account, newest first, paged with top and skip. Each note carries its id, text, author and timestamp, so company-level context written by your team or by an external agent can be retrieved later.
# Update account owner
Source: https://docs.reply.io/api-reference/accounts/update-account-owner
/api-reference/bundled.yaml put /v3/contact-accounts/{id}/owner
**Breaking change from early November 2026.** `linkedProspectsCount` in the response is now `contactsCount`.
_Requires the `contacts:write` scope (or a broader one that includes it)._
Hand an account to another member of your team by user id. Nothing else changes, and the account comes back with its new owner.
# Update an account
Source: https://docs.reply.io/api-reference/accounts/update-an-account
/api-reference/bundled.yaml put /v3/contact-accounts/{id}
**Breaking change from early November 2026.** `linkedProspectsCount` in the response is now `contactsCount`.
_Requires the `contacts:write` scope (or a broader one that includes it)._
Replace an account's details in full. Name and ownerUserId are required, and any optional field you leave out is cleared. `customFields` is the exception: the values you send are written, the values you leave out stay as they are.
# Authentication
Source: https://docs.reply.io/api-reference/authentication
Authenticate Reply API requests with a Bearer token. How to create an API key, send it, check it with /v3/whoami, and handle 401 errors.
The Reply API uses Bearer token authentication. Every request must include your API key in the `Authorization` header.
## Get your API key
**1. Sign in**
Sign in to your [Reply.io dashboard](https://run.reply.io).
**2. Open API key settings**
Go to **Settings → API Key**.
**3. Create or copy a key**
Create a new API key or copy an existing one. Treat your API key like a password.
## Authenticate a request
Include your API key as a Bearer token:
```http theme={null}
GET /v3/whoami HTTP/1.1
Host: api.reply.io
Authorization: Bearer YOUR_API_KEY
```
### curl example
```bash theme={null}
curl https://api.reply.io/v3/whoami \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Verify your setup
Call `/v3/whoami` to verify that your API key works. A successful response returns information about the authenticated user:
```json theme={null}
{ "userId": 12345 }
```
## Unauthorized response
If the `Authorization` header is missing, invalid, or contains a revoked API key, the API returns `401 Unauthorized` with an empty response body.
The response includes a `WWW-Authenticate` header:
```text theme={null}
HTTP/1.1 401 Unauthorized
Content-Length: 0
WWW-Authenticate: Bearer
```
Do not expect a JSON error response. Use the status code and headers to handle authentication failures.
> [!NOTE]
>
> This empty-body `401` covers **key** failures — a missing, malformed, or revoked key. A request that presents a valid Team or Organization key but cannot resolve an acting user is different: it returns an `application/problem+json` body with a `code` (see [Organization API key → Rejection responses](#rejection-responses)).
## Scopes
Every API key is granted a set of **scopes**. A scope is a permission such as `contacts:read` that controls which endpoints the key can call. Each endpoint requires a single **minimal scope**, shown as a small note near the top of that endpoint's reference description (below any New or Coming soon notice) — for example:
*Requires the `contacts:read` scope (or a broader one that includes it).*
Endpoints that need no particular permission say **No scope required** instead — any valid API key can call them (for example, `GET /v3/whoami`).
Scopes are configured **per API key** in **Settings → API Key**. Grant a key only the scopes its integration needs.
### Scope format
A scope is written as `domain:verb`:
* **`domain`** — the area of the API the permission applies to (for example `contacts`, `sequences`, `inbox`).
* **`verb`** — the level of access within that domain:
* **`read`** — read data.
* **`write`** — create, update, or delete data.
* **`operate`** — trigger runtime actions (for example, push a contact to a sequence, start or pause a sequence, or reply to an inbox thread).
### How a key satisfies a required scope
A key can hold a required scope directly, or hold a **broader** scope that includes it:
* **`write` and `operate` each also satisfy a `read` requirement** — a key that can write or operate in a domain can also read in that domain. (`write` and `operate` are independent of each other; neither one includes the other.)
* A **verb wildcard** `domain:*` satisfies any verb in that domain — for example, `contacts:*` satisfies `contacts:read`, `contacts:write`, and `contacts:operate`.
* The **global wildcard** `*:*` satisfies every scope except `teams:write`, which a key must be granted by name (`teams:write` or `teams:*`).
For example, an endpoint that requires `contacts:read` can be called by a key granted any of `contacts:read`, `contacts:write`, `contacts:operate`, `contacts:*`, or `*:*`.
### Available scopes
| Domain | Scopes | Covers |
| - | - | - |
| `settings` | `settings:read`, `settings:write` | Read and modify account settings. |
| `contacts` | `contacts:read`, `contacts:write`, `contacts:operate` | Read contacts, accounts, and related data; create/update/delete them; and trigger contact-level runtime actions (push to sequence, enrich, etc.). |
| `sequences` | `sequences:read`, `sequences:write`, `sequences:operate` | Read sequences, steps, variants, and templates; create/update/delete them; and start, pause, or resume running sequences. |
| `channels` | `channels:read`, `channels:write`, `channels:operate` | Read connected email and LinkedIn channels, manage their configuration, and connect/disconnect/re-authorize them. |
| `inbox` | `inbox:read`, `inbox:write`, `inbox:operate` | Read inbox threads, messages, and categories; manage inbox configuration; and reply, mark, or categorize threads. |
| `tasks` | `tasks:read`, `tasks:write`, `tasks:operate` | Read tasks, create/update/delete them, and complete or execute them. |
| `reporting` | `reporting:read` | Read reporting data. **Read-only** — there is no `write` or `operate` verb. |
| `webhooks` | `webhooks:read`, `webhooks:write`, `webhooks:operate` | Read webhook subscriptions and deliveries, manage subscriptions, and test/enable/disable them. |
| `ai-sdr` | `ai-sdr:read`, `ai-sdr:write`, `ai-sdr:operate` | Read AI-SDR campaigns and configuration, manage them, and run/stop/manage their runtime state. |
| `other` | `other:read`, `other:write`, `other:operate` | Read, manage, or trigger miscellaneous resources not covered by a domain-specific scope (background jobs, etc.). |
| `teams` | `teams:write` | Add existing users of your organization to its teams. **Write-only** — there is no `read` or `operate` verb. **Not included in `*:*`**: switch on **Teams** for the key. |
A separate `legacy:use` scope governs the older, non-V3 API and does not apply to the V3 endpoints documented here.
## Special API keys
In addition to user API keys, Reply supports two centralized authentication methods:
* **Team keys** for a single team/workspace
* **Organization API keys** for all team/workspaces in an organization
### Team key — team level
A Team key provides team/workspace-wide access.
Unlike a user API key, which always acts as a single user, a Team key can make requests as any user in the team/workspace.
Common use cases include:
* Team-wide automation
* Cross-user reporting
* Bulk operations
#### Permissions and access control
* Only the team/workspace owner can generate and view the Team key.
* The key must be created manually.
* A Team key is unique to its team/workspace.
For a credential that spans every team/workspace in an organization, see [Organization API key](#organization-api-key-—-organization-level) below.
#### Acting on behalf of a user
Use one of the following headers:
* `X-User-Id`
* `X-User-Email`
> [!NOTE]
>
> You only need one header.
#### Behavior and permission model
Team keys use the same permission model as user API keys.
| Request | Behavior |
| - | - |
| Team key only | Acts as the team/workspace owner |
| Team key + `X-User-Id` | Acts as the specified user (by ID) |
| Team key + `X-User-Email` | Acts as the specified user (by email) |
In all cases, the permissions of the resolved user are applied.
#### Important notes
* If an impersonation header is provided, the request runs with that user's permissions.
* If no impersonation header is provided, the request runs with the team/workspace owner's permissions.
* A Team key does not grant permissions beyond those of the resolved user.
### Organization API key — organization level
An **Organization API** key provides centralized access across every team/workspace in an organization.
Unlike a Team key, which is limited to a single team/workspace, an Organization API key can act on behalf of users across all team/workspaces owned by the organization.
#### Availability
* Organization-scoped
* Works across all team/workspaces in the organization
* Multiple keys can be created
* Keys can be named, revoked, and rotated independently
#### Permissions and access control
By default, Organization Owners can create, view, and revoke organization API keys.
Other organization users can be granted role with permission 'Manage organization API keys' to manage organization API keys.
Keys are managed in: **Settings → API keys**
#### Acting on behalf of a user
Organization API keys always require impersonation.
Use one of the following:
* `X-USER-ID`
* `X-User-Email` together with `X-TEAM-ID`
If no impersonation header is provided, the request is rejected.
If `X-User-Email` is provided without `X-TEAM-ID`, the request is rejected.
Example:
```http theme={null}
GET /v3/whoami HTTP/1.1
Host: api.reply.io
Authorization: Bearer YOUR_ORG_API_KEY
X-USER-ID: 12345
```
#### Behavior and permission model
| Request | Behavior |
| - | - |
| Organization key + `X-USER-ID` | Acts as the user with that ID |
| Organization key + `X-User-Email` + `X-TEAM-ID` | Acts as the user with that email in the given team/workspace |
| Organization key without impersonation | Rejected — `403 USER_REQUIRED` |
| User belongs to a different organization | Rejected — `403 TEAM_NOT_ACCESSIBLE` |
In all accepted requests, the permissions of the resolved user are applied.
#### Rejection responses
A rejected impersonation request returns `application/problem+json` with a stable `code` you can branch on:
| Condition | Status | `code` |
| - | - | - |
| No impersonation header (or `X-User-Email` without `X-TEAM-ID`) | `403` | `USER_REQUIRED` |
| Resolved user does not exist | `401` | `USER_NOT_FOUND` |
| Resolved user belongs to a different organization | `403` | `TEAM_NOT_ACCESSIBLE` |
```json theme={null}
{
"title": "Access forbidden",
"status": 403,
"code": "USER_REQUIRED",
"detail": "This credential requires an acting-user header."
}
```
This is distinct from an invalid or expired key, which returns `401` with an empty body (see [Unauthorized response](#unauthorized-response)).
#### Important notes
* Every request runs with the permissions of the resolved user.
* The resolved user must belong to the same organization that issued the key.
* An Organization API key does not grant permissions beyond those of the resolved user.
## Keep your API key safe
* Never commit API keys to source control.
* Never share API keys in public chats or screenshots.
* Rotate your API key from **Settings → API Key** if you think it has been exposed.
# Bulk create domain blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/bulk-create-domain-blacklist-rules
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/domains/bulk
_Requires the `contacts:write` scope (or a broader one that includes it)._
Block several domains in one call. Every pattern is checked first, so one malformed domain rejects the whole request.
# Bulk create email blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/bulk-create-email-blacklist-rules
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/emails/bulk
_Requires the `contacts:write` scope (or a broader one that includes it)._
Block several addresses in one call. Every pattern is checked first, so one malformed address rejects the whole request.
# Bulk create email exception blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/bulk-create-email-exception-blacklist-rules
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/email-exceptions/bulk
_Requires the `contacts:write` scope (or a broader one that includes it)._
Carve several addresses out of your blacklist at once. One malformed address rejects the whole request before anything is stored.
# Bulk delete domain blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/bulk-delete-domain-blacklist-rules
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/domains/bulk-delete
_Requires the `contacts:write` scope (or a broader one that includes it)._
Lift several domain blocks at once. The ones that can go are deleted; the response lists only the ids that were not.
# Bulk delete email blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/bulk-delete-email-blacklist-rules
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/emails/bulk-delete
_Requires the `contacts:write` scope (or a broader one that includes it)._
Unblock several addresses at once. The ones that can go are deleted; the response lists only the ids that were not.
# Bulk delete email exception blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/bulk-delete-email-exception-blacklist-rules
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/email-exceptions/bulk-delete
_Requires the `contacts:write` scope (or a broader one that includes it)._
Withdraw several exceptions at once, putting their addresses back under your blacklist. Only failed ids come back.
# Create a domain blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/create-a-domain-blacklist-rule
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/domains
_Requires the `contacts:write` scope (or a broader one that includes it)._
Stop contacting everyone at a domain. Send the bare domain such as example.com — no scheme, no address.
# Create an email blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/create-an-email-blacklist-rule
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/emails
_Requires the `contacts:write` scope (or a broader one that includes it)._
Stop contacting one address while the rest of its domain stays reachable. Send a full email address as the pattern.
# Create an email exception blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/create-an-email-exception-blacklist-rule
/api-reference/bundled.yaml post /v3/contact-blacklist-rules/email-exceptions
_Requires the `contacts:write` scope (or a broader one that includes it)._
Keep one address contactable even though a domain rule blocks the rest of its domain. Send a full email address.
# Delete a domain blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/delete-a-domain-blacklist-rule
/api-reference/bundled.yaml delete /v3/contact-blacklist-rules/domains/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Stop blocking a domain so contacts there are reachable again. Only your own rules go; Reply's platform rules are read-only.
# Delete an email blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/delete-an-email-blacklist-rule
/api-reference/bundled.yaml delete /v3/contact-blacklist-rules/emails/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Unblock one address. It becomes reachable again unless a domain rule still covers its domain. Platform rules are read-only.
# Delete an email exception blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/delete-an-email-exception-blacklist-rule
/api-reference/bundled.yaml delete /v3/contact-blacklist-rules/email-exceptions/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Withdraw an exception so its address falls back under your blacklist, if a domain or email rule still covers it.
# Get a domain blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/get-a-domain-blacklist-rule
/api-reference/bundled.yaml get /v3/contact-blacklist-rules/domains/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get one domain blacklist rule by id with the pattern it blocks. isGlobal tells you if it's yours or a Reply platform rule.
# Get an email blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/get-an-email-blacklist-rule
/api-reference/bundled.yaml get /v3/contact-blacklist-rules/emails/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get one email blacklist rule by id with the address it blocks. isGlobal tells you if it's yours or a Reply platform rule.
# Get an email exception blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/get-an-email-exception-blacklist-rule
/api-reference/bundled.yaml get /v3/contact-blacklist-rules/email-exceptions/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get one email exception rule by id with the address it keeps contactable. Only your own exceptions resolve here.
# List domain blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/list-domain-blacklist-rules
/api-reference/bundled.yaml get /v3/contact-blacklist-rules/domains
_Requires the `contacts:read` scope (or a broader one that includes it)._
Review the domain rules in force for you, each blocking every contact at that domain. Paged with top and skip.
# List email blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/list-email-blacklist-rules
/api-reference/bundled.yaml get /v3/contact-blacklist-rules/emails
_Requires the `contacts:read` scope (or a broader one that includes it)._
Review the email rules in force for you, each blocking a single address rather than a domain. Paged with top and skip.
# List email exception blacklist rules
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/list-email-exception-blacklist-rules
/api-reference/bundled.yaml get /v3/contact-blacklist-rules/email-exceptions
_Requires the `contacts:read` scope (or a broader one that includes it)._
Review the addresses you carved out of your blacklist, each staying contactable despite a domain rule. Paged with top and skip.
# Update a domain blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/update-a-domain-blacklist-rule
/api-reference/bundled.yaml put /v3/contact-blacklist-rules/domains/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Correct the domain a blacklist rule blocks. Send the full replacement pattern — it's the only field the rule carries.
# Update an email blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/update-an-email-blacklist-rule
/api-reference/bundled.yaml put /v3/contact-blacklist-rules/emails/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Change which address an email blacklist rule blocks. Send the full replacement pattern; platform rules are read-only.
# Update an email exception blacklist rule
Source: https://docs.reply.io/api-reference/contact-blacklist-rules/update-an-email-exception-blacklist-rule
/api-reference/bundled.yaml put /v3/contact-blacklist-rules/email-exceptions/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Change which address an exception keeps contactable. The previous address falls back under whatever rules cover it.
# Add contacts to a contact list
Source: https://docs.reply.io/api-reference/contact-lists/add-contacts-to-a-contact-list
/api-reference/bundled.yaml post /v3/contact-lists/{id}/add-contacts
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Add contacts to a list while keeping their other list memberships. Contacts are processed one by one, so partial success sticks.
# Create a contact list
Source: https://docs.reply.io/api-reference/contact-lists/create-a-contact-list
/api-reference/bundled.yaml post /v3/contact-lists
_Requires the `contacts:write` scope (or a broader one that includes it)._
Create a contact list to group contacts under. Set isShared to make it visible to your team, or leave it false to keep it private.
# Delete a contact list
Source: https://docs.reply.io/api-reference/contact-lists/delete-a-contact-list
/api-reference/bundled.yaml delete /v3/contact-lists/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Delete a contact list by id. A shared list can only be deleted by the person who created it.
# Get a contact list
Source: https://docs.reply.io/api-reference/contact-lists/get-a-contact-list
/api-reference/bundled.yaml get /v3/contact-lists/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get one contact list by id, including its name and whether it is shared with your team.
# Get contact's lists
Source: https://docs.reply.io/api-reference/contact-lists/get-contacts-lists
/api-reference/bundled.yaml get /v3/contacts/{id}/lists
_Requires the `contacts:read` scope (or a broader one that includes it)._
See which contact lists a contact belongs to, including each list's name and whether it's shared with your team.
# List contact lists
Source: https://docs.reply.io/api-reference/contact-lists/list-contact-lists
/api-reference/bundled.yaml get /v3/contact-lists
_Requires the `contacts:read` scope (or a broader one that includes it)._
Browse the contact lists you own plus any shared with your team. Paged with top and skip, with an optional name search.
# Move contacts to a contact list
Source: https://docs.reply.io/api-reference/contact-lists/move-contacts-to-a-contact-list
/api-reference/bundled.yaml post /v3/contact-lists/{id}/move-contacts
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Move contacts into a list and out of every other list. Use add-contacts instead to keep their existing memberships.
# Share a contact list
Source: https://docs.reply.io/api-reference/contact-lists/share-a-contact-list
/api-reference/bundled.yaml post /v3/contact-lists/{id}/share
_Requires the `contacts:write` scope (or a broader one that includes it)._
Make one of your private contact lists visible to the rest of your team. Use the unshare endpoint to reverse it later.
# Unshare a contact list
Source: https://docs.reply.io/api-reference/contact-lists/unshare-a-contact-list
/api-reference/bundled.yaml post /v3/contact-lists/{id}/unshare
_Requires the `contacts:write` scope (or a broader one that includes it)._
Take a shared contact list out of team visibility and make it private to you again.
# Update a contact list
Source: https://docs.reply.io/api-reference/contact-lists/update-a-contact-list
/api-reference/bundled.yaml put /v3/contact-lists/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Rename a contact list. Only the name changes here — use share and unshare to change visibility. The new name must be unique.
# Add a note to a contact
Source: https://docs.reply.io/api-reference/contacts/add-a-note-to-a-contact
/api-reference/bundled.yaml post /v3/contacts/{id}/notes
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Record context, call summaries, or reminders on a contact's timeline, so your whole team works from the same history.
# Bulk delete contacts
Source: https://docs.reply.io/api-reference/contacts/bulk-delete-contacts
/api-reference/bundled.yaml post /v3/contacts/bulk-delete
_Requires the `contacts:write` scope (or a broader one that includes it)._
Delete several contacts in one call. Each is handled on its own, and the response maps any skipped contact to its reason.
# Change contacts owner
Source: https://docs.reply.io/api-reference/contacts/change-contacts-owner
/api-reference/bundled.yaml put /v3/contacts/owner
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Reassign contacts to another teammate after a handoff or territory change. Set reassignTasks to move their tasks too.
A user can own only one contact per email. Contacts whose email the target user already owns keep their current owner and are left out of `affectedIds`. When several requested contacts share an email, only one of them is reassigned.
# Count filtered contacts
Source: https://docs.reply.io/api-reference/contacts/count-filtered-contacts
/api-reference/bundled.yaml post /v3/contacts/filter/count
**Breaking change from early November 2026.** Send `conditions` instead of `rules`, and count a sequence's contacts with `POST /v3/sequences/{id}/contacts/filter/count`; `rules`, `sequenceId` and `sequenceStepId` return 400.
_Requires the `contacts:read` scope (or a broader one that includes it)._
Use this endpoint when you need only the number of contacts that match a set of filter criteria — for example to show a total or decide whether to page through the results — without fetching the contacts themselves. It accepts the same request body as the filter endpoint.
# Create a contact
Source: https://docs.reply.io/api-reference/contacts/create-a-contact
/api-reference/bundled.yaml post /v3/contacts
_Requires the `contacts:write` scope (or a broader one that includes it)._
Add a single contact to your account with any profile and custom fields you have. Returns the contact with its new id.
When the Accounts feature is enabled for the workspace and `company` is set without `accountId`, the contact is
linked to the team's contact account with that name, or to a new account created from `company`, `industry` and
`companySize`. A deleted account with that name is restored, and an existing account gets `industry` and
`companySize` from the request only where its own are empty. The contact's `company`, `industry` and `companySize`
then come from the linked account. `accountId`, when set, takes precedence over `company`.
# Delete a contact
Source: https://docs.reply.io/api-reference/contacts/delete-a-contact
/api-reference/bundled.yaml delete /v3/contacts/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Delete one contact by its Reply id. To remove several at once, use the bulk-delete endpoint instead.
# Filter contacts
Source: https://docs.reply.io/api-reference/contacts/filter-contacts
/api-reference/bundled.yaml post /v3/contacts/filter
**Breaking change from early November 2026.** Send `conditions` instead of `rules`, and filter a sequence's contacts with `POST /v3/sequences/{id}/contacts/filter`; `rules`, `sequenceId` and `sequenceStepId` return 400.
_Requires the `contacts:read` scope (or a broader one that includes it)._
Use this endpoint when you need a filtered, sorted page of contacts that a plain email or LinkedIn lookup cannot express. Combine field conditions with optional scoping by list, a free-text search term, and a sort order. Results are paged with the top and skip query parameters. To get only the total for the same criteria, use filter/count. For one sequence's contacts, use `POST /v3/sequences/{id}/contacts/filter`.
Conditions are joined with AND, one condition per field: an `operator` with its `value`, an `and` list of rules that must all match, or an `or` list of alternatives. `GET /v3/contacts/filter/fields` lists the fields, operators and values your workspace accepts. Field names, operators and enum values are case-insensitive.
# Get a contact
Source: https://docs.reply.io/api-reference/contacts/get-a-contact
/api-reference/bundled.yaml get /v3/contacts/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the full record for one contact by id: profile fields, owner, opt-out, call and meeting status, and custom fields.
# Get a contact's statuses
Source: https://docs.reply.io/api-reference/contacts/get-a-contacts-statuses
/api-reference/bundled.yaml get /v3/contacts/{id}/statuses
_Requires the `contacts:read` scope (or a broader one that includes it)._
Check where a contact stands: global opt-out, call and meeting flags, plus their status in each sequence they're enrolled in.
# Get a note of a contact
Source: https://docs.reply.io/api-reference/contacts/get-a-note-of-a-contact
/api-reference/bundled.yaml get /v3/contacts/{id}/notes/{note_id}
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `contacts:read` scope (or a broader one that includes it)._
Read one note recorded on a contact by its id. The note must belong to the contact in the path; a note id from another contact is not found.
# Get activities for a contact
Source: https://docs.reply.io/api-reference/contacts/get-activities-for-a-contact
/api-reference/bundled.yaml get /v3/contacts/{id}/activities
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get a contact's activity history — emails, calls, status changes, and other tracked events. Paged with top and skip.
# Get inbox threads for a contact
Source: https://docs.reply.io/api-reference/contacts/get-inbox-threads-for-a-contact
/api-reference/bundled.yaml get /v3/contacts/{id}/inbox-threads
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the email conversation threads exchanged with a contact, grouped as they appear in your inbox. Paged with top and skip.
# Get sequences for a contact
Source: https://docs.reply.io/api-reference/contacts/get-sequences-for-a-contact
/api-reference/bundled.yaml get /v3/contacts/{id}/sequences
_Requires the `contacts:read` scope (or a broader one that includes it)._
See which sequences a contact is in, with each sequence's name, their status, the current step, and when they were added.
# Import contacts
Source: https://docs.reply.io/api-reference/contacts/import-contacts
/api-reference/bundled.yaml post /v3/contacts/import
_Requires the `contacts:write` scope (or a broader one that includes it)._
Use this endpoint when you need to add or update many contacts in one call — for example when
syncing contacts from another system. Each item requires firstName; the remaining fields are
optional and use the same fields as the contact update model. An item with no firstName is not
imported — it comes back with status "failed" and error "Invalid data", while the response itself
still has HTTP status 200. Use options to control deduplication, list assignment, and other
import behavior: which keys identify an existing contact (email plus any of contactId, LinkedIn
URL, phone, name, company, or custom fields), whether matched contacts are overwritten or
skipped, whether previously deleted contacts are restored, and which lists or sequence the
imported contacts are added to. With the contactId key, every item must carry a contactId and the
match is made on the id alone. The response reports how many contacts were added, updated,
skipped, or failed, with a per-item outcome. When options carries a sequenceId, each item also
reports whether that contact was enrolled, and the response carries the enrollment totals: a
contact can be imported and still be refused by the sequence, for instance when it is opted
out or already running there.
# List all contacts
Source: https://docs.reply.io/api-reference/contacts/list-all-contacts
/api-reference/bundled.yaml get /v3/contacts
_Requires the `contacts:read` scope (or a broader one that includes it)._
Browse your contacts or look one up by exact email or LinkedIn URL. Paged with the top and skip query parameters.
# List contact filter fields
Source: https://docs.reply.io/api-reference/contacts/list-contact-filter-fields
/api-reference/bundled.yaml get /v3/contacts/filter/fields
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `contacts:read` scope (or a broader one that includes it)._
List the fields `POST /v3/contacts/filter` accepts in your workspace, with each field's operators, value types and allowed values. Stage names and custom fields are your workspace's own. Fields read from one sequence membership (opened, status in sequence, current step) are listed by `GET /v3/sequences/{id}/contacts/filter/fields` instead.
# List notes for a contact
Source: https://docs.reply.io/api-reference/contacts/list-notes-for-a-contact
/api-reference/bundled.yaml get /v3/contacts/{id}/notes
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `contacts:read` scope (or a broader one that includes it)._
Read back the notes recorded on a contact, newest first, paged with top and skip. Each note carries its id, text, author and timestamp, so context written by your team or by an external agent can be retrieved later.
# Mark or unmark contacts as bounced
Source: https://docs.reply.io/api-reference/contacts/mark-or-unmark-contacts-as-bounced
/api-reference/bundled.yaml post /v3/contacts/set-bounced
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Record bounces detected outside Reply across every sequence a contact is in. Marking as bounced stops further steps.
# Mark or unmark contacts as replied
Source: https://docs.reply.io/api-reference/contacts/mark-or-unmark-contacts-as-replied
/api-reference/bundled.yaml post /v3/contacts/set-replied
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Record replies captured outside Reply, in another inbox or CRM, across every sequence a contact is in. Stops further steps.
# Move a contact to a sequence
Source: https://docs.reply.io/api-reference/contacts/move-a-contact-to-a-sequence
/api-reference/bundled.yaml post /v3/contacts/{id}/move-to-sequence
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Enroll a contact into a different sequence. Set removeFromExisting to true to take them out of their current one.
# Opt contacts out or clear their opt-out
Source: https://docs.reply.io/api-reference/contacts/opt-contacts-out-or-clear-their-opt-out
/api-reference/bundled.yaml post /v3/contacts/set-opted-out
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Opt contacts out of all outreach, or clear the flag. Opting out finishes them in every sequence they're in. The `contact_opted_out` webhook fires once per enrolled sequence, and not at all for a contact in no sequence.
# Run a Prompt Action on contacts
Source: https://docs.reply.io/api-reference/contacts/run-a-prompt-action-on-contacts
/api-reference/bundled.yaml post /v3/contacts/run-prompt-action
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Run one of your saved Prompt Actions over a batch of contacts and write its outputs into their custom fields. Up to 1000 contacts per call.
The run is asynchronous: the response returns straight away with a `jobId`, and Reply credits are reserved up front for the contacts it accepted. Poll `GET /v3/background-jobs/{jobId}` with that id to follow progress. Manage the Prompt Actions themselves under `/v3/prompt-actions`.
# Set contacts' in-sequence status
Source: https://docs.reply.io/api-reference/contacts/set-contacts-in-sequence-status
/api-reference/bundled.yaml post /v3/contacts/set-status-in-sequence
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Set contacts to active, paused, finished, or outOfOffice across their sequences. Replied and bounced are separate. Active, paused and outOfOffice are applied only in sequences the caller owns; finished is applied in every sequence the caller can see.
# Update a contact
Source: https://docs.reply.io/api-reference/contacts/update-a-contact
/api-reference/bundled.yaml patch /v3/contacts/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Change specific fields on a contact without resending the whole record. Omitted fields stay as they are; null clears one.
# Create a custom field
Source: https://docs.reply.io/api-reference/custom-fields/create-a-custom-field
/api-reference/bundled.yaml post /v3/custom-fields
_Requires the `contacts:write` scope (or a broader one that includes it)._
Track something on contacts or accounts that Reply doesn't capture by default. Provide a title and a text or number field type; set `entityType` to `account` for a field that lives on accounts.
# Delete a custom field
Source: https://docs.reply.io/api-reference/custom-fields/delete-a-custom-field
/api-reference/bundled.yaml delete /v3/custom-fields/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Retire a custom field your team no longer collects. It disappears for everyone, even where contacts already hold values.
# Enrich contacts with an AI custom field
Source: https://docs.reply.io/api-reference/custom-fields/enrich-contacts-with-an-ai-custom-field
/api-reference/bundled.yaml post /v3/custom-fields/{id}/enrich
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Fill an AI custom field for your contacts. The work is queued and runs in the background; each enrichment costs one credit.
# Get a custom field
Source: https://docs.reply.io/api-reference/custom-fields/get-a-custom-field
/api-reference/bundled.yaml get /v3/custom-fields/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get one custom field definition by id: its title, its text or number type, its metadata, and whether it's org-wide.
# List all custom fields
Source: https://docs.reply.io/api-reference/custom-fields/list-all-custom-fields
/api-reference/bundled.yaml get /v3/custom-fields
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get every custom field of one entity, for your team and your organization. One flat array, no paging. Without `entityType` you get the fields your contacts can carry; pass `entityType=account` for the fields your accounts can carry.
# Preview an AI custom field
Source: https://docs.reply.io/api-reference/custom-fields/preview-an-ai-custom-field
/api-reference/bundled.yaml post /v3/custom-fields/{id}/preview
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `contacts:operate` scope (or a broader one that includes it)._
See what an AI custom field would produce for one contact. Nothing is written to the contact.
# Update a custom field
Source: https://docs.reply.io/api-reference/custom-fields/update-a-custom-field
/api-reference/bundled.yaml put /v3/custom-fields/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Rename a custom field or change the kind of value it holds. Send the complete definition — metadata is replaced, not merged.
# Introduction
Source: https://docs.reply.io/api-reference/introduction
The Reply API v3 in one page: base URL, Bearer token auth, JSON format, rate limits, and what each group of endpoints covers.
Reply is an AI-powered sales engagement platform. The Reply API (v3) gives you access to the platform through a REST API, so you can automate the same workflows available in the Reply dashboard from your own applications, scripts, or AI agents.
## At a glance
Every request is an HTTPS call to a `/v3` endpoint and includes your API key in the `Authorization` header. This example returns information about the authenticated user and confirms that your credentials work:
```bash theme={null}
curl https://api.reply.io/v3/whoami \
-H "Authorization: Bearer YOUR_API_KEY"
```
* **Base URL**: `https://api.reply.io`, with all endpoints under the `/v3` prefix (for example, `/v3/sequences`).
* **Authentication**: Bearer token in the `Authorization` header on every request.
* **Format**: JSON request and response bodies. Errors use `application/problem+json`.
* **Rate limits**: 100 requests per minute, 3,000 per hour and 150,000 per week, per user.
## What you can do
The API covers every major area of the platform. Each area has its own group of endpoints in the API reference.
| Area | What you can manage |
| - | - |
| **Contacts & data** | Contacts, contact lists, custom fields, and blacklist rules |
| **Sequences** | Multichannel sequences across email, LinkedIn, calls, and manual tasks |
| **Accounts & templates** | Connected email and LinkedIn accounts, plus shared templates |
| **Inbox** | Replies handled through the unified Inbox |
| **Scheduling** | Sending schedules and holiday calendars that control send times |
| **Tasks** | Manual tasks assigned to your team |
| **Reporting** | Performance reports across all channels |
| **Automation** | Webhooks for real-time events and background jobs for long-running operations |
| **Support** | Support requests to Reply's support team, with the conversation and files |
## API conventions
The API follows consistent patterns across endpoints.
### REST
Resource URLs use plural nouns and standard HTTP methods:
* `GET` to read
* `POST` to create
* `PATCH` to update
* `DELETE` to remove
Request and response bodies use JSON.
### Errors
All `4xx` and `5xx` responses use `application/problem+json`.
Business errors include a stable code in `.` format, so you can handle them programmatically:
```json theme={null}
{
"title": "Bad Request",
"status": 400,
"detail": "Unknown webhook event 'email_clicked'.",
"code": "webHook.invalidEvent"
}
```
Validation errors (`400 Bad Request`) also include an `errors[]` array. Each entry identifies the invalid field using a JSON Pointer.
### Asynchronous jobs
Long-running operations, such as email validation and large bulk imports, return `202 Accepted` with a `Location` header that points to `/v3/background-jobs/{id}`.
Use the Background Jobs endpoint to check job status or cancel a job.
## Authentication
v3 uses Bearer token authentication. Every request must include an `Authorization: Bearer ` header.
If the token is missing, invalid, or revoked, the API returns `401 Unauthorized` with a `WWW-Authenticate: Bearer` header and an empty response body.
See **Authentication** for instructions on generating an API key, making your first authenticated request, using Master and Organization keys, and verifying credentials with `/v3/whoami`.
## Rate limits
To protect the platform, requests are limited to 100 per minute, 3,000 per hour and 150,000 per week, per user.
When you exceed a limit, the API returns `429 Too Many Requests` and includes a `Retry-After` header that tells you when to retry.
Reporting and statistics endpoints have stricter limits. See **Rate Limits** for details.
## Versioning
v3 is the current supported version and should be used for all new integrations.
API v1 and v2 remain available but are no longer supported and will be deprecated in the future. Their documentation is available at `apidocs.reply.io`.
## Connect an AI agent
Reply MCP connects Reply to Claude, Cursor, and other MCP-compatible AI clients, allowing agents to use Reply without making direct HTTP requests.
> [card] [Reply MCP](/mcp/overview)
>
> Connect Reply to your AI client.
> [card] [Authentication](/api-reference/authentication)
>
> Get an API key and make your first authenticated request.
## Get help
Questions, feedback, or stuck on an endpoint? The Reply developer community on Slack is the
fastest way to reach us and other builders. For a problem with your Reply account or your data,
[raise a support request](/api-reference/support).
> [card] [Join the Slack community](/slack)
>
> Ask questions, share feedback, and discuss the API — no Reply account required.
# List Live Data searches
Source: https://docs.reply.io/api-reference/live-data/list-live-data-searches
/api-reference/bundled.yaml get /v3/live-data/searches
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the Live Data searches your team has run, newest first, each with status, contacts found, and credits used.
# Preview a Live Data search
Source: https://docs.reply.io/api-reference/live-data/preview-a-live-data-search
/api-reference/bundled.yaml post /v3/live-data/searches/preview
_Requires the `contacts:write` scope (or a broader one that includes it)._
Size a Live Data audience before spending on it. Nothing is saved and no contacts are added, so you can try combinations.
# Start a Live Data search
Source: https://docs.reply.io/api-reference/live-data/start-a-live-data-search
/api-reference/bundled.yaml post /v3/live-data/searches
_Requires the `contacts:write` scope (or a broader one that includes it)._
Run a set of Live Data filters and add the people it matches to your contacts. Send filters and contactsCountToAdd.
# Create a Prompt Action
Source: https://docs.reply.io/api-reference/prompt-actions/create-a-prompt-action
/api-reference/bundled.yaml post /v3/prompt-actions
_Requires the `contacts:write` scope (or a broader one that includes it)._
Save a prompt your team can run against contacts. Give it between one and six outputs; map an output to an existing contact custom field with `customFieldId`, or leave that out and a new field titled after the output `label` is created for you.
# Delete a Prompt Action
Source: https://docs.reply.io/api-reference/prompt-actions/delete-a-prompt-action
/api-reference/bundled.yaml delete /v3/prompt-actions/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Remove a Prompt Action. The custom fields its outputs wrote into stay, along with the values already stored on your contacts.
# Get a Prompt Action
Source: https://docs.reply.io/api-reference/prompt-actions/get-a-prompt-action
/api-reference/bundled.yaml get /v3/prompt-actions/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Read one Prompt Action, including its prompt text, its outputs and the custom fields they write into.
# List Prompt Actions
Source: https://docs.reply.io/api-reference/prompt-actions/list-prompt-actions
/api-reference/bundled.yaml get /v3/prompt-actions
_Requires the `contacts:read` scope (or a broader one that includes it)._
Browse the Prompt Actions your team has saved, newest activity included. Each one carries its prompt text and the custom fields its outputs are written into. Paged with `top` and `skip`.
# Update a Prompt Action
Source: https://docs.reply.io/api-reference/prompt-actions/update-a-prompt-action
/api-reference/bundled.yaml put /v3/prompt-actions/{id}
_Requires the `contacts:write` scope (or a broader one that includes it)._
Replace a Prompt Action's name, prompt text and outputs. The whole definition is overwritten, so send every output you want to keep — any output you leave out is dropped.
# Rate limits
Source: https://docs.reply.io/api-reference/rate-limits
Reply API rate limits are 100 requests per minute, 3,000 per hour and 150,000 per week. See stricter endpoints, check usage, handle 429 and raise your limits.
The Reply API limits the number of requests each user can make. When a limit is exceeded, the API returns `429 Too Many Requests`.
## Limits
* **100 requests per minute**
* **3,000 requests per hour**
* **150,000 requests per week**
Each window starts with your first request and resets one full period later; the weekly window is a rolling 7 days, not a calendar week.
Limits are applied per user. Requests made by multiple applications, scripts, or services on behalf of the same user count toward the same quota.
## Stricter endpoints
Some endpoints have lower limits than the default quotas, including:
* **Reporting:** `/v3/reporting/*`
* **Sequence statistics:**
* `/v3/sequences/{id}/stats`
* `/v3/sequences/stats`
* **Support requests:**
* `/v3/support/*`
* `POST /v3/support/requests`
Analytics and reporting endpoints may return `429 Too Many Requests` before the general limits are reached.
## The 429 response
When a rate limit is exceeded, the API returns:
* **Status:** `429 Too Many Requests`
* **Headers:**
* `Retry-After: ` — seconds to wait before the quota window resets
* `Content-Type: application/problem+json`
* **Body:**
```json theme={null}
{
"title": "Too Many Requests",
"status": 429,
"detail": "API calls quota exceeded! maximum admitted 100 per 1m."
}
```
The numbers in `detail` reflect the limit that was exceeded, for example `3000 per 1h` for the hourly quota or `150000 per 7d` for the weekly one.
## Response headers
Successful responses include headers describing your current quota:
| Header | Example | Description |
| - | - | - |
| `x-rate-limit-limit` | `7d` | The period of the reported limit (such as `1h` or `7d`), not a request count. |
| `x-rate-limit-remaining` | `148730` | Requests remaining in that period. |
| `x-rate-limit-reset` | `2026-10-11T14:37:12.0000000Z` | UTC time when that period resets. |
These headers are not included on `429` responses, which carry only `Retry-After`.
> [!NOTE]
>
> The headers report the longest-period limit that applies to the endpoint. A shorter limit, such as the per-minute quota, can return `429` while `x-rate-limit-remaining` still shows requests left, so don't rely on these headers to predict a `429`.
## Check your usage
[`GET /v3/rate-limits`](/api-reference/rate-limits/get-rate-limits) returns every limit that applies to you — per minute, per hour and per week — with how many requests you have used and when each count resets, in one call. The response headers cover only one limit.
## Raise your limits
API limit packages raise your limits. Each active package adds the standard limits once more, for you alone: with 2 active packages you get 300 requests per minute, 9,000 per hour and 450,000 per week, and the stricter reporting limits triple the same way. Packages raise the limits on this page; the [MCP server](/mcp/overview) limits stay the same.
Packages are bought for your organization and shared through one pool.
**1. Buy packages**
The organization owner buys them in the Reply app, in [Plans & Billing](https://run.reply.io/Dashboard/Material#/settings/plans-billing), through the **API limit packages** item of the upgrade wizard. Packages can't be bought through the API.
**2. Claim them**
Each user claims packages from the pool for their own limits, in [API keys](https://run.reply.io/Dashboard/Material#/settings/api-keys) → **API rate limit packages** or with [`PUT /v3/settings/api-limit-packages/mine`](/api-reference/rate-limits/set-your-api-limit-packages). New limits apply within about 30 seconds.
**3. Check them**
[`GET /v3/settings/api-limit-packages`](/api-reference/rate-limits/get-api-limit-packages) shows the pool and the packages you hold. [`GET /v3/rate-limits`](/api-reference/rate-limits/get-rate-limits) shows `activePackages` and the `limit` that applies to you in each window.
## Handling 429
**1. Respect Retry-After**
Wait for the number of seconds specified in the `Retry-After` header before retrying the request.
**2. Limit concurrency**
For bulk operations, process requests sequentially or use a small concurrency limit instead of sending many requests in parallel.
**3. Raise your limits if 429s keep coming**
If normal use keeps hitting a limit, claim packages from your organization's pool, or ask the organization owner to buy more. See [Raise your limits](#raise-your-limits).
# Support
Source: https://docs.reply.io/api-reference/support
Raise and follow support requests with Reply's support team through the API: what to send, how a request moves, how you hear back, and the limits.
> [!WARNING]
>
> **Coming soon.** Support requests through the API will be available by mid November 2026.
When something in your Reply account doesn't work as expected, raise a support request through the API, from your
code or through your AI agent. Reply's support team works on it, and you follow the conversation through the API and
by email.
## Raise a request
```bash theme={null}
curl https://api.reply.io/v3/support/requests \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "Sequence stopped sending after editing step 2",
"description": "Sequence \"Q4 outreach\" stopped sending after I edited step 2. I expected the next step to go out at 9:00.",
"traceIds": ["4bf92f3577b34da6a3ce929d0e0e4736"],
"issueDate": "2026-11-12T08:30:00Z"
}'
```
The response is the new request, with its ID (for example `CS-1234`) and the status `new`. Your API key needs the
`support:write` scope to raise, answer and cancel requests and to add files, and `support:read` to read them.
### What helps support most
* **Trace IDs.** Every API response carries an `X-Trace-Id` header. Send the ones from the calls that went wrong in
`traceIds`, and support can look up exactly those calls.
* **When it happened.** `issueDate` tells support which time window to check.
* **Files.** Add screenshots, logs or HAR files with
[Add a file to a support request](/api-reference/support-requests/add-a-file-to-a-support-request).
* **A clear description.** What you did, what you expected, and what happened instead.
Don't send secrets. Anything that looks like an API key or a token is removed before a request or an answer is
stored.
## How a request moves
| Status | Meaning | What you can do |
| - | - | - |
| `new` | Raised; support hasn't picked it up yet. | Wait, or add details. |
| `inProgress` | Support is working on it. | Wait, or add details. |
| `needsResponse` | Support is waiting for your answer. | [Answer it](/api-reference/support-requests/send-an-answer-to-a-support-request). |
| `done` | Resolved, or cancelled by you. | Nothing; raise a new request if the problem comes back. |
Support moves a request between statuses. You can
[cancel a request](/api-reference/support-requests/cancel-a-support-request) at any time; it becomes `done`. A `done`
request can't be answered or given more files.
## Hearing back
Support's answers appear in the request's `messages` (`from: support`), next to yours (`from: you`), and arrive by
email at your account's address.
To follow your requests from code, check
[List support requests](/api-reference/support-requests/list-support-requests) with `?status=needsResponse`
periodically. A request you have just raised can take a few seconds to show up in the list;
[Get a support request](/api-reference/support-requests/get-a-support-request) returns it right away.
## Limits
* **3 open requests** at a time, in any status but `done`. Raising another returns `409` with `openRequestIds`.
* **10 new requests** in 24 hours, and **3 a minute**. Over that, the API returns `429` with a `Retry-After` header.
* **500 requests an hour** to the support endpoints, on top of the general [rate limits](/api-reference/rate-limits).
* **10 files** per request, **25 MB** each.
# Platform overview
Source: https://docs.reply.io/getting-started
One platform, four access layers — API, MCP, CLI, and Skills over the same Reply.io workspace.
Reply.io exposes one sales-engagement platform through four access layers. They share the same
account, the same [API key](/api-reference/authentication), the same object model, and the same
[rate limits](/api-reference/rate-limits) — pick the surface that fits how you (or your agent) work.
## Pick your surface
> [card] [REST API](/api-reference/introduction)
>
> The exhaustive surface. Every endpoint, schema, and webhook — for production integrations.
> [card] [MCP](/mcp/overview)
>
> 71 annotated tools for MCP clients — Claude, Cursor, and custom agents.
> [card] [CLI](/cli/overview)
>
> `reply` in your terminal — sign in once, then call any v3 endpoint as yourself.
> [card] [Skills](/skills/overview)
>
> Outbound expertise and guardrails as markdown skill packs for your AI assistant.
Not sure which to use? See [Choose your interface](/agents/choose-your-interface).
## Go further
> [card] [Guides](/guides/launch-outreach)
>
> Task-based guides — from importing contacts to building an AI SDR.
> [card] [For AI agents](/agents/overview)
>
> Agentic capabilities, safety rules, and drop-in prompts.
> [card] [OpenAPI & Postman](/openapi-postman)
>
> Download the OpenAPI spec or import the Postman collection.
> [card] [Slack community](/slack)
>
> Ask questions, share feedback, and request features.
> [card] [Support](/api-reference/support)
>
> Raise and follow support requests, from your code or your agent.
# OpenAPI & Postman
Source: https://docs.reply.io/openapi-postman
Download the Reply API OpenAPI 3.1 spec or import the Postman collection to generate clients and test endpoints with auth already set up.
## OpenAPI
The complete Reply API specification is available in OpenAPI 3.1 format.
Use it to:
* Generate client libraries
* Explore the API structure
* Import the API into tools such as Postman
## OpenAPI Spec
> [card] [View OpenAPI Spec](/api-reference/bundled.yaml)
>
> Open the complete OpenAPI specification (YAML)
Download OpenAPI Spec (YAML)
## Postman
Import the Reply API into Postman to explore and test it.
### What's included
Importing the OpenAPI spec gives you:
* Every Reply API endpoint, grouped by tag — Sequences, Contacts, Email Accounts, Templates, and more
* Request and response schemas for each operation
* A `baseUrl` collection variable, taken from the spec
* Collection-level Bearer authentication, ready for your API key
## Setup
**1. Get your API key**
1. Sign in to [Reply.io account](https://run.reply.io)
2. Go to **Settings → API Key**.
3. Create a new API key or copy an existing one.
**2. Import the collection**
1. Open Postman.
2. Click **Import**, then select **Link**.
3. Paste the OpenAPI spec URL below, then click **Continue** and **Import**.
```text theme={null}
https://docs.reply.io/api-reference/bundled.yaml
```
Postman builds a collection from the spec.
**3. Configure your environment**
The import sets `baseUrl` from the spec. Add your API key as an environment variable:
| Variable | Description | Example |
| - | - | - |
| `apiKey` | Your Reply.io API key | `************` |
**4. Set authentication**
Include your API key as a Bearer token:
```text theme={null}
Authorization: Bearer {{apiKey}}
```
## Test your setup
Send a request to:
```bash theme={null}
GET https://api.reply.io/v3/whoami
Authorization: Bearer your_api_key_here
```
If authentication succeeds, the API returns information about the authenticated user.
# Slack community
Source: https://docs.reply.io/slack
Join the Reply developer Slack to ask API questions, share feedback, and talk with other developers. No Reply account needed to join.
Join the Reply developer community on Slack to ask questions, share feedback, and discuss the API.
> [card] [Join the community](https://join.slack.com/t/replyio-api-community/shared_invite/zt-3zcjgphz4-Nj~dXkOUGnOXKN_wBgp5Wg)
>
> No Reply account required.
# List AI web searches for a sequence
Source: https://docs.reply.io/api-reference/ai-sdr-web-search/list-ai-web-searches-for-a-sequence
/api-reference/bundled.yaml get /v3/ai-web-search/searches
**Coming soon.** This endpoint will be available by late November 2026.
Review the AI web searches already started for one sequence. sequenceId is required, so each call covers a single sequence.
# Start an AI web search
Source: https://docs.reply.io/api-reference/ai-sdr-web-search/start-an-ai-web-search
/api-reference/bundled.yaml post /v3/ai-web-search/start
**Coming soon.** This endpoint will be available by late November 2026.
Have Reply find new contacts for a sequence by searching the web with AI. Runs in the background and returns once accepted.
# Enrich contacts by email
Source: https://docs.reply.io/api-reference/contact-enrichment/enrich-contacts-by-email
/api-reference/bundled.yaml post /v3/contacts/enrich-by-email
**Coming soon.** This endpoint will be available by late November 2026.
Fill in missing details on contacts that already have an email address. Contacts without one need the find-emails endpoint.
# Enrich contacts by LinkedIn URL
Source: https://docs.reply.io/api-reference/contact-enrichment/enrich-contacts-by-linkedin-url
/api-reference/bundled.yaml post /v3/contacts/enrich-by-linkedin
**Coming soon.** This endpoint will be available by late November 2026.
Enrich contacts from their LinkedIn profile URL, optionally looking up a missing email and phone number in the same pass.
# Find missing email addresses
Source: https://docs.reply.io/api-reference/contact-enrichment/find-missing-email-addresses
/api-reference/bundled.yaml post /v3/contacts/find-emails
**Coming soon.** This endpoint will be available by late November 2026.
Find email addresses for contacts that don't have one yet. Contacts that already have an address are left alone.
# Find phone numbers
Source: https://docs.reply.io/api-reference/contact-enrichment/find-phone-numbers
/api-reference/bundled.yaml post /v3/contacts/find-phones
**Coming soon.** This endpoint will be available by late November 2026.
Find phone numbers for your contacts. Accepted straight away, with the search running in the background.
# Add tags to an email account
Source: https://docs.reply.io/api-reference/email-accounts/add-tags-to-an-email-account
/api-reference/bundled.yaml post /v3/email-accounts/{id}/tags
_Requires the `channels:operate` scope (or a broader one that includes it)._
Label an email account so you can group or filter by it. Tags go by name, and any name that doesn't exist yet is created.
# Bulk delete email accounts
Source: https://docs.reply.io/api-reference/email-accounts/bulk-delete-email-accounts
/api-reference/bundled.yaml post /v3/email-accounts/bulk-delete
_Requires the `channels:write` scope (or a broader one that includes it)._
Disconnect several email accounts in one call. Successful deletions stick; the response returns only the ids that failed.
# Connect Gmail account via OAuth
Source: https://docs.reply.io/api-reference/email-accounts/connect-gmail-account-via-oauth
/api-reference/bundled.yaml get /v3/email-accounts/connect/gmail
_Requires the `channels:write` scope (or a broader one that includes it)._
Start connecting a Gmail mailbox. Returns a 302 to Google's consent screen, so follow it in a browser, not a backend client.
# Connect Office 365 account via OAuth
Source: https://docs.reply.io/api-reference/email-accounts/connect-office-365-account-via-oauth
/api-reference/bundled.yaml get /v3/email-accounts/connect/office-365
_Requires the `channels:write` scope (or a broader one that includes it)._
Start connecting an Office 365 or Outlook mailbox. Returns a 302 to Microsoft's consent screen — follow it in a browser.
# Create an email account
Source: https://docs.reply.io/api-reference/email-accounts/create-an-email-account
/api-reference/bundled.yaml post /v3/email-accounts
_Requires the `channels:write` scope (or a broader one that includes it)._
Connect a custom SMTP or IMAP mailbox. Gmail and Office 365 use their own OAuth connect endpoints instead.
# Delete an email account
Source: https://docs.reply.io/api-reference/email-accounts/delete-an-email-account
/api-reference/bundled.yaml delete /v3/email-accounts/{id}
_Requires the `channels:write` scope (or a broader one that includes it)._
Disconnect one email account and remove it from Reply by id. Use bulk-delete to remove several in one call.
# Filter email account stats
Source: https://docs.reply.io/api-reference/email-accounts/filter-email-account-stats
/api-reference/bundled.yaml post /v3/email-accounts/stats
_Requires the `channels:read` scope (or a broader one that includes it)._
Get sending stats for a set of email accounts at once — handy for spotting mailboxes near their daily limit.
# Filter email accounts
Source: https://docs.reply.io/api-reference/email-accounts/filter-email-accounts
/api-reference/bundled.yaml post /v3/email-accounts/filter
_Requires the `channels:read` scope (or a broader one that includes it)._
Find email accounts by status, provider, address, domain, owner, or tag. Every field is optional; an empty body matches all.
# Get an email account
Source: https://docs.reply.io/api-reference/email-accounts/get-an-email-account
/api-reference/bundled.yaml get /v3/email-accounts/{id}
_Requires the `channels:read` scope (or a broader one that includes it)._
Get one email account in full: connection, safety, signature, opt-out and ramp-up settings, tags, and connection status.
# Get email account stats
Source: https://docs.reply.io/api-reference/email-accounts/get-email-account-stats
/api-reference/bundled.yaml get /v3/email-accounts/{id}/stats
_Requires the `channels:read` scope (or a broader one that includes it)._
See how much sending capacity one email account has left: sent today, the daily limit, and the all-time total.
# List email account tags
Source: https://docs.reply.io/api-reference/email-accounts/list-email-account-tags
/api-reference/bundled.yaml get /v3/email-accounts/tags
_Requires the `channels:read` scope (or a broader one that includes it)._
Get the email account tags available to you, each with its id, name, and color. Tags are referenced by name.
# List email accounts
Source: https://docs.reply.io/api-reference/email-accounts/list-email-accounts
/api-reference/bundled.yaml get /v3/email-accounts
_Requires the `channels:read` scope (or a broader one that includes it)._
Browse the email accounts you can send from. Pass my=true to see only your own. Paged with top and skip.
# Remove tags from an email account
Source: https://docs.reply.io/api-reference/email-accounts/remove-tags-from-an-email-account
/api-reference/bundled.yaml delete /v3/email-accounts/{id}/tags
_Requires the `channels:operate` scope (or a broader one that includes it)._
Take one or more tags off an email account by name. Only the link goes — the tag stays available on other accounts.
# Resume sending
Source: https://docs.reply.io/api-reference/email-accounts/resume-sending
/api-reference/bundled.yaml post /v3/email-accounts/{id}/resume-sending
_Requires the `channels:operate` scope (or a broader one that includes it)._
Clear a provider lock so an email account picks its sequences back up. Check sendingLockedByProvider first.
# Set default email account
Source: https://docs.reply.io/api-reference/email-accounts/set-default-email-account
/api-reference/bundled.yaml post /v3/email-accounts/{id}/set-default
_Requires the `channels:operate` scope (or a broader one that includes it)._
Choose which email account Reply pre-selects for sending. Exactly one is default, so this clears the flag on the last one.
# Test IMAP connectivity
Source: https://docs.reply.io/api-reference/email-accounts/test-imap-connectivity
/api-reference/bundled.yaml post /v3/email-accounts/test/imap
_Requires the `channels:operate` scope (or a broader one that includes it)._
Check IMAP receiving credentials before you commit. Nothing is created or changed, and a failed test still returns 200.
# Test SMTP connectivity
Source: https://docs.reply.io/api-reference/email-accounts/test-smtp-connectivity
/api-reference/bundled.yaml post /v3/email-accounts/test/smtp
_Requires the `channels:operate` scope (or a broader one that includes it)._
Check SMTP sending credentials before you commit. Nothing is created or changed, and a failed test still returns 200.
# Update a tag
Source: https://docs.reply.io/api-reference/email-accounts/update-a-tag
/api-reference/bundled.yaml put /v3/email-accounts/tags/{tagId}
_Requires the `channels:operate` scope (or a broader one that includes it)._
Rename an email account tag or change its color. The change applies everywhere the tag is already used.
# Update an email account
Source: https://docs.reply.io/api-reference/email-accounts/update-an-email-account
/api-reference/bundled.yaml patch /v3/email-accounts/{id}
_Requires the `channels:write` scope (or a broader one that includes it)._
Change specific settings on an email account without resending the whole record. Only the sections you include are updated.
# Estimate email validation
Source: https://docs.reply.io/api-reference/email-validations/estimate-email-validation
/api-reference/bundled.yaml post /v3/email-validations/estimate
_Requires the `contacts:read` scope (or a broader one that includes it)._
Size and price an email validation run before committing. Nothing is queued and no credits are held. Up to 10,000 contact ids.
# Schedule email validation
Source: https://docs.reply.io/api-reference/email-validations/schedule-email-validation
/api-reference/bundled.yaml post /v3/email-validations/schedule
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Start validating specific contacts' email addresses. Up to 10,000 ids; call estimate first for the counts and credit cost.
# Departments typeahead
Source: https://docs.reply.io/api-reference/live-data/departments-typeahead
/api-reference/bundled.yaml get /v3/live-data/filter-values/departments
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the department names a Live Data search can filter on. Each is a plain string you pass in the departments filter.
# Get a Live Data search
Source: https://docs.reply.io/api-reference/live-data/get-a-live-data-search
/api-reference/bundled.yaml get /v3/live-data/searches/{id}
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get one Live Data search by id — status, contacts found, credits used, target sequence and lists, plus its filters.
# Job titles typeahead
Source: https://docs.reply.io/api-reference/live-data/job-titles-typeahead
/api-reference/bundled.yaml get /v3/live-data/filter-values/job-titles
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the job titles a Live Data search can filter on. Each is a plain string you pass in the jobTitles filter.
# Live Data industries typeahead
Source: https://docs.reply.io/api-reference/live-data/live-data-industries-typeahead
/api-reference/bundled.yaml get /v3/live-data/filter-values/industries
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the industry names a Live Data search can filter on. Each is a plain string you pass in the industries filter.
# Locations typeahead
Source: https://docs.reply.io/api-reference/live-data/locations-typeahead
/api-reference/bundled.yaml get /v3/live-data/filter-values/locations
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the place names a Live Data search can filter on. Mixes countries, regions, and cities, with no separate country list.
# Seniorities typeahead
Source: https://docs.reply.io/api-reference/live-data/seniorities-typeahead
/api-reference/bundled.yaml get /v3/live-data/filter-values/seniorities
_Requires the `contacts:read` scope (or a broader one that includes it)._
Get the seniority levels a Live Data search can filter on. This filter takes a plain array of strings, unlike the others.
# Bulk add contacts to sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/bulk-add-contacts-to-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/contact-links/bulk
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Enroll contacts in a sequence — up to 10,000 ids per call. Set removeFromExisting to pull them out of their current ones.
# Bulk remove contacts from sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/bulk-remove-contacts-from-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/contact-links/bulk-delete
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Use this endpoint when you need to take several contacts out of a sequence in one call: list them in contactIds, at least one and with no duplicates. Each of them stops progressing through the steps and anything still scheduled for it in this sequence is cancelled, while the contacts themselves stay in your account and their memberships in other sequences are left alone. The response reports how many ids you requested, how many were removed, and removedIds listing exactly which ones came out — ids you sent that were not enrolled simply do not appear there.
# Count contacts in sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/count-contacts-in-sequence
/api-reference/bundled.yaml get /v3/sequences/{id}/contacts/count
_Requires the `sequences:read` scope (or a broader one that includes it)._
Count the contacts enrolled in a sequence — useful for sizing a paging loop before walking the list endpoint.
# Count filtered contacts in sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/count-filtered-contacts-in-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/contacts/filter/count
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `sequences:read` scope (or a broader one that includes it)._
Count a sequence's contacts that match a set of conditions, for example how many of them replied, without paging through them. It accepts the same request body as `POST /v3/sequences/{id}/contacts/filter`; `sortBy` and `sortDirection` are validated the same way but do not change the count.
# Filter contacts in sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/filter-contacts-in-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/contacts/filter
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `sequences:read` scope (or a broader one that includes it)._
Filter one sequence's contacts by what happened in that sequence and by contact fields, with a free-text search term and a sort order. Returns the same items as `GET /v3/sequences/{id}/contacts`, paged with the top and skip query parameters.
Conditions are joined with AND, one condition per field: an `operator` with its `value`, an `and` list of rules that must all match, or an `or` list of alternatives. `GET /v3/sequences/{id}/contacts/filter/fields` lists the fields, operators and values your workspace accepts here; counts, dates and statuses are those of this sequence.
# Get a contact in a sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/get-a-contact-in-a-sequence
/api-reference/bundled.yaml get /v3/sequences/{id}/contacts/{contact_id}
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get one contact's state inside a sequence: status, the step they're waiting on, when they were added, and opt-out.
# Get sequence preview for a contact
Source: https://docs.reply.io/api-reference/sequence-contacts/get-sequence-preview-for-a-contact
/api-reference/bundled.yaml get /v3/sequences/{sequence_id}/contacts/{contact_id}/preview
_Requires the `sequences:read` scope (or a broader one that includes it)._
See the messages one contact will receive from a sequence, rendered with their own data, one entry per messaging step.
# List contacts in sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/list-contacts-in-sequence
/api-reference/bundled.yaml get /v3/sequences/{id}/contacts
_Requires the `sequences:read` scope (or a broader one that includes it)._
See who's enrolled in a sequence and where each stands: status, current step, added date, opt-out, and call status.
# List contacts in sequence with extended state
Source: https://docs.reply.io/api-reference/sequence-contacts/list-contacts-in-sequence-with-extended-state
/api-reference/bundled.yaml get /v3/sequences/{id}/contacts/state
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get a compact view of a sequence's contacts, adding only the extra columns you ask for via additionalColumns.
# List sequence contact filter fields
Source: https://docs.reply.io/api-reference/sequence-contacts/list-sequence-contact-filter-fields
/api-reference/bundled.yaml get /v3/sequences/{id}/contacts/filter/fields
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `sequences:read` scope (or a broader one that includes it)._
List the fields `POST /v3/sequences/{id}/contacts/filter` accepts in your workspace, with each field's operators, value types and allowed values. Sequence fields (opened, status in sequence, current step) are read from this sequence; contact fields work as on `POST /v3/contacts/filter`, except `addingDate`, `sequenceIds` and `crmLinks`, which this route does not offer.
# Mark or unmark contacts as bounced in this sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/mark-or-unmark-contacts-as-bounced-in-this-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/contacts/set-bounced
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Record bounces against this sequence alone. Clearing the flag also requires resendEmails to say what to do next.
# Mark or unmark contacts as replied in this sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/mark-or-unmark-contacts-as-replied-in-this-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/contacts/set-replied
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Record replies that reached you elsewhere against this sequence alone. Marking as replied finishes the contact here.
# Remove contact from sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/remove-contact-from-sequence
/api-reference/bundled.yaml delete /v3/sequences/{id}/contact-links/{contact_id}
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Take one contact out of a sequence. They stop progressing, but the contact and their history stay in your account.
# Reset manual edits in a sequence preview
Source: https://docs.reply.io/api-reference/sequence-contacts/reset-manual-edits-in-a-sequence-preview
/api-reference/bundled.yaml post /v3/sequences/{sequence_id}/contacts/{contact_id}/preview/reset
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Discard the copy held for one contact — generated messages and hand edits alike — and fall back to the step templates.
# Set contacts' status in this sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/set-contacts-status-in-this-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/contacts/set-status-in-sequence
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Set contacts to active, paused, finished, or outOfOffice in this sequence alone. Up to 100 ids, with no duplicates. Active, paused and outOfOffice can be set only by the sequence owner; finished can be set by any team member who can see the sequence.
# Set the sending mailbox for contacts in this sequence
Source: https://docs.reply.io/api-reference/sequence-contacts/set-the-sending-mailbox-for-contacts-in-this-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/contacts/set-email-account
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Repoint contacts already in this sequence at a different sending mailbox. Up to 100 ids; the mailbox must already be linked.
# Assign email account to sequence
Source: https://docs.reply.io/api-reference/sequence-email-accounts/assign-email-account-to-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/email-account-links
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Add one more mailbox for a sequence to send from. A sequence can hold up to 100 linked accounts, and the call is idempotent.
# List email accounts in sequence
Source: https://docs.reply.io/api-reference/sequence-email-accounts/list-email-accounts-in-sequence
/api-reference/bundled.yaml get /v3/sequences/{id}/email-accounts
_Requires the `sequences:read` scope (or a broader one that includes it)._
See which email accounts a sequence sends from, each with its address, sender name, daily limit, and connection status.
# Set sequence email accounts
Source: https://docs.reply.io/api-reference/sequence-email-accounts/set-sequence-email-accounts
/api-reference/bundled.yaml put /v3/sequences/{id}/email-account-links
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Replace a sequence's sending mailboxes with an exact list. Accounts missing from it are unlinked; an empty array clears all.
# Bulk assign sequences to a folder
Source: https://docs.reply.io/api-reference/sequence-folders/bulk-assign-sequences-to-a-folder
/api-reference/bundled.yaml post /v3/sequence-folders/{id}/sequence-links/bulk
_Requires the `sequences:operate` scope (or a broader one that includes it)._
File up to 1000 sequences into a folder in one call. A sequence belongs to one folder, so this moves it out of any other.
# Bulk unassign sequences from a folder
Source: https://docs.reply.io/api-reference/sequence-folders/bulk-unassign-sequences-from-a-folder
/api-reference/bundled.yaml post /v3/sequence-folders/{id}/sequence-links/bulk-delete
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Take up to 1000 sequences out of a folder without deleting them — they stay in your account and become unfiled.
# Create a sequence folder
Source: https://docs.reply.io/api-reference/sequence-folders/create-a-sequence-folder
/api-reference/bundled.yaml post /v3/sequence-folders
_Requires the `sequences:write` scope (or a broader one that includes it)._
Create a folder to group sequences under. The name is capped at 128 characters and must be unique among yours.
# Delete a sequence folder
Source: https://docs.reply.io/api-reference/sequence-folders/delete-a-sequence-folder
/api-reference/bundled.yaml delete /v3/sequence-folders/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete one of your sequence folders. The sequences inside are kept and simply become unfiled, ready to refile.
# Get a sequence folder
Source: https://docs.reply.io/api-reference/sequence-folders/get-a-sequence-folder
/api-reference/bundled.yaml get /v3/sequence-folders/{id}
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get one sequence folder by id, with its name. Folders are personal, so someone else's id reports not found.
# List all sequence folders
Source: https://docs.reply.io/api-reference/sequence-folders/list-all-sequence-folders
/api-reference/bundled.yaml get /v3/sequence-folders
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get the folders you have for organizing sequences, sorted by name, in one array. Folders are personal to you.
# List sequences in a folder
Source: https://docs.reply.io/api-reference/sequence-folders/list-sequences-in-a-folder
/api-reference/bundled.yaml get /v3/sequence-folders/{id}/sequences
_Requires the `sequences:read` scope (or a broader one that includes it)._
See which sequences are filed in a folder. Paged with top and skip, sortable by title, created, or people.
# Update a sequence folder
Source: https://docs.reply.io/api-reference/sequence-folders/update-a-sequence-folder
/api-reference/bundled.yaml put /v3/sequence-folders/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Rename one of your sequence folders. Only the name changes; the sequences filed in it stay where they are.
# Bulk create sequence steps
Source: https://docs.reply.io/api-reference/sequence-steps/bulk-create-sequence-steps
/api-reference/bundled.yaml post /v3/sequences/{id}/steps/bulk
**Breaking change from early November 2026.** Condition steps take `conditions` in the filter condition format (`field` with `operator` and `value`, or `and` / `or` lists) instead of `{property, rules}` templates.
_Requires the `sequences:write` scope (or a broader one that includes it)._
Add several steps to a sequence in one call, processed in order, each appended after the one before it.
# Bulk create step variants
Source: https://docs.reply.io/api-reference/sequence-steps/bulk-create-step-variants
/api-reference/bundled.yaml post /v3/sequences/{id}/steps/{step_id}/variants/bulk
_Requires the `sequences:write` scope (or a broader one that includes it)._
Add several text variants to one step in a single call. They're appended in the order you send them.
# Bulk delete sequence steps
Source: https://docs.reply.io/api-reference/sequence-steps/bulk-delete-sequence-steps
/api-reference/bundled.yaml post /v3/sequences/{id}/steps/bulk-delete
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete up to 100 steps from a sequence at once. Each step's children re-attach to its parent as it goes.
# Bulk delete step variants
Source: https://docs.reply.io/api-reference/sequence-steps/bulk-delete-step-variants
/api-reference/bundled.yaml post /v3/sequences/{id}/steps/{step_id}/variants/bulk-delete
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete up to 100 variants from one step at once. Each is handled on its own, so the ones that can go still go.
# Create a sequence step
Source: https://docs.reply.io/api-reference/sequence-steps/create-a-sequence-step
/api-reference/bundled.yaml post /v3/sequences/{id}/steps
**Breaking change from early November 2026.** Condition steps take and return `conditions` in the filter condition format (`field` with `operator` and `value`, or `and` / `or` lists) instead of `{property, rules}` templates.
_Requires the `sequences:write` scope (or a broader one that includes it)._
Add a step to a sequence. `type` picks what it does — `email`, `linkedIn`, `call`, `sms`, `condition`, and more; `linkedIn` adds `actionType`.
# Create a step variant
Source: https://docs.reply.io/api-reference/sequence-steps/create-a-step-variant
/api-reference/bundled.yaml post /v3/sequences/{id}/steps/{step_id}/variants
_Requires the `sequences:write` scope (or a broader one that includes it)._
Add another variant so a step rotates between bodies. Text variants use JSON; LinkedIn voice uses multipart form data.
A LinkedIn voice message step needs at least one enabled variant, and every enabled variant needs a recording.
# Delete a sequence step
Source: https://docs.reply.io/api-reference/sequence-steps/delete-a-sequence-step
/api-reference/bundled.yaml delete /v3/sequences/{id}/steps/{step_id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete a step from a sequence. Children re-attach to its parent by default; condition steps need a mode for the branches.
# Delete a step variant
Source: https://docs.reply.io/api-reference/sequence-steps/delete-a-step-variant
/api-reference/bundled.yaml delete /v3/sequences/{id}/steps/{step_id}/variants/{variant_id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete one variant from a step for good. A variant already sent to a contact can't go, and a step keeps one enabled.
# Disable step variants
Source: https://docs.reply.io/api-reference/sequence-steps/disable-step-variants
/api-reference/bundled.yaml post /v3/sequences/{id}/steps/{step_id}/disable
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Take variants out of rotation without deleting them — handy for stopping one arm of an A/B test. Toggled one by one.
# Enable step variants
Source: https://docs.reply.io/api-reference/sequence-steps/enable-step-variants
/api-reference/bundled.yaml post /v3/sequences/{id}/steps/{step_id}/enable
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Bring variants of a step back into rotation after they were switched off. Each one is toggled on its own.
# Get a sequence step
Source: https://docs.reply.io/api-reference/sequence-steps/get-a-sequence-step
/api-reference/bundled.yaml get /v3/sequences/{id}/steps/{step_id}
**Breaking change from early November 2026.** Condition steps return `conditions` in the filter condition format (`field` with `operator` and `value`, or `and` / `or` lists) instead of `{property, rules}` templates.
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get one step of a sequence by id. Read `type` — and `actionType` for `linkedIn` — to know which other fields to expect.
# List all sequence steps
Source: https://docs.reply.io/api-reference/sequence-steps/list-all-sequence-steps
/api-reference/bundled.yaml get /v3/sequences/{id}/steps
**Breaking change from early November 2026.** Condition steps return `conditions` in the filter condition format (`field` with `operator` and `value`, or `and` / `or` lists) instead of `{property, rules}` templates.
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get every step in a sequence. Read type first to know the shape, and parentId to see how the steps chain together.
Steps are ordered by their position number in the sequence.
# List condition step fields
Source: https://docs.reply.io/api-reference/sequence-steps/list-condition-step-fields
/api-reference/bundled.yaml get /v3/sequences/steps/condition/fields
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `sequences:read` scope (or a broader one that includes it)._
List the fields a condition step's `conditions` accept in your workspace, with each field's operators, value types and allowed values. Stage names and custom fields are your workspace's own; step fields refer to the sequence the step belongs to.
# List contact filter properties
Source: https://docs.reply.io/api-reference/sequence-steps/list-contact-filter-properties
/api-reference/bundled.yaml get /v3/sequences/steps/contact-filter-properties
**Breaking change from early November 2026.** This endpoint is removed; use `GET /v3/sequences/steps/condition/fields` instead.
_Requires the `sequences:read` scope (or a broader one that includes it)._
See which contact properties a condition step can test, with the operators each accepts and any allowed values.
# List step variants
Source: https://docs.reply.io/api-reference/sequence-steps/list-step-variants
/api-reference/bundled.yaml get /v3/sequences/{id}/steps/{step_id}/variants
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get the variants a step rotates between, ordered by `id`, each with its letter, subject, message, enabled flag, and whether it has attachments.
# Update a sequence step
Source: https://docs.reply.io/api-reference/sequence-steps/update-a-sequence-step
/api-reference/bundled.yaml put /v3/sequences/{id}/steps/{step_id}
**Breaking change from early November 2026.** Condition steps take and return `conditions` in the filter condition format (`field` with `operator` and `value`, or `and` / `or` lists) instead of `{property, rules}` templates.
_Requires the `sequences:write` scope (or a broader one that includes it)._
Change what a step does. Send the whole step; give each variant an id, or it's added as new, and omitted ones are dropped. An omitted `delayInMinutes` (and `waitInMinutes` on a condition step) keeps the current value.
# Update a step variant
Source: https://docs.reply.io/api-reference/sequence-steps/update-a-step-variant
/api-reference/bundled.yaml put /v3/sequences/{id}/steps/{step_id}/variants/{variant_id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Change one variant of a step. Text variants use JSON; LinkedIn voice message variants use multipart form data.
A LinkedIn voice message step needs at least one enabled variant, and every enabled variant needs a recording.
# Archive a sequence
Source: https://docs.reply.io/api-reference/sequences/archive-a-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/archive
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Put a sequence aside without deleting it. Pause it first, and note that archiving removes every contact currently in it.
# Bulk archive sequences
Source: https://docs.reply.io/api-reference/sequences/bulk-archive-sequences
/api-reference/bundled.yaml post /v3/sequences/archive
_Requires the `sequences:write` scope (or a broader one that includes it)._
Archive up to 1000 sequences in one call. Each must be paused or never started, and its contacts are taken out.
# Bulk change sequence owner
Source: https://docs.reply.io/api-reference/sequences/bulk-change-sequence-owner
/api-reference/bundled.yaml post /v3/sequences/batch/owner
_Requires the `sequences:write` scope (or a broader one that includes it)._
Hand up to 1000 sequences to another team member. Reassigning is restricted to the team owner outside an organization.
# Bulk delete sequences
Source: https://docs.reply.io/api-reference/sequences/bulk-delete-sequences
/api-reference/bundled.yaml post /v3/sequences/bulk-delete
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete up to 1000 sequences in one call. Their contacts stay in your account, but a deleted sequence can't be restored.
# Bulk pause sequences
Source: https://docs.reply.io/api-reference/sequences/bulk-pause-sequences
/api-reference/bundled.yaml post /v3/sequences/pause
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Pause up to 1000 running sequences in one call. Only currently active ones are paused; the rest are reported back.
# Bulk start sequences
Source: https://docs.reply.io/api-reference/sequences/bulk-start-sequences
/api-reference/bundled.yaml post /v3/sequences/start
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Start up to 1000 sequences in one call. Each needs contacts, a connected email account, and a schedule with sending hours.
# Bulk unarchive sequences
Source: https://docs.reply.io/api-reference/sequences/bulk-unarchive-sequences
/api-reference/bundled.yaml post /v3/sequences/unarchive
_Requires the `sequences:write` scope (or a broader one that includes it)._
Bring up to 1000 sequences out of the archive. Each returns to its old status, but its contacts are not put back.
# Change sequence owner
Source: https://docs.reply.io/api-reference/sequences/change-sequence-owner
/api-reference/bundled.yaml put /v3/sequences/{id}/owner
_Requires the `sequences:write` scope (or a broader one that includes it)._
Hand one sequence to another team member by user id. Reassigning is restricted to the team owner outside an organization.
# Count sequences
Source: https://docs.reply.io/api-reference/sequences/count-sequences
/api-reference/bundled.yaml get /v3/sequences/count
_Requires the `sequences:read` scope (or a broader one that includes it)._
Count the sequences matching a filter without fetching them. Takes the same filters as the list endpoint.
# Create a sequence
Source: https://docs.reply.io/api-reference/sequences/create-a-sequence
/api-reference/bundled.yaml post /v3/sequences
**Breaking change from early November 2026.** Inline condition steps take and return `conditions` in the filter condition format instead of `{property, rules}` templates; a condition step without conditions returns 400.
_Requires the `sequences:write` scope (or a broader one that includes it)._
Create a sequence to send from. Name and at least one step are required — a sequence with no steps has nothing to send and cannot be started. Omit scheduleId to fall back to your default schedule. Omit `settings`, or any field in it, to use that field's default.
# Create a sequence from a template
Source: https://docs.reply.io/api-reference/sequences/create-a-sequence-from-a-template
/api-reference/bundled.yaml post /v3/sequences/create-from-template
_Requires the `sequences:write` scope (or a broader one that includes it)._
Build a new sequence from one of your saved templates. Pass templateId, and optionally a folder to file it into.
# Delete a sequence
Source: https://docs.reply.io/api-reference/sequences/delete-a-sequence
/api-reference/bundled.yaml delete /v3/sequences/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete a sequence by id. Its contacts stay in your account, but the sequence can't be restored — archive it instead.
# Get a sequence
Source: https://docs.reply.io/api-reference/sequences/get-a-sequence
/api-reference/bundled.yaml get /v3/sequences/{id}
**Breaking change from early November 2026.** Condition steps in `steps` return `conditions` in the filter condition format instead of `{property, rules}` templates.
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get one sequence in full: name, status, owner, schedule, settings, connected accounts, and its complete list of steps.
# Get sequence email stats
Source: https://docs.reply.io/api-reference/sequences/get-sequence-email-stats
/api-reference/bundled.yaml post /v3/sequences/{id}/stats/emails
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `sequences:read` scope (or a broader one that includes it)._
Compare A/B variants: get one sequence's email stats per step and per variant, as on its Stats → Email tab. Set the window with a preset or from and to, not both; if omitted give you the last week.
# Get sequence LinkedIn stats
Source: https://docs.reply.io/api-reference/sequences/get-sequence-linkedin-stats
/api-reference/bundled.yaml post /v3/sequences/{id}/stats/linkedin
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `sequences:read` scope (or a broader one that includes it)._
Compare A/B variants: get one sequence's LinkedIn stats per step and per variant, as on its Stats → LinkedIn tab. Set the window with a preset or from and to, not both; if omitted give you the last week.
# Get sequence stats
Source: https://docs.reply.io/api-reference/sequences/get-sequence-stats
/api-reference/bundled.yaml post /v3/sequences/{id}/stats
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get engagement figures for one sequence. Set the window with a date range preset or an explicit from and to, not both.
# Get stats for all sequences
Source: https://docs.reply.io/api-reference/sequences/get-stats-for-all-sequences
/api-reference/bundled.yaml post /v3/sequences/stats
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get email and LinkedIn engagement per sequence. The window is capped at 31 days, as a preset or an explicit from and to.
# List all sequences
Source: https://docs.reply.io/api-reference/sequences/list-all-sequences
/api-reference/bundled.yaml get /v3/sequences
_Requires the `sequences:read` scope (or a broader one that includes it)._
Browse the sequences you can work with. Paged with top and skip, and filterable by status, owner, folder, and name.
# Pause a sequence
Source: https://docs.reply.io/api-reference/sequences/pause-a-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/pause
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Stop a running sequence sending further steps while keeping it and its contacts in place. It must have started once.
# Save a sequence as a template
Source: https://docs.reply.io/api-reference/sequences/save-a-sequence-as-a-template
/api-reference/bundled.yaml post /v3/sequences/{id}/save-as-template
_Requires the `sequences:write` scope (or a broader one that includes it)._
Reuse a sequence's structure for future ones. Name the template and set scope to organization to share it wider.
# Start a sequence
Source: https://docs.reply.io/api-reference/sequences/start-a-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/start
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Start a sequence or resume a paused one. It needs contacts, a connected email account, and a schedule with sending hours.
# Unarchive a sequence
Source: https://docs.reply.io/api-reference/sequences/unarchive-a-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/unarchive
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Bring an archived sequence back to its old status. Its contacts aren't put back, so add them again before starting.
# Update a sequence
Source: https://docs.reply.io/api-reference/sequences/update-a-sequence
/api-reference/bundled.yaml patch /v3/sequences/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Change part of a sequence and leave the rest. settings merges key by key; account lists replace what's there.
# Cancel a direct send
Source: https://docs.reply.io/api-reference/direct-outreach/cancel-a-direct-send
/api-reference/bundled.yaml post /v3/direct-sends/{reference}/cancel
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Cancel a direct send that is still `queued` or `waitingForSchedule`, by its `reference`, or a LinkedIn send for later (`linkedin-scheduled-`) that is `sending` but still waits in the account's queue. Answers the send in the `cancelled` state. Cancelling a send already cancelled answers it again, so the call is safe to repeat.
A send that is `sending` or `sent` answers 409 `directSend.alreadySent`, and one that has `failed` answers 409 `directSend.alreadyFailed`. A LinkedIn send for later (`linkedin-scheduled-`) that is being handed to the account's queue, or that the account has started, answers 409 `directSend.alreadySending`. A send can start the moment it is due, so a cancel made very close to `sendAfter` may find it already gone.
An unconfirmed cancel of a send not yet gone answers 503 `directSend.cancelNotConfirmed`; retry it. For a LinkedIn send for later that also covers one being picked up at that moment while it still reads `queued` or `waitingForSchedule`, and one waiting in the account's queue whose cancel met a concurrent change.
An email send made by a teammate can be cancelled when you may act for that teammate, otherwise it answers 403 `directSend.notOwned`. A LinkedIn send can be cancelled by every teammate who can see its LinkedIn account.
# Get a direct send
Source: https://docs.reply.io/api-reference/direct-outreach/get-a-direct-send
/api-reference/bundled.yaml get /v3/direct-sends/{reference}
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `contacts:read` scope (or a broader one that includes it)._
Read where a direct email or LinkedIn send stands, by the `reference` its send route answered with. A send stays readable for at least 30 days after it was made.
Read `state` first: `sentAt` is set only once the send has gone out, and `estimatedSendAt` only while it waits for its schedule. A send made with `scheduleId` when the schedule was open or opened within the next ten minutes was queued for that moment at once and reads `queued` with `sendAfter`; one whose schedule opened later reads `waitingForSchedule` with `estimatedSendAt` until the schedule opens. A LinkedIn send for later reads `sending` from the moment it is handed to the account's queue until it has gone out or failed. A `failed` send carries `failureReason`, a sentence, and `failureCode` when the failure has one; see the model for the values. An email that has gone out carries `renderedSubject` and `renderedBody` as sent, with the signature and the tracking; both are null when the sent message can no longer be read.
An email send made by a teammate is readable when you may act for that teammate. A LinkedIn send is readable by every teammate who can see its LinkedIn account. A send of another team answers 404.
# Send a direct email to a contact
Source: https://docs.reply.io/api-reference/direct-outreach/send-a-direct-email-to-a-contact
/api-reference/bundled.yaml post /v3/contacts/{id}/send-direct-email
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Send a one-off email to a contact outside any sequence, from a connected account. The reply is still tracked on the contact.
Without `sendAfter` or `scheduleId` the email is sent within the request and is not added to the sending queue; with `sendAfter`, the email waits until then.
With `scheduleId` the email goes out at that schedule's next opening, from `sendAfter` when given. The schedule is any you can read with `GET /v3/schedules/{id}`; its active days and time ranges decide when it opens, and its holidays are skipped when it excludes them. `useContactTimeZone` reads the schedule in the contact's time zone (`true`) or in the schedule's own (`false`); absent, as the schedule is set, and a schedule set to the contact's time zone reads its own for a contact with none, as in a sequence. When the schedule is open now or opens within the next ten minutes, the send is queued for that moment at once and answers `queued` with `sendAfter`. Otherwise it is in the `waitingForSchedule` state until the schedule opens, goes out within about 10 minutes of the opening, and the answer's `estimatedSendAt` says when that is, as read at acceptance. A waiting send does not expire, and a schedule changed meanwhile is read as it is when it opens; if the schedule is deleted, or `useContactTimeZone` is `true` and the contact no longer has a time zone, the send fails with `failureCode` `contact.scheduleNotFound` or `contact.contactTimeZoneMissing`. **Coming soon (mid November 2026).** A schedule left with no active day that has a time range fails it with `failureCode` `contact.scheduleHasNoSlot`. Cancel a waiting send with `POST /v3/direct-sends/{reference}/cancel`.
`subject` and `body` are templates rendered for the contact, with the same variables as a sequence step. A template that uses variables with no value for the contact answers 400 `contact.missingVariables`, naming them in `missingVariables`; any other template that cannot be rendered answers 400 `contact.renderingFailed`. An email accepted for later is checked the same way when it is accepted, and rendered again, with the contact's values of that moment, when it goes out. AI variables are resolved only when the email goes out.
`trackLinks` and `trackOpens` turn on link-click and open tracking for this email, as on a sequence step; both are off when absent.
Direct emails are not subject to the email account's daily sending limit or sending delay, and they do not count toward that daily limit, so they do not reduce the number of emails your sequences can send from the account that day. If you send a large number of direct emails from one account, pace them on your side to protect the account's deliverability. Only the general API rate limit applies to this endpoint.
# Send a LinkedIn connection request to a contact
Source: https://docs.reply.io/api-reference/direct-outreach/send-a-linkedin-connection-request-to-a-contact
/api-reference/bundled.yaml post /v3/contacts/{id}/send-direct-linkedin-connect
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Invite a contact to connect on LinkedIn outside any sequence. Pass the connected account to send from, plus an optional note.
Pass `sendAfter` to send it later, at most 30 days ahead; a moment already past sends now. **Coming soon (mid November 2026).** Pass `scheduleId` to send it at that schedule's next opening, from `sendAfter` when given; without either, the send is made within the request. A send for later waits on Reply's side and goes to the LinkedIn account's queue only once it is due. It answers `queued` with `sendAfter`, or `waitingForSchedule` with `estimatedSendAt`, and a `linkedin-scheduled-` reference that stays the send's reference for its whole life.
**Coming soon (mid November 2026).** A send for later is not refused for the account's limits when it is accepted. Once it is due, an attempt blocked by the account's daily allowance for the action, or LinkedIn's limit on the account's connection requests, is retried, within the schedule's open hours when it has one, until `retryWindowMinutes` (90 by default) after it was due; the send then fails with the code of what blocked it, as `failureCode`.
**Coming soon (mid November 2026).** A send for later whose contact is already connected when it is due ends `failed` with `failureCode` `directLinkedIn.alreadyConnected`, and one whose invitation to the contact is still pending then ends `failed` with `directLinkedIn.notConnected`, the codes a request made now answers with. Nothing is sent.
Read the send's state with `GET /v3/direct-sends/{reference}`, or cancel it while it is `queued` or `waitingForSchedule` with `POST /v3/direct-sends/{reference}/cancel`. **Coming soon (mid November 2026).** A send for later can be cancelled until the LinkedIn account starts it, also once it waits in the account's queue.
While LinkedIn is limiting the account's connection requests, no request is sent. A request made now answers 429 `directLinkedIn.weeklyLimitReached` naming the failed send, and one that waits behind the account's other actions ends `failed` with `failureCode` `directLinkedIn.weeklyLimitReached` when its turn comes. **Coming soon (mid November 2026).** A request for later waits for the limit to end within its retry window, and ends `failed` with that code when the limit outlasts the window or begins after the request was handed to the account's queue. Send again once the account is no longer limited.
# Send a LinkedIn InMail to a contact
Source: https://docs.reply.io/api-reference/direct-outreach/send-a-linkedin-inmail-to-a-contact
/api-reference/bundled.yaml post /v3/contacts/{id}/send-direct-linkedin-inmail
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Reach a contact you aren't connected with via LinkedIn InMail. The sending account needs Sales Navigator and InMail credits.
Pass `sendAfter` to send it later, at most 30 days ahead; a moment already past sends now. **Coming soon (mid November 2026).** Pass `scheduleId` to send it at that schedule's next opening, from `sendAfter` when given; without either, the send is made within the request. A send for later waits on Reply's side and goes to the LinkedIn account's queue only once it is due. It answers `queued` with `sendAfter`, or `waitingForSchedule` with `estimatedSendAt`, and a `linkedin-scheduled-` reference that stays the send's reference for its whole life.
**Coming soon (mid November 2026).** A send for later is not refused for the account's limits when it is accepted. Once it is due, an attempt blocked by the account's daily allowance for the action is retried, within the schedule's open hours when it has one, until `retryWindowMinutes` (90 by default) after it was due; the send then fails with the code of what blocked it, as `failureCode`.
Read the send's state with `GET /v3/direct-sends/{reference}`, or cancel it while it is `queued` or `waitingForSchedule` with `POST /v3/direct-sends/{reference}/cancel`. **Coming soon (mid November 2026).** A send for later can be cancelled until the LinkedIn account starts it, also once it waits in the account's queue.
# Send a LinkedIn message to a contact
Source: https://docs.reply.io/api-reference/direct-outreach/send-a-linkedin-message-to-a-contact
/api-reference/bundled.yaml post /v3/contacts/{id}/send-direct-linkedin-message
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Send a one-off LinkedIn message to a contact you're already connected with, from one of your connected accounts.
Pass `sendAfter` to send it later, at most 30 days ahead; a moment already past sends now. **Coming soon (mid November 2026).** Pass `scheduleId` to send it at that schedule's next opening, from `sendAfter` when given; without either, the send is made within the request. A send for later waits on Reply's side and goes to the LinkedIn account's queue only once it is due. It answers `queued` with `sendAfter`, or `waitingForSchedule` with `estimatedSendAt`, and a `linkedin-scheduled-` reference that stays the send's reference for its whole life.
**Coming soon (mid November 2026).** A send for later is not refused for the account's limits when it is accepted. Once it is due, an attempt blocked by the account's daily allowance for the action is retried, within the schedule's open hours when it has one, until `retryWindowMinutes` (90 by default) after it was due; the send then fails with the code of what blocked it, as `failureCode`.
Read the send's state with `GET /v3/direct-sends/{reference}`, or cancel it while it is `queued` or `waitingForSchedule` with `POST /v3/direct-sends/{reference}/cancel`. **Coming soon (mid November 2026).** A send for later can be cancelled until the LinkedIn account starts it, also once it waits in the account's queue.
# Send a LinkedIn voice message to a contact
Source: https://docs.reply.io/api-reference/direct-outreach/send-a-linkedin-voice-message-to-a-contact
/api-reference/bundled.yaml post /v3/contacts/{id}/send-direct-linkedin-voice
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Send a recorded voice message on LinkedIn. Upload the audio first and pass the id it returns as voiceAttachmentId.
Pass `sendAfter` to send it later, at most 30 days ahead; a moment already past sends now. **Coming soon (mid November 2026).** Pass `scheduleId` to send it at that schedule's next opening, from `sendAfter` when given; without either, the send is made within the request. A send for later waits on Reply's side and goes to the LinkedIn account's queue only once it is due. It answers `queued` with `sendAfter`, or `waitingForSchedule` with `estimatedSendAt`, and a `linkedin-scheduled-` reference that stays the send's reference for its whole life.
**Coming soon (mid November 2026).** A send for later is not refused for the account's limits when it is accepted. Once it is due, an attempt blocked by the account's daily allowance for the action is retried, within the schedule's open hours when it has one, until `retryWindowMinutes` (90 by default) after it was due; the send then fails with the code of what blocked it, as `failureCode`.
Read the send's state with `GET /v3/direct-sends/{reference}`, or cancel it while it is `queued` or `waitingForSchedule` with `POST /v3/direct-sends/{reference}/cancel`. **Coming soon (mid November 2026).** A send for later can be cancelled until the LinkedIn account starts it, also once it waits in the account's queue.
# Send an AI-generated LinkedIn voice message to a contact
Source: https://docs.reply.io/api-reference/direct-outreach/send-an-ai-generated-linkedin-voice-message-to-a-contact
/api-reference/bundled.yaml post /v3/contacts/{id}/send-direct-linkedin-ai-voice
_Requires the `contacts:operate` scope (or a broader one that includes it)._
Turn a written script into a voice message and send it on LinkedIn. The sending account needs a voice profile.
Pass `sendAfter` to send it later, at most 30 days ahead; a moment already past sends now. **Coming soon (mid November 2026).** Pass `scheduleId` to send it at that schedule's next opening, from `sendAfter` when given; without either, the send is made within the request. A send for later waits on Reply's side and goes to the LinkedIn account's queue only once it is due. It answers `queued` with `sendAfter`, or `waitingForSchedule` with `estimatedSendAt`, and a `linkedin-scheduled-` reference that stays the send's reference for its whole life.
**Coming soon (mid November 2026).** A send for later is not refused for the account's limits when it is accepted. Once it is due, an attempt blocked by the account's daily allowance for the action is retried, within the schedule's open hours when it has one, until `retryWindowMinutes` (90 by default) after it was due; the send then fails with the code of what blocked it, as `failureCode`.
Read the send's state with `GET /v3/direct-sends/{reference}`, or cancel it while it is `queued` or `waitingForSchedule` with `POST /v3/direct-sends/{reference}/cancel`. **Coming soon (mid November 2026).** A send for later can be cancelled until the LinkedIn account starts it, also once it waits in the account's queue.
# Clone an email template
Source: https://docs.reply.io/api-reference/email-templates/clone-an-email-template
/api-reference/bundled.yaml post /v3/email-templates/{id}/clone
_Requires the `sequences:write` scope (or a broader one that includes it)._
Copy a template so you can change it without touching the original. The copy keeps the folder and is named Copy of…
# Create an email template
Source: https://docs.reply.io/api-reference/email-templates/create-an-email-template
/api-reference/bundled.yaml post /v3/email-templates
_Requires the `sequences:write` scope (or a broader one that includes it)._
Store a reusable email as a template. Name, body, and folderType are required; folderType is personal or team.
# Create an email template folder
Source: https://docs.reply.io/api-reference/email-templates/create-an-email-template-folder
/api-reference/bundled.yaml post /v3/email-template-folders
_Requires the `sequences:write` scope (or a broader one that includes it)._
Create a folder to group email templates under. Pick personal or team, with names up to 128 characters and unique per type.
# Delete an email template
Source: https://docs.reply.io/api-reference/email-templates/delete-an-email-template
/api-reference/bundled.yaml delete /v3/email-templates/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Permanently delete an email template by id. There is no undo, and a successful call returns no content.
# Delete an email template folder
Source: https://docs.reply.io/api-reference/email-templates/delete-an-email-template-folder
/api-reference/bundled.yaml delete /v3/email-template-folders/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete an email template folder, passing its foldertype. Team folders must be emptied first; personal ones just unfile.
# Get an email template
Source: https://docs.reply.io/api-reference/email-templates/get-an-email-template
/api-reference/bundled.yaml get /v3/email-templates/{id}
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get one email template in full: name, subject, body, folder, attachments, and its created and updated timestamps.
# Get an email template folder
Source: https://docs.reply.io/api-reference/email-templates/get-an-email-template-folder
/api-reference/bundled.yaml get /v3/email-template-folders/{id}
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get one email template folder by id. The foldertype query parameter is required: personal, team, community, or organization.
# Get template variables
Source: https://docs.reply.io/api-reference/email-templates/get-template-variables
/api-reference/bundled.yaml get /v3/email-templates/variables
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get the variables you can place in a template subject or body, grouped by category, each with its key and what it fills in.
# List email template folders
Source: https://docs.reply.io/api-reference/email-templates/list-email-template-folders
/api-reference/bundled.yaml get /v3/email-template-folders
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get every folder available for organizing email templates — personal, team, community, and organization — in one array.
# List email templates
Source: https://docs.reply.io/api-reference/email-templates/list-email-templates
/api-reference/bundled.yaml get /v3/email-templates
_Requires the `sequences:read` scope (or a broader one that includes it)._
Browse the email templates you can use: your own, your team's, and any shared with you. Paged with top and skip.
# Move an email template
Source: https://docs.reply.io/api-reference/email-templates/move-an-email-template
/api-reference/bundled.yaml post /v3/email-templates/{id}/move
_Requires the `sequences:write` scope (or a broader one that includes it)._
File a template under a different folder. Send folderId with a matching folderType of personal or team; the folder must exist.
# Render an email template
Source: https://docs.reply.io/api-reference/email-templates/render-an-email-template
/api-reference/bundled.yaml post /v3/email-templates/{id}/render
_Requires the `sequences:operate` scope (or a broader one that includes it)._
See how a template reads for a particular contact, with their field values filled in. contactId is required.
# Send a test email
Source: https://docs.reply.io/api-reference/email-templates/send-a-test-email
/api-reference/bundled.yaml post /v3/email-templates/{id}/send-test
_Requires the `sequences:operate` scope (or a broader one that includes it)._
See how a template lands in a real inbox. Both the destination address and the sending account id are required.
# Share an email template folder
Source: https://docs.reply.io/api-reference/email-templates/share-an-email-template-folder
/api-reference/bundled.yaml post /v3/email-template-folders/{id}/share
_Requires the `sequences:write` scope (or a broader one that includes it)._
Move one of your personal template folders, and everything in it, across to your team. No request body needed.
# Update an email template
Source: https://docs.reply.io/api-reference/email-templates/update-an-email-template
/api-reference/bundled.yaml put /v3/email-templates/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Change a template's content. Name and body are required every time, so send it in full — anything left out is overwritten.
# Update an email template folder
Source: https://docs.reply.io/api-reference/email-templates/update-an-email-template-folder
/api-reference/bundled.yaml put /v3/email-template-folders/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Rename an email template folder, passing its foldertype. Templates stay put, and default folders cannot be renamed.
# Upload a template attachment
Source: https://docs.reply.io/api-reference/email-templates/upload-a-template-attachment
/api-reference/bundled.yaml post /v3/email-template-attachments
Upload a file to use as an email template attachment. Returns the attachment id you pass when creating or updating a template.
# Create a holiday calendar
Source: https://docs.reply.io/api-reference/holiday-calendars/create-a-holiday-calendar
/api-reference/bundled.yaml post /v3/holiday-calendars
_Requires the `sequences:write` scope (or a broader one that includes it)._
Build your own holiday calendar from dates you supply. Each entry needs a name, a start date, and an end date.
# Delete a holiday calendar
Source: https://docs.reply.io/api-reference/holiday-calendars/delete-a-holiday-calendar
/api-reference/bundled.yaml delete /v3/holiday-calendars/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete a custom calendar you created. It detaches from every schedule that used it; Reply's country calendars can't go.
# Export a holiday calendar as CSV
Source: https://docs.reply.io/api-reference/holiday-calendars/export-a-holiday-calendar-as-csv
/api-reference/bundled.yaml get /v3/holiday-calendars/{id}/export-csv
_Requires the `sequences:read` scope (or a broader one that includes it)._
Download a holiday calendar as CSV, listing each holiday's name and dates as yyyy-MM-dd. The file is named after it.
# Get a holiday calendar
Source: https://docs.reply.io/api-reference/holiday-calendars/get-a-holiday-calendar
/api-reference/bundled.yaml get /v3/holiday-calendars/{id}
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get one holiday calendar in full: name, type, country code, the repeat setting, and every holiday with its dates.
# List holiday calendars
Source: https://docs.reply.io/api-reference/holiday-calendars/list-holiday-calendars
/api-reference/bundled.yaml get /v3/holiday-calendars
_Requires the `sequences:read` scope (or a broader one that includes it)._
See which holiday calendars you can link to a schedule — your team's custom ones plus Reply's country calendars.
# Update a holiday calendar
Source: https://docs.reply.io/api-reference/holiday-calendars/update-a-holiday-calendar
/api-reference/bundled.yaml put /v3/holiday-calendars/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Change a custom calendar's name, repeat setting, or days. The holidays array replaces the set outright, so send it all.
# Assign threads to a category
Source: https://docs.reply.io/api-reference/inbox-categories/assign-threads-to-a-category
/api-reference/bundled.yaml post /v3/inbox/threads/categories/{id}/thread-links/bulk
_Requires the `inbox:operate` scope (or a broader one that includes it)._
Use this endpoint when you need to file several conversations under this category at once. A thread sits in at most one category, so any earlier category on a supplied thread is replaced. Threads are processed one by one and successful links are kept even when others fail; the response returns only the thread ids that were not linked, each with its error details. A per-item error is notFound when the thread or the category does not exist, invalidInput when the thread id is not usable, or forbidden when you are not allowed to file that thread.
# Create inbox category
Source: https://docs.reply.io/api-reference/inbox-categories/create-inbox-category
/api-reference/bundled.yaml post /v3/inbox/threads/categories
_Requires the `inbox:write` scope (or a broader one that includes it)._
Use this endpoint when you need a category of your own to sort inbox conversations under. Provide a name — unique within your team, ignoring case — and optionally a color; the created category is returned with its assigned id.
# Delete inbox category
Source: https://docs.reply.io/api-reference/inbox-categories/delete-inbox-category
/api-reference/bundled.yaml delete /v3/inbox/threads/categories/{id}
_Requires the `inbox:write` scope (or a broader one that includes it)._
Delete one of your own inbox categories. Threads filed under it are unlinked and stay put. Reserved categories return 403.
# Get inbox category
Source: https://docs.reply.io/api-reference/inbox-categories/get-inbox-category
/api-reference/bundled.yaml get /v3/inbox/threads/categories/{id}
_Requires the `inbox:read` scope (or a broader one that includes it)._
Get one inbox category by id: its name, color, whether it's reserved by Reply, and its current unread thread count.
# List inbox categories
Source: https://docs.reply.io/api-reference/inbox-categories/list-inbox-categories
/api-reference/bundled.yaml get /v3/inbox/threads/categories
_Requires the `inbox:read` scope (or a broader one that includes it)._
Get the categories you can file conversations under, including Reply's reserved ones, each with its unread count.
# Unassign threads from a category
Source: https://docs.reply.io/api-reference/inbox-categories/unassign-threads-from-a-category
/api-reference/bundled.yaml post /v3/inbox/threads/categories/{id}/thread-links/bulk-delete
_Requires the `inbox:operate` scope (or a broader one that includes it)._
Use this endpoint when you need to take several conversations out of this category. A supplied thread filed under a different category is left alone. The conversations themselves are not deleted. Threads are processed one by one; the response returns only the thread ids that were not unlinked, each with its error details. A per-item error is notFound when the thread or the category does not exist, invalidInput when the thread id is not usable, or forbidden when you are not allowed to modify that thread.
# Update inbox category
Source: https://docs.reply.io/api-reference/inbox-categories/update-inbox-category
/api-reference/bundled.yaml put /v3/inbox/threads/categories/{id}
_Requires the `inbox:write` scope (or a broader one that includes it)._
Use this endpoint when you need to rename a category or change its color. Both name and color are replaced by what you send, so include the values you want to keep. The new name must be unique within your team. Reply's reserved categories cannot be edited — those are rejected with 403 and code inboxCategory.cannotModifyDefault.
# Assign or clear a thread's category
Source: https://docs.reply.io/api-reference/inbox/assign-or-clear-a-threads-category
/api-reference/bundled.yaml put /v3/inbox/threads/{id}/category
_Requires the `inbox:operate` scope (or a broader one that includes it)._
File one conversation under an inbox category, or send categoryId as null to clear it. A thread sits in at most one.
# Bulk-delete inbox threads
Source: https://docs.reply.io/api-reference/inbox/bulk-delete-inbox-threads
/api-reference/bundled.yaml post /v3/inbox/threads/bulk-delete
_Requires the `inbox:operate` scope (or a broader one that includes it)._
Use this endpoint when you need to permanently remove several inbox conversations in one call. Threads are processed one by one and successful deletions are kept even when others fail; the response returns only the thread ids that were not deleted, each with its error details, so an empty object means everything succeeded. A per-item error is notFound when the thread does not exist, or forbidden when you are not allowed to delete it.
# Delete inbox thread
Source: https://docs.reply.io/api-reference/inbox/delete-inbox-thread
/api-reference/bundled.yaml delete /v3/inbox/threads/{id}
_Requires the `inbox:operate` scope (or a broader one that includes it)._
Permanently delete one conversation and its messages. Use bulk-delete to remove several in one call.
# Filter inbox threads
Source: https://docs.reply.io/api-reference/inbox/filter-inbox-threads
/api-reference/bundled.yaml post /v3/inbox/threads/filter
_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.
# Generate an AI draft reply
Source: https://docs.reply.io/api-reference/inbox/generate-an-ai-draft-reply
/api-reference/bundled.yaml post /v3/inbox/threads/{id}/ai-draft/generate
Generate an AI-suggested reply for an inbox thread. Each call makes a fresh draft, so it also powers Regenerate.
# Get inbox thread
Source: https://docs.reply.io/api-reference/inbox/get-inbox-thread
/api-reference/bundled.yaml get /v3/inbox/threads/{id}
_Requires the `inbox:read` scope (or a broader one that includes it)._
Get one conversation with its message history in order. An email thread with more than 25 messages comes with its newest 25 messages and `hasMoreMessages` set to `true`; any other thread comes in full. Use the messages endpoint to page through the whole exchange.
# List changed inbox threads
Source: https://docs.reply.io/api-reference/inbox/list-changed-inbox-threads
/api-reference/bundled.yaml get /v3/inbox/threads/changes
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `inbox:read` scope (or a broader one that includes it)._
Use this endpoint to follow which inbox threads changed without re-listing the inbox. It returns threads in the order they were changed, earliest change first, and you read it forward with a cursor. A thread appears each time it changes: a new message, inbound or outbound, including one synced late; marking it read or unread; a meeting intent change; an owner change; its deletion from the inbox. Changing a thread's category alone does not return it; the `category` on each item, and `hasMeetingIntent`, which also follows the category, are the thread's values at the time of the read. Each item carries the thread's latest message, so you can tell a contact's reply from your own send. You see the same threads as in the thread list.
`lastActivityDate` is the date of the message that last moved the thread, at the same 10 ms precision as the message dates; nothing else moves it (not category, meeting intent, viewed, owner or delete changes). For a thread whose latest message is an email or a LinkedIn message, it equals `lastMessage.date`; it can be later when the latest message is an SMS, which `lastMessage` does not carry.
`isDeleted` true means the thread was deleted; the change reported is the deletion, and `GET /v3/inbox/threads/{id}` answers 404 for it. A thread removed together with its contact, its sequence enrolment or its team is not reported; `GET /v3/inbox/threads/{id}` answering 404 is how you learn of it.
A change of who may see a thread is not a change of the thread: a thread moved to another owner is not reported to a reader who saw it only as the previous owner's, and threads that become visible to you through a sequence or contact owner change are not returned until they change again. After a change of your role, of ownership or of your team, read again with `since`.
Start a read in one of three ways: pass the `cursor` from a previous page; pass `since` to start from the threads whose last activity is at or after that moment (at most 30 days ago); or pass neither to start from the last 30 days. Pass `cursor` or `since`, not both. A read started from `since` or with no parameters first returns the threads that moved in that window, oldest first, by the moment the thread moved, deleted threads excluded: a thread deleted before the read is not listed. The window lists only live threads: a thread you hold whose last activity is at or after the window's start and that the window does not return was deleted or is no longer visible to you, and for a thread whose last activity is before the window's start the window says nothing (only a message moves `lastActivityDate`, so a deletion does not bring a thread into the window). Deletions are reported only by the changes you read by cursor (`isDeleted`), so a read started again does not report the deletions made since your last cursor; confirm a thread you hold with `GET /v3/inbox/threads/{id}`, which answers 404 for a deleted one. It then continues with the changes made since the read began, by cursor like any later read: a thread written, moved or deleted while the window was being read arrives there, whatever its last activity, so it can appear twice.
The cursor is a position in the sequence of changes, not a time. Keep calling with the returned `cursor` while `hasMore` is true; read until `hasMore` is false, not until a page is empty, because a page can be empty with `hasMore` true: while the read passes threads it does not return (threads you cannot see, or deleted threads in the window), and when it reaches the end of the window, as when the window's last thread was deleted while it was being read. When `hasMore` is false, store the cursor and call again later: the next call returns every change made after the page was read, and none is skipped. An empty page with `hasMore` false returns a cursor at the feed's current position, never behind the one you passed. A change becomes readable once every write in progress before it has finished, so a long-running write anywhere in Reply can hold the feed back for every team until it completes; nothing is lost while it waits. Delivery is at least once: a thread can come back after a cursor that already covered it, so process each item as the thread's current state, keyed on `threadId`.
A cursor ahead of the feed's current position (as after a restore of the service's data), or a `since` older than 30 days, is refused with 400 and the code `inboxThread.changeWindowExpired`; start again with `since` or with no parameters.
# List inbox threads
Source: https://docs.reply.io/api-reference/inbox/list-inbox-threads
/api-reference/bundled.yaml get /v3/inbox/threads
_Requires the `inbox:read` scope (or a broader one that includes it)._
Browse your inbox — email and LinkedIn conversations with contacts, most recently active first. Paged with top and skip.
# List messages in an inbox thread
Source: https://docs.reply.io/api-reference/inbox/list-messages-in-an-inbox-thread
/api-reference/bundled.yaml get /v3/inbox/threads/{id}/messages
_Requires the `inbox:read` scope (or a broader one that includes it)._
Page through one conversation's messages, oldest first. Email messages carry recipient and subject; LinkedIn ones don't.
# Mark threads as read
Source: https://docs.reply.io/api-reference/inbox/mark-threads-as-read
/api-reference/bundled.yaml post /v3/inbox/threads/mark-as-read
_Requires the `inbox:operate` scope (or a broader one that includes it)._
Use this endpoint when you need to clear the unread state on one or more conversations — for example after your own app has shown them to the user. Threads that are already read are unaffected. Threads are processed one by one; the response returns only the thread ids that were not updated, each with its error details, so an empty object means everything succeeded. A per-item error is notFound when the thread does not exist, or forbidden when you are not allowed to access it.
# Mark threads as unread
Source: https://docs.reply.io/api-reference/inbox/mark-threads-as-unread
/api-reference/bundled.yaml post /v3/inbox/threads/mark-as-unread
_Requires the `inbox:operate` scope (or a broader one that includes it)._
Use this endpoint when you need to flag one or more conversations as needing attention again by restoring their unread state. Threads are processed one by one; the response returns only the thread ids that were not updated, each with its error details, so an empty object means everything succeeded. A per-item error is notFound when the thread does not exist, or forbidden when you are not allowed to access it.
# Send a reply within a thread
Source: https://docs.reply.io/api-reference/inbox/send-a-reply-within-a-thread
/api-reference/bundled.yaml post /v3/inbox/threads/{id}/messages
_Requires the `inbox:operate` scope (or a broader one that includes it)._
Reply to a contact inside an existing conversation. The channel in your body must match the thread's, or it's rejected.
# Submit feedback on a generated AI draft
Source: https://docs.reply.io/api-reference/inbox/submit-feedback-on-a-generated-ai-draft
/api-reference/bundled.yaml post /v3/inbox/threads/{id}/ai-draft/feedback
**Coming soon.** This endpoint will be available by late November 2026.
Records a thumbs-up / thumbs-down on the AI-generated draft, with optional dislike reasons and a freeform comment. Used as a training signal.
Requires the AI SDR feature on the caller's team.
# Toggle thread meeting-intent
Source: https://docs.reply.io/api-reference/inbox/toggle-thread-meeting-intent
/api-reference/bundled.yaml put /v3/inbox/threads/{id}/meeting-intent
_Requires the `inbox:operate` scope (or a broader one that includes it)._
Mark a conversation as one where the contact wants to book a meeting, or clear it. The thread filter can use this flag.
# Bulk delete LinkedIn accounts
Source: https://docs.reply.io/api-reference/linkedin-accounts/bulk-delete-linkedin-accounts
/api-reference/bundled.yaml post /v3/linkedin-accounts/bulk-delete
_Requires the `channels:write` scope (or a broader one that includes it)._
Disconnect up to 100 LinkedIn accounts in one call. Set force to true to delete accounts still used by sequences.
# Create a connection link
Source: https://docs.reply.io/api-reference/linkedin-accounts/create-a-connection-link
/api-reference/bundled.yaml post /v3/linkedin-accounts/connection-link
_Requires the `channels:write` scope (or a broader one that includes it)._
Invite a named LinkedIn account to connect. Returns a link to hand to the profile owner plus the pending account id.
# Create a direct connection link
Source: https://docs.reply.io/api-reference/linkedin-accounts/create-a-direct-connection-link
/api-reference/bundled.yaml post /v3/linkedin-accounts/connect
_Requires the `channels:write` scope (or a broader one that includes it)._
Get a connection link without naming the account up front — the name is captured as the link is completed.
# Delete a LinkedIn account
Source: https://docs.reply.io/api-reference/linkedin-accounts/delete-a-linkedin-account
/api-reference/bundled.yaml delete /v3/linkedin-accounts/{id}
_Requires the `channels:write` scope (or a broader one that includes it)._
Disconnect one LinkedIn account. An account still used by a sequence is rejected unless you pass force=true.
# Delete a pending LinkedIn account
Source: https://docs.reply.io/api-reference/linkedin-accounts/delete-a-pending-linkedin-account
/api-reference/bundled.yaml delete /v3/linkedin-accounts/pending/{id}
_Requires the `channels:write` scope (or a broader one that includes it)._
Cancel an outstanding LinkedIn connection invitation, for instance when its link expired or went to the wrong person.
# Get a LinkedIn account
Source: https://docs.reply.io/api-reference/linkedin-accounts/get-a-linkedin-account
/api-reference/bundled.yaml get /v3/linkedin-accounts/{id}
_Requires the `channels:read` scope (or a broader one that includes it)._
Get one connected LinkedIn account in full: profile, account and cookie status, daily usage, limits, and revoke settings.
# Link a voice to a LinkedIn account
Source: https://docs.reply.io/api-reference/linkedin-accounts/link-a-voice-to-a-linkedin-account
/api-reference/bundled.yaml put /v3/linkedin-accounts/{id}/voice
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:write` scope (or a broader one that includes it)._
Pick the voice this account speaks with in AI voice message steps. An account holds one voice at a time, so this replaces whatever was linked before.
# List LinkedIn accounts
Source: https://docs.reply.io/api-reference/linkedin-accounts/list-linkedin-accounts
/api-reference/bundled.yaml get /v3/linkedin-accounts
_Requires the `channels:read` scope (or a broader one that includes it)._
Get the LinkedIn accounts connected to Reply, with connection state and automation limits. One call, no paging.
# List pending LinkedIn accounts
Source: https://docs.reply.io/api-reference/linkedin-accounts/list-pending-linkedin-accounts
/api-reference/bundled.yaml get /v3/linkedin-accounts/pending
_Requires the `channels:read` scope (or a broader one that includes it)._
Track LinkedIn accounts invited by link but not yet connected, with the link, its expiry, and whether it has expired.
# Reconnect a LinkedIn account
Source: https://docs.reply.io/api-reference/linkedin-accounts/reconnect-a-linkedin-account
/api-reference/bundled.yaml post /v3/linkedin-accounts/{id}/reconnect
_Requires the `channels:write` scope (or a broader one that includes it)._
Get a fresh connection link for a connected LinkedIn account whose session cookie has expired and stopped working.
# Toggle LinkedIn account status
Source: https://docs.reply.io/api-reference/linkedin-accounts/toggle-linkedin-account-status
/api-reference/bundled.yaml post /v3/linkedin-accounts/{id}/toggle-status
_Requires the `channels:operate` scope (or a broader one that includes it)._
Pause or resume LinkedIn automation on one account. The call flips between enabled and disabled and returns the result.
# Unlink the voice from a LinkedIn account
Source: https://docs.reply.io/api-reference/linkedin-accounts/unlink-the-voice-from-a-linkedin-account
/api-reference/bundled.yaml delete /v3/linkedin-accounts/{id}/voice
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:write` scope (or a broader one that includes it)._
Drop the account's own voice. AI voice message steps sent from it then use the team's default voice.
# Update LinkedIn account limits
Source: https://docs.reply.io/api-reference/linkedin-accounts/update-linkedin-account-limits
/api-reference/bundled.yaml put /v3/linkedin-accounts/{id}/limits
_Requires the `channels:operate` scope (or a broader one that includes it)._
Cap daily LinkedIn automation per account: connection requests, messages, InMails, profile views, and more.
Send only what you want to change: every property you leave out, or send as `null`, keeps its current value, including single values inside `rangeMin`, `rangeMax` and `fixedMax`.
# Update LinkedIn account revoke settings
Source: https://docs.reply.io/api-reference/linkedin-accounts/update-linkedin-account-revoke-settings
/api-reference/bundled.yaml put /v3/linkedin-accounts/{id}/revoke-settings
_Requires the `channels:write` scope (or a broader one that includes it)._
Have an account withdraw its own unanswered LinkedIn invitations. Set enabled and the days a request may stay pending.
# Create a schedule
Source: https://docs.reply.io/api-reference/schedules/create-a-schedule
/api-reference/bundled.yaml post /v3/schedules
_Requires the `sequences:write` scope (or a broader one that includes it)._
Create a sending schedule for your sequences. The name must be unique in your team, and timezoneId takes a Windows time zone id.
# Delete a schedule
Source: https://docs.reply.io/api-reference/schedules/delete-a-schedule
/api-reference/bundled.yaml delete /v3/schedules/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete a schedule for good. Rejected while a sequence, template, or someone's default is still using it.
# Get a schedule
Source: https://docs.reply.io/api-reference/schedules/get-a-schedule
/api-reference/bundled.yaml get /v3/schedules/{id}
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get one schedule in full: its time zone, main and follow-up windows, and the flags controlling how they apply.
# Link a holiday calendar to a schedule
Source: https://docs.reply.io/api-reference/schedules/link-a-holiday-calendar-to-a-schedule
/api-reference/bundled.yaml post /v3/schedules/{id}/holiday-calendar-links
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Have a schedule observe a holiday calendar. A schedule can hold several, but linking the same one twice is rejected.
# List linked holiday calendars
Source: https://docs.reply.io/api-reference/schedules/list-linked-holiday-calendars
/api-reference/bundled.yaml get /v3/schedules/{id}/holiday-calendars
_Requires the `sequences:read` scope (or a broader one that includes it)._
See which holiday calendars are attached to a schedule, each in short form with its id, name, type, and country code.
# List schedules
Source: https://docs.reply.io/api-reference/schedules/list-schedules
/api-reference/bundled.yaml get /v3/schedules
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get every schedule your team can use. A schedule sets the weekday windows a sequence may send in. One call, no paging.
# Set default schedule
Source: https://docs.reply.io/api-reference/schedules/set-default-schedule
/api-reference/bundled.yaml post /v3/schedules/{id}/set-default
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Pick the schedule your new sequences start with. The default is yours alone and doesn't change what teammates use.
# Unlink a holiday calendar from a schedule
Source: https://docs.reply.io/api-reference/schedules/unlink-a-holiday-calendar-from-a-schedule
/api-reference/bundled.yaml delete /v3/schedules/{id}/holiday-calendar-links/{calendarId}
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Stop a schedule observing a holiday calendar. The calendar itself stays available to other schedules.
# Update a schedule
Source: https://docs.reply.io/api-reference/schedules/update-a-schedule
/api-reference/bundled.yaml put /v3/schedules/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Replace a schedule in full. Send every value you want to keep, including the complete main and follow-up timings arrays.
# Remove email account from sequence
Source: https://docs.reply.io/api-reference/sequence-email-accounts/remove-email-account-from-sequence
/api-reference/bundled.yaml delete /v3/sequences/{id}/email-account-links/{email_account_id}
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Stop a sequence sending from one of its mailboxes. The account itself stays connected and works in other sequences.
# Assign a LinkedIn account to a sequence
Source: https://docs.reply.io/api-reference/sequence-linkedin-accounts/assign-a-linkedin-account-to-a-sequence
/api-reference/bundled.yaml post /v3/sequences/{id}/linkedin-account-links
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Add one more LinkedIn account for a sequence's LinkedIn steps. It links whatever state the account is currently in.
# List LinkedIn accounts for a sequence
Source: https://docs.reply.io/api-reference/sequence-linkedin-accounts/list-linkedin-accounts-for-a-sequence
/api-reference/bundled.yaml get /v3/sequences/{id}/linkedin-accounts
_Requires the `sequences:read` scope (or a broader one that includes it)._
See which LinkedIn accounts a sequence sends its LinkedIn steps from, each with its id, name, profile URL, and status.
# Remove a LinkedIn account from a sequence
Source: https://docs.reply.io/api-reference/sequence-linkedin-accounts/remove-a-linkedin-account-from-a-sequence
/api-reference/bundled.yaml delete /v3/sequences/{id}/linkedin-account-links/{linkedInAccountId}
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Stop a sequence sending LinkedIn steps from one linked account. The account stays connected and works elsewhere.
# Delete a sequence template
Source: https://docs.reply.io/api-reference/sequence-templates/delete-a-sequence-template
/api-reference/bundled.yaml delete /v3/sequence-templates/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete a sequence template so it's no longer offered. Team templates are shared, so any teammate who sees one can delete it.
# List all sequence templates
Source: https://docs.reply.io/api-reference/sequence-templates/list-all-sequence-templates
/api-reference/bundled.yaml get /v3/sequence-templates
_Requires the `sequences:read` scope (or a broader one that includes it)._
See which sequence templates you can start a new sequence from. A blueprint for a whole sequence, not an email template.
# Batch reassign tasks
Source: https://docs.reply.io/api-reference/tasks/batch-reassign-tasks
/api-reference/bundled.yaml post /v3/tasks/batch/assign
_Requires the `tasks:write` scope (or a broader one that includes it)._
Hand up to 100 tasks to a colleague. They must be on your team, or nothing is reassigned. Only failed ids come back.
# Bulk delete tasks
Source: https://docs.reply.io/api-reference/tasks/bulk-delete-tasks
/api-reference/bundled.yaml post /v3/tasks/bulk-delete
_Requires the `tasks:write` scope (or a broader one that includes it)._
Remove up to 100 tasks at once. Open tasks are cancelled and completed ones archived; either way they leave your lists.
# Complete a task
Source: https://docs.reply.io/api-reference/tasks/complete-a-task
/api-reference/bundled.yaml post /v3/tasks/{id}/complete
_Requires the `tasks:operate` scope (or a broader one that includes it)._
Mark a task done without carrying it out. On a call task, pass callResolution to record how the call went.
# Create a task
Source: https://docs.reply.io/api-reference/tasks/create-a-task
/api-reference/bundled.yaml post /v3/tasks
_Requires the `tasks:write` scope (or a broader one that includes it)._
Create a task of your own. taskType, startAt, dueTo, and a template body are required; contactId for every type but toDo.
# Delete a task
Source: https://docs.reply.io/api-reference/tasks/delete-a-task
/api-reference/bundled.yaml delete /v3/tasks/{id}
_Requires the `tasks:write` scope (or a broader one that includes it)._
Remove one task by id. An open task is cancelled and a completed one archived; either way it leaves your task lists.
# Execute and complete a task
Source: https://docs.reply.io/api-reference/tasks/execute-and-complete-a-task
/api-reference/bundled.yaml post /v3/tasks/{id}/execute
_Requires the `tasks:operate` scope (or a broader one that includes it)._
Carry a task out and complete it. Only manualEmail and sms tasks can be executed — use complete for any other type.
# Filter tasks
Source: https://docs.reply.io/api-reference/tasks/filter-tasks
/api-reference/bundled.yaml post /v3/tasks/filter
_Requires the `tasks:read` scope (or a broader one that includes it)._
Narrow the task list by due date, type, status, or overdue. Every field is optional, so an empty object returns them all.
# Get a task
Source: https://docs.reply.io/api-reference/tasks/get-a-task
/api-reference/bundled.yaml get /v3/tasks/{id}
_Requires the `tasks:read` scope (or a broader one that includes it)._
Get everything about one task: type, status, the contact, the sequence step it came from, its dates, and its assignee.
# List all tasks
Source: https://docs.reply.io/api-reference/tasks/list-all-tasks
/api-reference/bundled.yaml get /v3/tasks
_Requires the `tasks:read` scope (or a broader one that includes it)._
Work through your to-do list — your own tasks, plus teammates' when your role allows. Each carries type, status, and dates.
# Reassign a task
Source: https://docs.reply.io/api-reference/tasks/reassign-a-task
/api-reference/bundled.yaml put /v3/tasks/{id}/assigned-user
_Requires the `tasks:write` scope (or a broader one that includes it)._
Hand one task to a colleague by user id. They must be on your team, and your role must allow the reassignment.
# Update a task
Source: https://docs.reply.io/api-reference/tasks/update-a-task
/api-reference/bundled.yaml put /v3/tasks/{id}
_Requires the `tasks:write` scope (or a broader one that includes it)._
Replace an open task in full. Send taskType, startAt, dueTo, and a template body every time; only open tasks can change.
# Create a voice
Source: https://docs.reply.io/api-reference/voices/create-a-voice
/api-reference/bundled.yaml post /v3/voices
_Requires the `channels:write` scope (or a broader one that includes it)._
Clone a new voice from an audio sample. Send multipart/form-data with audioFile, name, and a 2-3 character languageCode. Requires a connected LinkedIn account; the number of voices is limited by your plan.
# Delete a voice
Source: https://docs.reply.io/api-reference/voices/delete-a-voice
/api-reference/bundled.yaml delete /v3/voices/{id}
_Requires the `channels:write` scope (or a broader one that includes it)._
Delete a voice and unlink it from every LinkedIn account using it. The default voice cannot be deleted while other voices exist.
# Get a voice
Source: https://docs.reply.io/api-reference/voices/get-a-voice
/api-reference/bundled.yaml get /v3/voices/{id}
_Requires the `channels:read` scope (or a broader one that includes it)._
Get one voice in full: name, language code, default status, and creation date.
# List background noise presets
Source: https://docs.reply.io/api-reference/voices/list-background-noise-presets
/api-reference/bundled.yaml get /v3/voices/background-noises
_Requires the `channels:read` scope (or a broader one that includes it)._
Get the background noise presets for AI voice message steps. Pass a preset id as backgroundNoiseId when creating a step.
# List supported voice languages
Source: https://docs.reply.io/api-reference/voices/list-supported-voice-languages
/api-reference/bundled.yaml get /v3/voices/languages
_Requires the `channels:read` scope (or a broader one that includes it)._
Get the supported language codes for voice creation as a code-to-name dictionary. Pass a code as languageCode when creating a voice.
# List voices
Source: https://docs.reply.io/api-reference/voices/list-voices
/api-reference/bundled.yaml get /v3/voices
_Requires the `channels:read` scope (or a broader one that includes it)._
Get the cloned voices available to your team for AI voice message steps, including which one is the team default. One call, no paging.
# Rename a voice
Source: https://docs.reply.io/api-reference/voices/rename-a-voice
/api-reference/bundled.yaml put /v3/voices/{id}
_Requires the `channels:write` scope (or a broader one that includes it)._
Rename a voice. Language and recording are fixed at creation and cannot be changed.
# Set a voice as the team default
Source: https://docs.reply.io/api-reference/voices/set-a-voice-as-the-team-default
/api-reference/bundled.yaml post /v3/voices/{id}/set-default
_Requires the `channels:write` scope (or a broader one that includes it)._
Make a voice the team default for LinkedIn accounts with no voice linked. Only one default at a time; the previous default is cleared.
# Get AI insights for a contact
Source: https://docs.reply.io/api-reference/ai-sdr-insights/get-ai-insights-for-a-contact
/api-reference/bundled.yaml get /v3/sequences/ai-sdr/{sequence_id}/contacts/{contact_id}/ai-insights
**Coming soon.** This endpoint will be available by late November 2026.
Get the AI SDR insights summary for one contact in one sequence. Returns a single Markdown field, ready to render as-is.
# Add a link
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/add-a-link
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/links
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Add a web page to a knowledge base so the AI SDR can draw on it. The URL is required and capped at 256 characters.
# Assign a reengagement flow to a contact
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/assign-a-reengagement-flow-to-a-contact
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows/{flow_id}/assign
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need to move one contact onto a specific reengagement flow — after a conversation suggests a different follow-up track, for instance. Provide sequenceId and contactId in the body, both positive; the flow must belong to this knowledge base and the sequence must already be connected to it, otherwise the call is rejected as not found. The assignment resets the contact's reengagement timing and returns 204 with no body. The AI SDR feature must be enabled for your team.
# Create a knowledge base
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/create-a-knowledge-base
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Create a knowledge base for the AI SDR to write from. Only the name is required; instructions add up to 2000 characters of guidance.
# Create a reengagement card
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/create-a-reengagement-card
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-cards
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Create a follow-up for contacts who stop replying. Name, instructions, and sendAfter are required — sendAfter is days of silence.
# Create a reengagement flow
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/create-a-reengagement-flow
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need a follow-up track alongside the ones a knowledge base already has — a gentler cadence for VIP contacts, say. name is required, must be unique within the knowledge base and is limited to 256 characters; description is optional and limited to 512. The created flow is returned with its id and starts out empty — add cards to it by passing that id as flowId when you create a reengagement card. The AI SDR feature must be enabled for your team.
# Create a reply handler
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/create-a-reply-handler
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Tell the AI SDR how to handle one recurring kind of reply. The question type and instructions are required; a sample answer helps.
# Delete a document
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/delete-a-document
/api-reference/bundled.yaml delete /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/documents/{document_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Remove a file from a knowledge base so the AI SDR stops drawing on it. Returns 204 with no body when it succeeds.
# Delete a knowledge base
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/delete-a-knowledge-base
/api-reference/bundled.yaml delete /v3/ai-sdr/knowledge-bases/{id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Delete a knowledge base by id so the AI SDR stops writing from it. Returns 204 with no body when it succeeds.
# Delete a link
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/delete-a-link
/api-reference/bundled.yaml delete /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/links/{link_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Remove a web page from a knowledge base so the AI SDR stops drawing on it. Returns 204 with no body on success.
# Delete a reengagement card
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/delete-a-reengagement-card
/api-reference/bundled.yaml delete /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-cards/{reengagement_card_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Delete a reengagement card so it no longer fires for quiet contacts. To keep it but stop it firing, set isEnabled to false.
# Delete a reengagement flow
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/delete-a-reengagement-flow
/api-reference/bundled.yaml delete /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows/{flow_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Retire a reengagement flow and its cards. Contacts on it fall back to the default flow, which cannot itself be deleted.
# Delete a reply handler
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/delete-a-reply-handler
/api-reference/bundled.yaml delete /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers/{reply_handler_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Delete a reply handler so the AI SDR stops applying it to incoming replies. Returns 204 with no body on success.
# Delete reengagement card media
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/delete-reengagement-card-media
/api-reference/bundled.yaml delete /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-cards/{reengagement_card_id}/media/{media_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Detach a file from a reengagement card so it stops going out with the card's messages. Returns 204 with no body.
# Delete reply handler media
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/delete-reply-handler-media
/api-reference/bundled.yaml delete /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers/{reply_handler_id}/media/{media_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Detach a file from a reply handler so it stops going out with the answers the agent writes. Returns 204 with no body.
# Duplicate a knowledge base
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/duplicate-a-knowledge-base
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{id}/duplicate
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Copy a knowledge base with its documents, links, reply handlers, and reengagement cards, so you can adapt it safely.
# Duplicate a reengagement flow
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/duplicate-a-reengagement-flow
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows/{flow_id}/duplicate
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Copy a reengagement flow along with its cards. The copy is created as a non-default flow in the same knowledge base.
# Get a knowledge base
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/get-a-knowledge-base
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{id}
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Get one knowledge base by id: its name, standing instructions, owner, and last update. Its contents have their own endpoints.
# Get a reengagement card
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/get-a-reengagement-card
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-cards/{reengagement_card_id}
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Get one reengagement card in full: instructions, sample answer, the sendAfter delay, tone, length, links, and media.
# Get a reply handler
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/get-a-reply-handler
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers/{reply_handler_id}
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Get one reply handler in full: its question type, instructions, sample answer, tone, length, links, media, and delivery mode.
# Get contacts count for a reengagement flow
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/get-contacts-count-for-a-reengagement-flow
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows/{flow_id}/contacts-count
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Count the contacts currently on a reengagement flow. The body is the number on its own, as a plain integer.
# Get reengagement flow state for a contact
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/get-reengagement-flow-state-for-a-contact
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows/state
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
See which reengagement flow a contact is on and when it was assigned. Pass sequenceid and contactid as query parameters.
# List documents
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/list-documents
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/documents
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
List the files a knowledge base holds for the AI SDR. Paged with top and skip, with an optional search on the file name.
# List knowledge bases
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/list-knowledge-bases
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Browse the knowledge bases you can see — the collections that brief the AI SDR. Paged with top and skip.
# List links
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/list-links
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/links
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
List the web pages a knowledge base pulls content from. Paged with top and skip, with an optional search on the URL.
# List reengagement cards
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/list-reengagement-cards
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-cards
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Review the follow-ups a knowledge base sends to contacts who went quiet. Paged with top and skip, filterable by flow.
# List reengagement flows
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/list-reengagement-flows
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
List the reengagement flows on a knowledge base. Returned as one plain array with each flow's name, description, and card count.
# List reply handlers
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/list-reply-handlers
/api-reference/bundled.yaml get /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Review the rules that tell the AI SDR how to answer each kind of reply. Paged with the top and skip query parameters.
# Set a reengagement flow as default
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/set-a-reengagement-flow-as-default
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows/{flow_id}/set-default
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Make a reengagement flow the default for contacts with none assigned. The previous default loses the role. Returns 204.
# Update a knowledge base
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/update-a-knowledge-base
/api-reference/bundled.yaml patch /v3/ai-sdr/knowledge-bases/{id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Rename a knowledge base or change its standing instructions. Send only what you're changing; at least one field is required.
# Update a reengagement card
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/update-a-reengagement-card
/api-reference/bundled.yaml patch /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-cards/{reengagement_card_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need to adjust a reengagement card — retime it, reword its instructions, or switch it on and off with isEnabled. Send only the fields you want to change; at least one of name, instructions, sampleAnswer, sendAfter, toneOfVoice, responseLength, links, isEnabled and deliveryMode must be present, and the same limits apply as on create. Media is not changed here — attach and remove files through the card's media sub-resource. The updated card is returned; a sendAfter that clashes with another card in the same flow is rejected as a conflict. The AI SDR feature must be enabled for your team.
# Update a reengagement flow
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/update-a-reengagement-flow
/api-reference/bundled.yaml patch /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-flows/{flow_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need to rename a reengagement flow or change its description. Send only the fields you want to change; at least one of name and description must be present. name must be non-empty, at most 256 characters and still unique within the knowledge base; description accepts up to 512 characters. The updated flow is returned. The cards in the flow are unaffected. The AI SDR feature must be enabled for your team.
# Update a reply handler
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/update-a-reply-handler
/api-reference/bundled.yaml patch /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers/{reply_handler_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need to adjust how the AI SDR agent answers a kind of reply. Send only the fields you want to change; at least one of typeOfQuestion, instructions, sampleAnswer, toneOfVoice, responseLength, links, deliveryMode and additionalNotificationEmail must be present, and the same limits apply as on create. Switching deliveryMode to stopAndNotify requires that mode to be enabled for your team, and moving the handler off stopAndNotify clears additionalNotificationEmail. Media is not changed here — use the handler's media sub-resource. The updated handler is returned. The AI SDR feature must be enabled for your team.
# Upload a document
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/upload-a-document
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/documents
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Upload a file to a knowledge base for the AI SDR to draw on. Send it as multipart/form-data, up to 100 MB per request.
# Upload reengagement card media
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/upload-reengagement-card-media
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reengagement-cards/{reengagement_card_id}/media
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Attach an image or file to a reengagement card so it goes out with the message. Multipart/form-data, up to 100 MB.
# Upload reply handler media
Source: https://docs.reply.io/api-reference/ai-sdr-knowledge-bases/upload-reply-handler-media
/api-reference/bundled.yaml post /v3/ai-sdr/knowledge-bases/{knowledge_base_id}/reply-handlers/{reply_handler_id}/media
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Attach an image or file to a reply handler so it goes out with the agent's answers. Multipart/form-data, up to 100 MB.
# Create an offer
Source: https://docs.reply.io/api-reference/ai-sdr-offers/create-an-offer
/api-reference/bundled.yaml post /v3/ai-sdr/offers
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Create an offer to hold the company context your AI SDR outreach draws on. Only the name is required, up to 200 characters.
# Delete an offer
Source: https://docs.reply.io/api-reference/ai-sdr-offers/delete-an-offer
/api-reference/bundled.yaml delete /v3/ai-sdr/offers/{id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Delete an offer you no longer work with, by id. A successful call returns no content. Needs the AI SDR feature on your team.
# Duplicate an offer
Source: https://docs.reply.io/api-reference/ai-sdr-offers/duplicate-an-offer
/api-reference/bundled.yaml post /v3/ai-sdr/offers/{id}/duplicate
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Copy an offer so you can adapt a proven one to a new segment. The copy carries the same company context as the original.
# Generate an offer
Source: https://docs.reply.io/api-reference/ai-sdr-offers/generate-an-offer
/api-reference/bundled.yaml post /v3/ai-sdr/offers/generate
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Have the AI SDR draft an offer from a company URL or a brief, instead of filling in the context by hand. Runs in the background.
# Get an offer
Source: https://docs.reply.io/api-reference/ai-sdr-offers/get-an-offer
/api-reference/bundled.yaml get /v3/ai-sdr/offers/{id}
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Get one offer in full: company name and description, ICP, reason for outreach, case studies, pain points, and value props.
# List offers
Source: https://docs.reply.io/api-reference/ai-sdr-offers/list-offers
/api-reference/bundled.yaml get /v3/ai-sdr/offers
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Browse the AI SDR offers you can work with. Each bundles the company context used to personalize outreach. Paged with top and skip.
# Update an offer
Source: https://docs.reply.io/api-reference/ai-sdr-offers/update-an-offer
/api-reference/bundled.yaml patch /v3/ai-sdr/offers/{id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need to change part of an existing offer without resending all of it. Send only the fields you want to change — at least one must be present, and every field you leave out keeps its current value. A list field you do send replaces the whole list, so include every entry you want to keep; each list accepts up to 10 non-empty entries of at most 1000 characters, and any text you send may reference only the template variables your account recognizes. The full updated offer is returned. The AI SDR feature must be enabled for your team.
# Upload an attachment for offer generation
Source: https://docs.reply.io/api-reference/ai-sdr-offers/upload-an-attachment-for-offer-generation
/api-reference/bundled.yaml post /v3/ai-sdr/offers/generation-attachments
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Upload a document for the AI SDR to read before drafting an offer. Max 10 MB, as .txt, .pdf, .doc, .docx, or .rtf.
# Get pending approval for a contact
Source: https://docs.reply.io/api-reference/ai-sdr-pending-approvals/get-pending-approval-for-a-contact
/api-reference/bundled.yaml get /v3/sequences/ai-sdr/{sequence_id}/contacts/{contact_id}/approval
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Review one queued draft before you act on it. It's addressed by sequence and contact id — there is no separate approval id.
# List pending approvals
Source: https://docs.reply.io/api-reference/ai-sdr-pending-approvals/list-pending-approvals
/api-reference/bundled.yaml get /v3/ai-sdr/approvals
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Work through the AI messages your team's sequences have queued for approval. Paged with top and skip, filterable by sequence.
# Regenerate a pending approval
Source: https://docs.reply.io/api-reference/ai-sdr-pending-approvals/regenerate-a-pending-approval
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/contacts/{contact_id}/approval/regenerate
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Have the AI SDR write a new message while keeping the contact in the sequence. Pass recommendations to steer the rewrite.
# Reject (delete) a pending approval
Source: https://docs.reply.io/api-reference/ai-sdr-pending-approvals/reject-delete-a-pending-approval
/api-reference/bundled.yaml delete /v3/sequences/ai-sdr/{sequence_id}/contacts/{contact_id}/approval
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Reject a contact's queued draft instead of sending it. The draft is discarded and the contact leaves the sequence.
# Send a batch of pending approvals
Source: https://docs.reply.io/api-reference/ai-sdr-pending-approvals/send-a-batch-of-pending-approvals
/api-reference/bundled.yaml post /v3/ai-sdr/approvals/send-bulk
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need to approve and send several queued drafts in one call. Pass items as a list of at most 20 sequenceId and contactId pairs, each identifying one pending approval. The batch is all or nothing: every pair is matched to a pending approval before anything is sent, and if any of them has none, nothing is sent and the response names the pairs that could not be matched. Drafts go out exactly as generated — to change a body or subject first, use the per-contact send endpoint. A successful call returns no content. The AI SDR feature must be enabled for your team.
# Send a pending approval
Source: https://docs.reply.io/api-reference/ai-sdr-pending-approvals/send-a-pending-approval
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/contacts/{contact_id}/approval/send
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Approve and send one contact's queued draft. Leave body and subject unset to send as generated, or pass either to overwrite. Pass an empty subject to send the draft without one.
# Submit feedback on a pending approval
Source: https://docs.reply.io/api-reference/ai-sdr-pending-approvals/submit-feedback-on-a-pending-approval
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/contacts/{contact_id}/approval/feedback
**Coming soon.** This endpoint will be available by late November 2026.
Use this endpoint when you need to tell the AI SDR whether a queued draft was good, so it can learn from your judgement. Set vote to like or dislike; when the vote is dislike, add dislikeReasons to categorize what was wrong and comment for a freeform explanation. The feedback is recorded against the approval pending for the sequence_id and contact_id in the path, so no draft identifier is needed. A successful call returns no content. The AI SDR feature must be enabled for your team.
# Create a playbook
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/create-a-playbook
/api-reference/bundled.yaml post /v3/ai-sdr/playbooks
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Create a playbook holding the tone, voice, and writing guidance your AI SDR follows. Name, description, body, and type are required.
# Delete a playbook
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/delete-a-playbook
/api-reference/bundled.yaml delete /v3/ai-sdr/playbooks/{id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Delete a playbook by its composite id. Reply-curated global playbooks cannot be deleted, and organization ones need permission.
# Delete a style file
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/delete-a-style-file
/api-reference/bundled.yaml delete /v3/ai-sdr/playbooks/{playbook_id}/style-files/{style_file_id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Remove a style file so it stops informing how the AI SDR writes for this playbook. Only that file is removed.
# Duplicate a playbook
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/duplicate-a-playbook
/api-reference/bundled.yaml post /v3/ai-sdr/playbooks/{id}/duplicate
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Copy a playbook so you can adapt it to a new segment. Any playbook you can read works as the source, including a global one.
# Get a playbook
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/get-a-playbook
/api-reference/bundled.yaml get /v3/ai-sdr/playbooks/{id}
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Get one playbook by composite id — g- global, o- organization, t- team — with its description, body, and style files.
# List playbooks
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/list-playbooks
/api-reference/bundled.yaml get /v3/ai-sdr/playbooks
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Browse the AI SDR playbooks you can use. Pass type to keep one scope: global, organization, or team.
# List sequences using a playbook
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/list-sequences-using-a-playbook
/api-reference/bundled.yaml get /v3/ai-sdr/playbooks/{id}/sequences
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
See which AI SDR sequences a playbook is attached to — useful before editing a playbook, since an edit applies to every one of them. Returns all sequences, ordered by sequence id.
# Regenerate a playbook
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/regenerate-a-playbook
/api-reference/bundled.yaml post /v3/ai-sdr/playbooks/{id}/regenerate
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Have the AI SDR rewrite a playbook's body from your feedback. The playbook is updated in place, so every sequence that uses it picks up the new version. Works on organization and team playbooks; global playbooks are read-only.
# Update a playbook
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/update-a-playbook
/api-reference/bundled.yaml patch /v3/ai-sdr/playbooks/{id}
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Change part of a playbook without resending it all. Send at least one of name, description, and body; type cannot change.
# Upload a style file
Source: https://docs.reply.io/api-reference/ai-sdr-playbooks/upload-a-style-file
/api-reference/bundled.yaml post /v3/ai-sdr/playbooks/{playbook_id}/style-files
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Upload a reference document — a tone guide or writing sample — for the AI SDR to draw on alongside the playbook body.
# Personalize the preview for a contact
Source: https://docs.reply.io/api-reference/ai-sdr-sequence-preview/personalize-the-preview-for-a-contact
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/contacts/{contact_id}/preview/personalize
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Have the AI write or rewrite the messages one contact will get in an AI SDR sequence. Runs in the background across their steps.
# Submit feedback on a preview step
Source: https://docs.reply.io/api-reference/ai-sdr-sequence-preview/submit-feedback-on-a-preview-step
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/contacts/{contact_id}/preview/steps/{step_id}/feedback
**Coming soon.** This endpoint will be available by late November 2026.
Use this endpoint when you need to record a reaction to the AI-generated message for one step of a contact's preview — set vote to like or dislike. When the vote is dislike you can add dislikeReasons to categorize what was wrong, and comment carries a freeform note alongside either vote. The feedback is kept as a training signal for the AI SDR; a successful call returns no content. The AI SDR feature must be enabled for your team.
# Get a sequence structure
Source: https://docs.reply.io/api-reference/ai-sdr-sequence-structures/get-a-sequence-structure
/api-reference/bundled.yaml get /v3/ai-sdr/sequence-structures/{id}
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Read one sequence structure by id: its name, the channels its steps use, and its scope.
# List sequence structures
Source: https://docs.reply.io/api-reference/ai-sdr-sequence-structures/list-sequence-structures
/api-reference/bundled.yaml get /v3/ai-sdr/sequence-structures
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Browse the sequence structures you can apply to AI SDR sequences. Pick one scope with scope: library (the default), personal, team, or organization.
# Add example messages to the playbook draft
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/add-example-messages-to-the-playbook-draft
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/playbook-draft/example-files
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Upload a file with your best-performing outreach messages. The AI SDR matches them to the sequence's steps and adds them to the draft's examples, so generated messages follow your style. Updates the draft only. Accepted file types: .txt, .html, .csv, .md, .pdf, up to 100 MB.
# Attach a playbook to the sequence
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/attach-a-playbook-to-the-sequence
/api-reference/bundled.yaml put /v3/sequences/ai-sdr/{sequence_id}/playbook
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Set the playbook the AI SDR follows for this sequence. Send playbookId as a composite id such as t-7. Replaces any previous one.
# Connect a knowledge base to the sequence
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/connect-a-knowledge-base-to-the-sequence
/api-reference/bundled.yaml put /v3/sequences/ai-sdr/{sequence_id}/knowledge-base
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Set the knowledge base the AI SDR draws on for this sequence. A sequence keeps one at a time, so this replaces any previous.
# Create an AI SDR sequence
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/create-an-ai-sdr-sequence
/api-reference/bundled.yaml post /v3/sequences/ai-sdr
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Create a sequence the AI SDR writes and runs. Seed the company context with exactly one of offerId or offerGenerationInputs. Pass structureId to build the steps from a specific sequence structure, or omit it to let the AI SDR pick one.
# Detach the playbook from the sequence
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/detach-the-playbook-from-the-sequence
/api-reference/bundled.yaml delete /v3/sequences/ai-sdr/{sequence_id}/playbook
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Stop the AI SDR following this sequence's playbook. Only the connection goes — the playbook stays available elsewhere.
# Disable autopilot
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/disable-autopilot
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/autopilot/disable
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Stop a sequence looking for new contacts on its own. Existing contacts, filters, and limits stay exactly as they are.
# Disconnect the knowledge base from the sequence
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/disconnect-the-knowledge-base-from-the-sequence
/api-reference/bundled.yaml delete /v3/sequences/ai-sdr/{sequence_id}/knowledge-base
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Stop the AI SDR drawing on this sequence's knowledge base. Only the connection goes — the knowledge base itself stays.
# Enable autopilot
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/enable-autopilot
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/autopilot/enable
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Let a sequence keep finding and adding contacts on its own, using the autopilot filters and limits already saved on it.
# Force-start an autopilot search
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/force-start-an-autopilot-search
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/autopilot/force-start
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Start an autopilot contact search now instead of waiting for the next run. Autopilot has to be on or the call is rejected.
# Generate a playbook draft
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/generate-a-playbook-draft
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/playbook-draft/generate
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Have the AI SDR write a playbook for this sequence from its offer. Starts a new draft, replacing your current one. The draft is not saved to your playbooks until you call save.
# Get the sequence's knowledge base
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/get-the-sequences-knowledge-base
/api-reference/bundled.yaml get /v3/sequences/ai-sdr/{sequence_id}/knowledge-base
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
See which knowledge base the AI SDR draws on for this sequence. Reports not found when none is connected.
# Get the sequence's playbook
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/get-the-sequences-playbook
/api-reference/bundled.yaml get /v3/sequences/ai-sdr/{sequence_id}/playbook
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
See which playbook the AI SDR follows for this sequence, with its id, name, and whether it's global, organization, or team.
# Get the sequence's playbook draft
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/get-the-sequences-playbook-draft
/api-reference/bundled.yaml get /v3/sequences/ai-sdr/{sequence_id}/playbook-draft
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Read your current AI-generated playbook draft for this sequence. Each user has their own draft per sequence. Drafts are deleted after 1 hour of inactivity.
# Get the sequence's structure
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/get-the-sequences-structure
/api-reference/bundled.yaml get /v3/sequences/ai-sdr/{sequence_id}/structure
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
See which sequence structure the sequence's steps were built from, and whether the structure can still be changed.
# Preview autopilot results
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/preview-autopilot-results
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/autopilot/preview
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
See how many contacts and companies a set of autopilot filters would reach before you commit. Nothing you send is saved.
# Read AI SDR sequence settings
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/read-ai-sdr-sequence-settings
/api-reference/bundled.yaml get /v3/sequences/ai-sdr/{sequence_id}/settings
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Read one sequence's AI SDR settings: offer context, tone, LLM, intent signals, playbook, and approval mode.
# Regenerate the playbook draft
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/regenerate-the-playbook-draft
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/playbook-draft/regenerate
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Have the AI SDR rewrite your playbook draft from your feedback. Updates the draft only; the saved playbook, if any, changes when you call save.
# Save the playbook draft
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/save-the-playbook-draft
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/playbook-draft/save
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Save your playbook draft as a team playbook and attach it to this sequence, replacing any attached playbook. The first save creates the playbook; later saves of the same draft update that playbook. Send structure to save your edits, or omit it to save the draft as it is.
# Save the sequence's steps as a structure
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/save-the-sequences-steps-as-a-structure
/api-reference/bundled.yaml post /v3/sequences/ai-sdr/{sequence_id}/structure/save-as
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Save the sequence's current steps as a new sequence structure you can apply to other AI SDR sequences. Share it with yourself, your team, or your organization. The sequence is then linked to the new structure.
# Set the approval mode
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/set-the-approval-mode
/api-reference/bundled.yaml put /v3/sequences/ai-sdr/{sequence_id}/approval-mode
_Requires the `ai-sdr:operate` scope (or a broader one that includes it)._
Decide whether AI-written messages send on their own or wait for a person to approve them. Set enabled to true to hold them.
# Set the sequence's structure
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/set-the-sequences-structure
/api-reference/bundled.yaml put /v3/sequences/ai-sdr/{sequence_id}/structure
**Coming soon.** This endpoint will be available by late October 2026.
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Rebuild the sequence's steps from a sequence structure. The sequence's current steps are replaced. Not allowed once the sequence has sent messages.
# Update AI SDR sequence settings
Source: https://docs.reply.io/api-reference/ai-sdr-sequences/update-ai-sdr-sequence-settings
/api-reference/bundled.yaml patch /v3/sequences/ai-sdr/{sequence_id}/settings
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Change part of a sequence's AI SDR settings. offerId and offerGenerationInputs are mutually exclusive; send at least one field.
# Start a strategist run
Source: https://docs.reply.io/api-reference/ai-sdr-strategist/start-a-strategist-run
/api-reference/bundled.yaml post /v3/ai-sdr/strategist/start
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Have the AI Strategist think up outreach ideas for a company and build a sequence from each. Runs in the background.
# Get calls reporting overview
Source: https://docs.reply.io/api-reference/reports/get-calls-reporting-overview
/api-reference/bundled.yaml post /v3/reporting/calls/overview
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need call activity for a period rolled up two ways at once — a single total for the whole selection covering calls placed, answered and resolved positively, missed inbound calls, average call duration and calls per answered contact, and the same figures repeated per team member under memberStatistics, keyed by userId. Use the calls endpoint instead when you need the individual call records behind these numbers. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account. Figures cover your whole team unless you narrow them with userIds or teamIds, and if your role only exposes your own activity you get your own numbers whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the calls report.
# Get channel efficiency overview
Source: https://docs.reply.io/api-reference/reports/get-channel-efficiency-overview
/api-reference/bundled.yaml post /v3/reporting/channel-efficiency/overview
_Requires the `reporting:read` scope (or a broader one that includes it)._
Compare channels for a period: contacts touched, touches across email, SMS, calls, tasks, and LinkedIn, replies, and meetings.
# Get email reporting overview
Source: https://docs.reply.io/api-reference/reports/get-email-reporting-overview
/api-reference/bundled.yaml post /v3/reporting/emails/overview
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need the headline email numbers for a period as one team-wide total with no per-member or per-sequence split — how many contacts were reached, and how many of them were delivered to, opened, replied, showed interest, bounced, auto-replied, were out of office, opted out or booked a meeting, each counted in distinct contacts and paired with its rate. Use the emails endpoint instead when you need the individual sent emails behind these totals. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account; set includeOutOfSequence to true to also count one-off emails sent outside any sequence. Figures cover your whole team unless you narrow them with userIds or teamIds, and if your role only exposes your own activity you get your own numbers whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the email report.
# Get LinkedIn reporting overview
Source: https://docs.reply.io/api-reference/reports/get-linkedin-reporting-overview
/api-reference/bundled.yaml post /v3/reporting/linkedin/overview
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need LinkedIn activity for a period as one team-wide total — connection requests sent and accepted, connection notes, regular messages and InMails with the replies each drew, and profile views, likes, follows, endorsements and comments, with acceptance and reply rates alongside the raw counts. There is no per-account or per-member split here; use the linkedin endpoint instead when you need the individual actions behind these totals. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account. Figures cover your whole team unless you narrow them with userIds or teamIds, or to specific senders with linkedInAccountIds, and if your role only exposes your own activity you get your own numbers whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the LinkedIn report.
# Get tasks reporting overview
Source: https://docs.reply.io/api-reference/reports/get-tasks-reporting-overview
/api-reference/bundled.yaml post /v3/reporting/tasks/overview
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need task volume for a period rolled up two ways at once — a total task count with a count and share of the total for each task type (calls, emails, LinkedIn, SMS, to-dos and WhatsApp), and the same counts repeated per team member under memberStatistics, keyed by userId. Use the tasks endpoint instead when you need the individual tasks behind these counts. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account; the window is matched against the date each task was created, or against the date it was completed when taskStatuses includes completed. Figures cover your whole team unless you narrow them with userIds or teamIds, and if your role only exposes your own activity you get your own numbers whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the tasks report.
# Get team performance overview
Source: https://docs.reply.io/api-reference/reports/get-team-performance-overview
/api-reference/bundled.yaml post /v3/reporting/team-performance/overview
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need to compare the people on your team over a period — meetings booked, contacts in sequences, meeting conversion rate, average touches per contact split into automated and manual, and average response time, returned both as a team total and per member under memberStatistics, keyed by userId. Members with a recorded response time also carry a responseRate of fast, average or slow, which ranks them against the other members in the same response rather than against a fixed threshold. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account. Figures cover your whole team unless you narrow them with userIds or teamIds, and if your role only exposes your own activity you get your own numbers whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the team performance report.
# List call activity
Source: https://docs.reply.io/api-reference/reports/list-call-activity
/api-reference/bundled.yaml post /v3/reporting/calls
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need the individual calls behind the calls report rather than its totals — one row per call, oldest first, carrying the team member who made it, the contact and phone number, the start time in your account time zone, the duration, resolution, disposition and direction, plus a link to the recording when you are allowed to listen to your team recordings. Results are returned as a page controlled by the top and skip query parameters; omit both to get the first page. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account. Rows cover your whole team unless you narrow them with userIds or teamIds, and if your role only exposes your own activity you see only your own whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the calls report.
# List email activity
Source: https://docs.reply.io/api-reference/reports/list-email-activity
/api-reference/bundled.yaml post /v3/reporting/emails
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need the individual emails behind the email report rather than its totals — one row per email sent, carrying the contact, the email account it was sent from, the sequence and step it belongs to, the A/B variant it was sent from (`variantId`), its delivery date, and whether it was delivered, opened, clicked, replied to, marked interested, bounced or opted out. Results are returned as a page controlled by the top and skip query parameters; omit both to get the first page. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account; set includeOutOfSequence to true to also return one-off emails sent outside any sequence. Rows cover your whole team unless you narrow them with userIds or teamIds, and if your role only exposes your own activity you see only your own whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the email report.
# List LinkedIn activity
Source: https://docs.reply.io/api-reference/reports/list-linkedin-activity
/api-reference/bundled.yaml post /v3/reporting/linkedin
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need the individual LinkedIn actions behind the LinkedIn report rather than its totals — one row per action, oldest first, carrying the action type, the date it happened, the LinkedIn account that performed it, the contact it targeted, the sequence step it came from and, for automated messages and replies to them, the A/B variant (`variantId`). Results are returned as a page controlled by the top and skip query parameters; omit both to get the first page. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account. Rows cover your whole team unless you narrow them with userIds or teamIds, or to specific senders with linkedInAccountIds, and if your role only exposes your own activity you see only your own whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the LinkedIn report.
# List meetings
Source: https://docs.reply.io/api-reference/reports/list-meetings
/api-reference/bundled.yaml post /v3/reporting/team-performance/meetings
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need the individual meetings behind the team performance report rather than its totals — one row per meeting, oldest first, carrying the team member credited with it, the channel it was booked through, the contact and the sequence it came from, with the booking time in your account time zone. Results are returned as a page controlled by the top and skip query parameters; omit both to get the first page. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account. Rows cover your whole team unless you narrow them with userIds or teamIds, and if your role only exposes your own activity you see only your own whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the team performance report.
# List task activity
Source: https://docs.reply.io/api-reference/reports/list-task-activity
/api-reference/bundled.yaml post /v3/reporting/tasks
_Requires the `reporting:read` scope (or a broader one that includes it)._
Use this endpoint when you need the individual tasks behind the tasks report rather than its totals — one row per task ordered by due date, carrying the assignee, the task type and its LinkedIn sub-type where one applies, the task status, its description and the contact it concerns. Results are returned as a page controlled by the top and skip query parameters; omit both to get the first page. The request body must carry a filters object; set the window inside it with either from and to or a dateRangePreset — the two cannot be combined, sending neither gives you the last seven days, and both are read in the time zone configured on your Reply account; the window is matched against the date each task was created, or against the date it was completed when taskStatuses includes completed. Rows cover your whole team unless you narrow them with userIds or teamIds, and if your role only exposes your own activity you see only your own whatever you pass. Reporting must be enabled for your team, and your role must allow viewing the tasks report.
# Batch complete tasks
Source: https://docs.reply.io/api-reference/tasks/batch-complete-tasks
/api-reference/bundled.yaml post /v3/tasks/batch/complete
_Requires the `tasks:operate` scope (or a broader one that includes it)._
Clear up to 100 tasks off the list without carrying them out. Sequence-step tasks close their step so the contact moves on.
# Choose your interface
Source: https://docs.reply.io/agents/choose-your-interface
MCP vs Skills vs CLI vs API — how the four Reply.io access layers differ and which to pick.
MCP, Skills, CLI, and API are not separate products — they are four ways to access the same
Reply.io platform. Same account, same [API key](/api-reference/authentication), same object model,
same [rate limits](/api-reference/rate-limits).
## Comparison
| | **MCP** | **Skills** | **CLI** | **API** |
| - | - | - | - | - |
| **Best for** | Agents in MCP clients (Claude, Cursor) | Coding agents that need procedure, not just tools | Shell scripts, CI, coding agents | Production integrations, webhooks, bulk |
| **Granularity** | 70 curated tools | 18 skills in 3 installable packs | 5 command groups + `reply api` passthrough | Every endpoint |
| **Install cost** | One client config entry | One `reply skills install` | One `npm install` | None (HTTP) |
| **Safety built in** | `readOnlyHint`/`destructiveHint` annotations | Hard confirmation gates + previews | None — the caller gates | Scoped keys only |
| **Coverage today** | Day-to-day operations + Jason AI SDR | Planning, launch, triage, analysis, guardrails, durable work | Auth and identity, skill installs, plus every endpoint via `reply api` | Full surface |
| **Start** | [Connect](/mcp/connect) | [Install](/skills/overview#install) | [Install](/cli/overview#install) | [Get a key](/api-reference/authentication) |
## Decision rules
* **Your agent runs in an MCP client** (Claude, Cursor, Make, n8n) → use **[MCP](/mcp/overview)**.
Richest interactive surface, and the only one with per-tool safety annotations the client can
gate on automatically.
* **Your agent has a shell** (Claude Code, Codex, CI pipelines) → use the **[CLI](/cli/overview)**,
and add **[Skills](/skills/overview)** so it follows proven procedure — previews,
verification steps, and confirmation gates included.
* **You're building a production integration** — webhooks, bulk imports, background jobs, or
anything not exposed as a tool/command → use the **[REST API](/api-reference/introduction)**.
* **You want Jason (AI SDR) programmable** — approval queues, knowledge bases, offers, playbooks →
**[MCP](/mcp/overview)** has the richest Jason toolset today; the REST
API covers the knowledge/offer/playbook layer.
## They compose
The layers are designed to be combined, not chosen once:
* **Skills drive an execution surface** — the skill decides *what* to do; the CLI, MCP, or the API
does it. `reply-adapter` is the pack that carries that execution layer, so it is the one to install
when you want your agent operating Reply.io.
* An agent can follow a **skill's procedure using MCP tools** instead of CLI commands — the
vendor-neutral skills describe platform operations, not surface-specific calls.
* **MCP for the interactive path, REST for the exhaustive one** — drop to REST for bulk
imports/updates, report exports, and webhook administration that aren't exposed as tools.
* A **CLI cron job** can do the weekly hygiene sweep while an **MCP agent** handles the
conversational work in the same workspace.
## Consistent everywhere
Whatever surface you choose, these hold:
* **One key, scoped** — `domain:verb` scopes (`contacts:read`, `sequences:operate`, …) behave
identically on every surface. See [Authentication](/api-reference/authentication).
* **One object model** — contacts, lists, sequences, threads, tasks, and Jason objects carry the
same IDs and semantics everywhere.
* **One rate-limit budget** — see [Rate limits](/api-reference/rate-limits).
* **Same safety expectations** — see [Agent safety rules](/agents/safety).
# Machine-readable indexes
Source: https://docs.reply.io/agents/machine-readable
llms.txt, OpenAPI, catalog.json, and runtime discovery — how agents read Reply.io documentation programmatically.
Every layer of Reply.io documentation is available in a machine-readable form. Use these instead of
scraping HTML.
## This site (docs.reply.io)
| Resource | URL | What it is |
| - | - | - |
| llms.txt | [`/llms.txt`](https://docs.reply.io/llms.txt) | Index of all documentation pages with descriptions |
| llms-full.txt | [`/llms-full.txt`](https://docs.reply.io/llms-full.txt) | The full documentation content in one file |
| OpenAPI spec | see [OpenAPI & Postman](/openapi-postman) | The complete v3 REST API specification (also drives the API Reference tab) |
Mintlify also serves any docs page as markdown — append `.md` to a page URL for the raw source.
## The agents portal (agents.reply.io)
The [agent discovery portal](https://agents.reply.io) publishes its own machine surface, useful as
a compact capability index before diving into full references here:
| Resource | What it is |
| - | - |
| `/catalog.json` | Machine-readable module index: modules, workflows, auth model, rate limits, MCP endpoint |
| `/llms.txt` · `/llms-full.txt` | Portal content index and full text |
| `.md` twins | Every portal page is also plain markdown — append `.md` to its URL |
| Per-module OpenAPI | Small, module-scoped OpenAPI subsets — lighter than the full spec for narrow tasks |
The portal is a discovery layer; canonical technical facts live here on docs.reply.io.
## Runtime discovery
Two sources are always current because they come from the running systems:
* **MCP `tools/list`** — the live tool catalog with full JSON schemas and safety annotations.
This is the runtime truth for MCP; regenerate the reference any time — see
[Tool reference](/mcp/tools#regenerate-this-reference).
* **CLI `--help`** — `reply --help` and `reply --help` print flags and examples, matching
the installed version exactly.
## Recommended agent reading order
1. `docs.reply.io/llms.txt` — find the relevant pages.
2. The specific page as `.md` — read only what the task needs.
3. For MCP work: `tools/list` on the live server for exact schemas.
4. For REST work: the [OpenAPI spec](/openapi-postman) for exact request/response shapes.
# Agentic capabilities
Source: https://docs.reply.io/agents/overview
The capability map for agents on the Reply.io platform — outcomes, access layers, and where the human boundary sits.
Reply.io is a sales-engagement platform an AI agent can operate end to end: find and manage
contacts, launch multichannel outreach, triage and answer replies, pull performance data, and
program Jason — Reply's AI SDR — as a supervised autopilot. Everything runs behind one scoped
[API key](/api-reference/authentication) across four access layers.
## What an agent can do today
| Outcome | Status | Where to start |
| - | - | - |
| Import and manage contacts, lists, accounts | ✅ Available | [Import and clean contacts](/guides/import-contacts) |
| Launch multichannel sequences (email + LinkedIn) | ✅ Available | [Launch multichannel outreach](/guides/launch-outreach) |
| Manage and optimize running sequences | ✅ Available | [Improve sequences every cycle](/guides/improve-sequences) |
| Triage the inbox and send approved replies | ✅ Available | [Convert replies into meetings](/guides/convert-replies-to-meetings) |
| Pull reports and per-sequence stats | ✅ Available | [Decide what to scale or fix](/guides/analyze-performance) |
| Configure Jason AI SDR (knowledge, offers, playbooks, approvals) | ✅ Available | [Build a supervised AI SDR](/guides/build-an-ai-sdr) |
| Event-driven automation via webhooks | ✅ Available | [Automate outbound end-to-end](/guides/automate-outbound) |
| Validate emails, enforce blacklists, keep lists clean | ✅ Available | [Automate outbound end-to-end](/guides/automate-outbound) |
| Search the 1B+ B2B database for new prospects | 🔜 Coming soon | [Find your ideal prospects](/guides/find-ideal-prospects) |
| Waterfall-enrich contacts (emails, phones, firmographics) | 🔜 Coming soon | [Find your ideal prospects](/guides/find-ideal-prospects) |
## The four access layers
All four surfaces operate the same platform — same key, same objects, same limits. They differ in
how an agent consumes them:
```
┌────────────────────────────┐
MCP client ──▶ │ MCP · 70 annotated tools │ ──┐
└────────────────────────────┘ │
┌────────────────────────────┐ │ ┌───────────────┐
Coding agent ──▶ │ Skill · packaged workflows│ ──┤ ───▶ │ Reply.io v3 │
│ └─▶ CLI · `reply` command │ │ │ platform │
└────────────────────────────┘ │ └───────────────┘
┌────────────────────────────┐ │
Any program ──▶ │ REST API · api.reply.io/v3│ ──┘
└────────────────────────────┘
```
* **[MCP](/mcp/overview)** — direct tool access for AI agents in MCP clients.
* **[Skills](/skills/overview)** — outbound expertise and guardrails as markdown packs; the skill
decides *what* to do, the CLI or MCP does it.
* **[CLI](/cli/overview)** — terminal and automation interface with JSON output and safety flags.
* **[API](/api-reference/introduction)** — low-level programmable integration; the exhaustive surface.
Not sure which fits? [Choose your interface](/agents/choose-your-interface).
## The human boundary today
An agent can operate everything behind the API key. Three things still need a human:
1. **Account creation** — a human signs up (14-day free trial, no credit card required).
2. **API key issuance** — created in the Reply app under **Settings → API Keys** and handed to the
agent. Keys support granular scopes — see [Authentication](/api-reference/authentication).
3. **Billing** — plan upgrades and credit purchases happen in the Reply app.
## Next steps
> [card] [Choose your interface](/agents/choose-your-interface)
>
> MCP vs Skills vs CLI vs API — decision rules and a comparison table.
> [card] [Agent safety rules](/agents/safety)
>
> High-stakes gating, scoped keys, and rate-limit etiquette across all surfaces.
> [card] [Drop-in system prompts](/agents/prompts)
>
> Ready-to-paste prompts for agents operating Reply.
> [card] [Guides](/guides/launch-outreach)
>
> Task-based guides for every outcome in the table above.
# Drop-in system prompts
Source: https://docs.reply.io/agents/prompts
Ready-to-paste system prompts for AI agents operating Reply.io — cross-surface, MCP, and CLI variants.
Paste these into an agent's system prompt to encode the platform's object model, safety rules, and
error handling. Pick the variant matching your agent's surface.
## Cross-surface platform prompt
Works for any agent operating Reply.io, regardless of access layer:
```text theme={null}
You operate the Reply.io sales-engagement platform. Rules:
1. One platform, four surfaces (API, MCP, CLI, Skills) — same objects everywhere:
contacts, lists, sequences (with steps and variants), inbox threads, tasks,
and Jason AI SDR objects (knowledge bases, offers, playbooks, approval queue).
2. Resolve before you mutate: look up exact IDs with search/list operations first.
Never invent an ID and never ask the user for one — users don't know internal IDs.
3. High-stakes actions require explicit user confirmation BEFORE executing:
sending any message, approving drafts, starting sequences, enrolling contacts,
blacklisting, changing contact owners, deleting, and switching Jason to
Autonomous. A successful call executes immediately; there is no undo.
4. Report honestly from per-item results: state exact counts ("imported 48 of 50"),
and never claim success for an item the response didn't confirm.
5. On timeouts of send-like operations, verify state with a read before retrying —
the operation may have already succeeded.
6. Respect rate limits: honor Retry-After on 429, back off on 5xx, paginate lists.
7. If a capability seems missing, check the docs (docs.reply.io) before concluding;
prefer the REST API for anything not exposed on your surface.
```
## MCP variant
For agents connected to the [Reply MCP server](/mcp/overview), use the canonical MCP prompt — it
adds tool-annotation gating, response-envelope parsing, and the MCP-specific failure guidance:
> [card] [MCP drop-in system prompt](/mcp/agent-guide#drop-in-system-prompt)
>
> The canonical prompt for MCP agents, maintained with the MCP docs.
## CLI variant
For coding agents that shell out to the [`reply` CLI](/cli/overview):
```text theme={null}
You operate Reply.io through the `reply` CLI. Rules:
1. The CLI covers authentication and identity (auth, profile, team). Everything
else goes through `reply api ` — a raw authenticated call to a v3
endpoint, e.g. `reply api /v3/sequences`. Use paths exactly as documented,
starting with /v3; the query string goes in the path.
2. Always pass --json. Data arrives on stdout, status/errors on stderr.
3. `reply api` prints {"code":,"data":} for every status and
exits 1 on >= 400 — branch on .code and read .data for the problem details.
Other commands print errors as one stderr line:
{"error":{status,code,title,detail,hint}}. Act on `hint`.
4. Exit codes: 0 = success, 1 = API/runtime error, 2 = usage error.
5. There is NO --dry-run and NO confirmation prompt. `reply api` sends exactly
what you give it. Before any write — POST/PUT/PATCH/DELETE, starting a
sequence, sending a reply — show the user the exact request and get explicit
approval first.
6. A --body switches the method to POST; override with --method. Bodies accept
inline JSON, @file, or - for stdin.
7. Paginate with the endpoint's own parameters (usually top/skip) and keep going
while the response has hasMore: true.
8. Rate limits and transient 5xx are retried by the CLI (Retry-After, backoff) —
do not add your own retry loop around writes; verify state with a GET instead.
9. Resolve IDs with a GET before mutating — never invent numeric IDs.
10. If a call fails with TEAM_REQUIRED, run `reply team list`, ask the user which
workspace to act in, then `reply team use ` or pass --team-id.
```
## When to hand the agent a Skill instead
If your agent platform supports skills (e.g. Claude Code, Codex), install
[Reply Skills](/skills/overview) rather than writing procedure into the prompt — they package the
procedure above with verification steps and confirmation gates, and update through
`reply skills update`. Keep the CLI variant prompt as a fallback for platforms without skill support.
# Agent safety rules
Source: https://docs.reply.io/agents/safety
Cross-surface safety for agents operating Reply.io — high-stakes gating, scoped keys, and rate-limit etiquette.
An agent operating Reply.io can send real messages to real prospects. A successful call executes
immediately — there is no undo. These rules apply across all four access layers.
## What counts as high-stakes
Confirm with the user before any action that:
* **Sends to a prospect** — inbox replies, approving Jason drafts, one-off outreach actions
* **Starts outreach** — starting a sequence, enrolling contacts into a sequence
* **Changes ownership or reach** — reassigning contacts, blacklisting an email or a whole domain
* **Removes work irreversibly** — rejecting a Jason draft (this also removes the contact from the
sequence), deleting contacts or lists
* **Removes supervision** — switching Jason from Review to Autonomous mode
Configuration changes (assigning mailboxes, schedules, attaching offers/playbooks) are
production-affecting but not prospect-visible — usually worth confirming too.
## How each surface enforces it
| Surface | Mechanism |
| - | - |
| **MCP** | Every tool is annotated in `tools/list`: `readOnlyHint` (31 tools) or `destructiveHint` (39). Gate on these before adding your own confirmation UX. See the [tool contract](/mcp/tool-contract) and the [high-stakes list](/mcp/agent-guide#high-stakes-tools). |
| **CLI** | No built-in gating — `reply api` sends exactly the request it is given. The caller owns the confirmation step: show the exact request, get approval, then run it. See [Using the CLI from agents](/cli/agents). |
| **Skills** | Hard confirmation gates — nothing sends, starts, or deletes without explicit approval — plus previews and verification steps. The rules live in one skill, `approval-boundaries`, shipped inside `ai-sdr-core` so no selective install can omit them. See [Skills](/skills/overview#safety-model). |
| **API** | No built-in gating — your integration is the gate. Use scoped keys (below) to bound the blast radius, and verify state with a read before retrying any timed-out write. |
> [!WARNING]
>
> A timed-out send may already have succeeded server-side — on any surface. Verify with a read
> before retrying anything that reaches a prospect.
## Scoped keys bound the blast radius
API keys support granular `domain:verb` scopes (`contacts:read`, `sequences:operate`,
`inbox:write`, …) that behave identically on every surface — a key with `sequences:read` can list
sequences but not start them, whether the call arrives via REST, MCP, or the CLI.
Give an agent the narrowest scope that covers its job; issue separate keys for separate agents so
one can be revoked without stopping the others. Details: [Authentication](/api-reference/authentication).
## Rate-limit etiquette
One budget covers all surfaces — see [Rate limits](/api-reference/rate-limits).
* Honor `Retry-After` on `429`; back off exponentially on `5xx`. (The [CLI](/cli/agents) and MCP
server handle this for you.)
* Paginate instead of hammering: `top`/`skip` on MCP, and the endpoint's own paging parameters
(usually `top`/`skip`) when calling through REST or `reply api`.
* Never auto-retry a send, approval, start, or enrollment — verify first (see the
[safe-retry matrix](/mcp/tool-contract#safe-retry-matrix); the same logic applies to REST and CLI).
* If `429` keeps coming during normal work, the REST limits are too low for the job: tell your user. More
limit comes from [API limit packages](/api-reference/rate-limits#raise-your-limits). Claim packages from the
shared pool only when the user asks, since every user in the organization draws on it; when none are
available, the organization owner buys more.
## Report honestly
Batch operations return per-item results (`NotProcessed`, `AffectedContactIds`, per-row import
failures). Read them and report exact counts — "reassigned 48 of 50" — and never claim an item
succeeded unless the response says so.
## Next
* [Drop-in system prompts](/agents/prompts) — these rules, pre-packaged for your agent
* [MCP tool contract](/mcp/tool-contract) — envelopes, error codes, and the retry matrix in detail
# Create a personal AI prompt
Source: https://docs.reply.io/api-reference/ai-prompts/create-a-personal-ai-prompt
/api-reference/bundled.yaml post /v3/ai-prompts
_Requires the `sequences:write` scope (or a broader one that includes it)._
Save your own AI prompt for a sequence step type so you can reuse it. The name must be unique among your personal prompts.
# Delete a personal AI prompt
Source: https://docs.reply.io/api-reference/ai-prompts/delete-a-personal-ai-prompt
/api-reference/bundled.yaml delete /v3/ai-prompts/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Delete one of your personal AI prompts. Steps already using it keep their saved text. Library prompts cannot be deleted.
# List AI prompts
Source: https://docs.reply.io/api-reference/ai-prompts/list-ai-prompts
/api-reference/bundled.yaml get /v3/ai-prompts
_Requires the `sequences:read` scope (or a broader one that includes it)._
Get the AI prompts available for a sequence step type, in one call with no paging. Mixes Reply's library prompts and yours.
# Preview a comment prompt against a LinkedIn post
Source: https://docs.reply.io/api-reference/ai-prompts/preview-a-comment-prompt-against-a-linkedin-post
/api-reference/bundled.yaml post /v3/ai-prompts/preview/linkedin-post
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Test a comment prompt against a real person's latest LinkedIn post. The response shows which post the comment was written for.
# Preview a comment prompt against a sample post
Source: https://docs.reply.io/api-reference/ai-prompts/preview-a-comment-prompt-against-a-sample-post
/api-reference/bundled.yaml post /v3/ai-prompts/preview/sample
_Requires the `sequences:operate` scope (or a broader one that includes it)._
Try a comment prompt against a generic sample post. Nothing is fetched from LinkedIn and no Reply credits are spent.
# Update a personal AI prompt
Source: https://docs.reply.io/api-reference/ai-prompts/update-a-personal-ai-prompt
/api-reference/bundled.yaml put /v3/ai-prompts/{id}
_Requires the `sequences:write` scope (or a broader one that includes it)._
Rename one of your personal AI prompts or rewrite its text. Both fields are replaced, so send everything you want to keep.
# Intent signal industries typeahead
Source: https://docs.reply.io/api-reference/ai-sdr-intent-signals/intent-signal-industries-typeahead
/api-reference/bundled.yaml get /v3/ai-sdr/intent-signals/industries
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Get the industries you can reference in an AI SDR intent signal. The id is what you send as technologyUsed.industryId.
# Technologies typeahead
Source: https://docs.reply.io/api-reference/ai-sdr-intent-signals/technologies-typeahead
/api-reference/bundled.yaml get /v3/ai-sdr/intent-signals/technologies
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Get the technologies you can reference in an AI SDR intent signal. Send the slug in technologyUsed.technologies.
# Create an AI learning
Source: https://docs.reply.io/api-reference/ai-sdr-learnings/create-an-ai-learning
/api-reference/bundled.yaml post /v3/ai-sdr/learnings
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need a new standing rule for how the AI writes. text is required and
limited to 1000 characters, and categories says where the rule applies — personalizedMessage for
outbound drafting, replyHandling for answering incoming mail, or both. scope decides who the rule
binds: user for yourself across all your sequences, sequence for named sequences only,
workspace for everyone in your team, or organization for every workspace in the org.
sequenceIds names the sequences — at most 50 and no repeats, each one you can see — and is
required for the sequence scope and rejected for every other one. Creating a workspace or
organization learning needs the matching permission, and an organization learning needs you to
belong to one — without either the call is refused and nothing is written. A learning created
here is always enabled and counts as manually authored, so it can be refused with a conflict when
those categories and scope already hold as many manually authored learnings as they may; the
message says which budget is full. The created learning is returned in full with its assigned
id — unless the service cannot be reached to read it straight back, in which case the response
carries the assigned id and the fields you sent rather than the stored learning. Contradictions
with your other learnings are looked for after the learning is stored, so conflictState comes
back as none here — read the learning again a moment later to see its conflict standing.
The AI Learnings feature must be enabled for your team.
# Delete an AI learning
Source: https://docs.reply.io/api-reference/ai-sdr-learnings/delete-an-ai-learning
/api-reference/bundled.yaml delete /v3/ai-sdr/learnings/{id}
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when a learning should stop shaping what the AI writes for good. To keep the
learning but stop it applying, patch it with isEnabled set to false instead. Only a learning you
own can be deleted: one a team or organization admin set for everyone is not yours to remove. A
successful call returns no content. The AI Learnings feature must be enabled for your team.
# Get an AI learning
Source: https://docs.reply.io/api-reference/ai-sdr-learnings/get-an-ai-learning
/api-reference/bundled.yaml get /v3/ai-sdr/learnings/{id}
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Use this endpoint when you need a single AI learning by its id, including the rules it clashes
with. Alongside the text, categories, scope and status you already see in the list, conflicts
names every other learning this one contradicts, quoting its text and saying which of the two
currently applies: takesPrecedence means this learning wins, overridden means the other one does,
and unresolved means neither is applied until somebody settles it. A learning a team or
organization admin set for everyone can be read here but not changed unless you hold the matching
permission. The AI Learnings feature must be enabled for your team.
# List AI learnings
Source: https://docs.reply.io/api-reference/ai-sdr-learnings/list-ai-learnings
/api-reference/bundled.yaml get /v3/ai-sdr/learnings
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `ai-sdr:read` scope (or a broader one that includes it)._
Use this endpoint when you need to see the AI learnings that shape how the AI writes for you —
standing rules such as never opening with "Hello" or keeping subject lines short. The list holds
your own learnings plus the ones a team or organization admin has set for everyone, so a rule you
did not write can appear here; isOwn and ownerUserId tell them apart. Results are returned as a
page controlled by the top and skip query parameters; top defaults to 100 and cannot exceed 1000,
and search keeps only the learnings whose text matches. Each entry carries the text, the
categories it applies to, its scope, whether it is enabled, and its conflict standing — a
learning whose conflictState is unresolved is held back and is shaping nothing until the
contradiction is settled. Read a single learning to see which other learnings it clashes with.
The AI Learnings feature must be enabled for your team.
# Update an AI learning
Source: https://docs.reply.io/api-reference/ai-sdr-learnings/update-an-ai-learning
/api-reference/bundled.yaml patch /v3/ai-sdr/learnings/{id}
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `ai-sdr:write` scope (or a broader one that includes it)._
Use this endpoint when you need to change part of an existing AI learning without resending all
of it; the full updated learning comes back in the response. Send at least one of text,
categories, scope, isEnabled and sequenceIds — every field you leave out keeps its current value.
Leaving text out is the way to switch a learning on or off without touching its wording:
rewording a learning the AI generated turns it into a manually authored one, which can hit the
manual limit even though the number of learnings does not change, and the call is then refused
with a conflict. sequenceIds names at most 50 sequences with no repeats, and any it adds must be
ones you can see; it is required once the learning ends up on the sequence scope and rejected on
every other one. Moving a sequence-scoped learning to another scope drops its sequenceIds for
you — send scope on its own — but sending sequenceIds alongside a scope that does not take them
is still refused.
Moving a learning to the workspace or organization scope needs the matching permission, and a
learning somebody else set for your team or org cannot be changed by you at all. The AI Learnings
feature must be enabled for your team.
# Upload attachment
Source: https://docs.reply.io/api-reference/attachments/upload-attachment
/api-reference/bundled.yaml post /v3/attachments
_Requires the `other:write` scope (or a broader one that includes it)._
Upload a file once and reuse it across outbound messages. Send it as multipart/form-data in a single field named file.
# Upload voice attachment
Source: https://docs.reply.io/api-reference/attachments/upload-voice-attachment
/api-reference/bundled.yaml post /v3/attachments/voice
Turn a recorded audio file into a LinkedIn voice message. Send it as multipart/form-data in a single field named file.
# Cancel a background job
Source: https://docs.reply.io/api-reference/background-jobs/cancel-a-background-job
/api-reference/bundled.yaml post /v3/background-jobs/{jobId}/cancel
_Requires the `other:operate` scope (or a broader one that includes it)._
Stop a background job that is no longer worth finishing. Returns 204, and you can record an optional reason for stopping it.
# Get a background job
Source: https://docs.reply.io/api-reference/background-jobs/get-a-background-job
/api-reference/bundled.yaml get /v3/background-jobs/{jobId}
_Requires the `other:read` scope (or a broader one that includes it)._
Check how far a background job has got. Poll until status settles on Done, Failed, Cancelled, or Expired, and read progress.
# List background jobs
Source: https://docs.reply.io/api-reference/background-jobs/list-background-jobs
/api-reference/bundled.yaml get /v3/background-jobs
_Requires the `other:read` scope (or a broader one that includes it)._
See the asynchronous work you've started and where each job stands, running and finished alike. Paged with top and skip.
# Get billing details
Source: https://docs.reply.io/api-reference/billing/get-billing-details
/api-reference/bundled.yaml get /v3/billing
_Requires the `billing:read` scope (or a broader one that includes it)._
See the plan you are on and how many active contacts the current billing month has consumed, day by day. A
contact counts once per pool per month, on the day it is first touched. The `activeContacts` section follows
`billingScope`: under `organization` it holds one pool shared by every team, with each day split across the
teams you belong to; under `team` it holds one entry per team you can see, each with its own subscription
and pool. Available to the organization owner, who sees every team, and to users with the Plans and Billing
permission, who see the teams they belong to.
# Buy a domain with mailboxes
Source: https://docs.reply.io/api-reference/domains/buy-a-domain-with-mailboxes
/api-reference/bundled.yaml post /v3/email-accounts/procurement/domains/purchase
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:write` scope (or a broader one that includes it)._
Orders a domain and the mailboxes that send from it.
Send serviceProvider (google or microsoft) and domain.mailboxes with 1 to 5 entries, exactly one with isAdmin true.
Returns a jobId — poll GET /v3/background-jobs/{jobId} for the outcome.
When the job ends as Failed, its jsonDataResult carries an `errorCode` and a message — on `domain.failureMessage` when the domain is the cause, otherwise on the top-level `failureMessage`. Every code except `procurementOrder.submitFailed` means no payment was charged.
| `errorCode` | Meaning |
|---|---|
| `procurementOrder.domainNoLongerAvailable` | The domain is no longer available for registration. Choose a different domain. |
| `procurementOrder.availabilityCheckFailed` | The domain availability check could not be completed. Contact support if this keeps happening. |
| `procurementOrder.domainAlreadyExists` | A workspace already exists for this domain. |
| `procurementOrder.workspaceValidationFailed` | Workspace validation failed for the domain. |
| `procurementOrder.workspaceValidationTimedOut` | Workspace validation did not finish in time. Retry in a few minutes. |
| `procurementOrder.paymentDeclined` | The payment provider declined the payment. |
| `procurementOrder.paymentActionRequired` | The saved payment method needs interactive authentication. Complete it in the app, then retry. |
| `procurementOrder.validation` | The domain or mailbox configuration was rejected, or the current plan cannot take the order. |
| `procurementOrder.temporarilyUnavailable` | A transient failure before the charge. Retry. |
| `procurementOrder.unknown` | The order could not be reliably priced. Retry, or contact support. |
| `procurementOrder.submitFailed` | Payment was taken, but the order or one of its items failed at the provider. Check the item failureMessage and contact support before ordering again. |
If the job ends as Expired, nothing reported progress for 26 hours and the job was closed: jsonDataResult is `{"timedOut": true}`, with no `errorCode`. The outcome is unknown — the payment may have been taken and the order placed. Do not order again: check GET /v3/email-accounts/procurement/domains, where the domain appears once the provider accepted the order, and contact support with the jobId if it is not there.
# Estimate order cost
Source: https://docs.reply.io/api-reference/domains/estimate-order-cost
/api-reference/bundled.yaml post /v3/email-accounts/procurement/domains/estimate
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:read` scope (or a broader one that includes it)._
Price breakdown for a domain and its mailboxes before you order — per-seat unit prices, subtotal, discount and total, all in cents.
Send serviceProvider (google or microsoft) and domain.mailboxes with 1 to 5 entries.
Estimate only a domain returned by GET /v3/email-accounts/procurement/domains/available within the last 49 hours: the estimate reads the domain price that search stored. Any other domain fails with 400 `procurementOrder.unknown` — search for it, then retry. A domain the team already owns with the same serviceProvider is exempt. The purchase does not depend on a prior search; it checks availability and price itself.
# Find available domains
Source: https://docs.reply.io/api-reference/domains/find-available-domains
/api-reference/bundled.yaml get /v3/email-accounts/procurement/domains/available
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:read` scope (or a broader one that includes it)._
Domain names available to buy for mailbox procurement, with purchase and renewal prices in cents.
Search one label in domainName against up to 5 TLDs in tlds (com, net, org, biz, live).
# Add mailboxes
Source: https://docs.reply.io/api-reference/mailboxes/add-mailboxes
/api-reference/bundled.yaml post /v3/email-accounts/procurement/domains/{domainId}/mailboxes/purchase
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:write` scope (or a broader one that includes it)._
Adds mailboxes to a domain your team already bought. Seats your plan already covers are free; extra seats are charged to the payment card on file.
Send mailboxes with 1 to 5 entries. A domain holds at most 5 mailboxes, existing ones included. isAdmin may be true on one entry only, and only when the domain has no admin mailbox yet.
Take domainId from GET /v3/email-accounts/procurement/domains. Returns a jobId — poll GET /v3/background-jobs/{jobId} for the outcome.
When the job ends as Failed, its jsonDataResult carries an `errorCode` and a top-level `failureMessage`. Only `procurementOrder.submitFailed` can follow a charge.
| `errorCode` | Meaning |
|---|---|
| `procurementOrder.domainNotFound` | The domain was removed before the order ran. |
| `procurementOrder.validation` | The mailbox configuration was rejected, the domain cannot take mailboxes yet, or the current plan cannot take the order. |
| `procurementOrder.noPaymentMethod` | Extra seats must be bought and no payment card is on file. Add one in billing settings, then retry. |
| `procurementOrder.paymentDeclined` | The payment provider declined the payment. |
| `procurementOrder.paymentActionRequired` | The saved payment method needs interactive authentication. Complete it in the app, then retry. |
| `procurementOrder.temporarilyUnavailable` | A transient failure. Retry — unless failureMessage says the order may have been placed; then contact support first. |
| `procurementOrder.unknown` | The order could not be reliably priced. Retry, or contact support. |
| `procurementOrder.submitFailed` | The order was submitted, and paid when extra seats were needed, but could not be confirmed with the provider. Contact support before ordering again. |
If the job ends as Expired, nothing reported progress for 26 hours and the job was closed: jsonDataResult is `{"timedOut": true}`, with no `errorCode`. The outcome is unknown — extra seats may have been charged and the mailboxes ordered. Do not order again; contact support with the jobId.
# Estimate mailbox cost
Source: https://docs.reply.io/api-reference/mailboxes/estimate-mailbox-cost
/api-reference/bundled.yaml post /v3/email-accounts/procurement/domains/{domainId}/mailboxes/estimate
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:read` scope (or a broader one that includes it)._
Price breakdown for adding mailboxes to a domain your team already bought — per-seat unit prices, subtotal, discount and total, all in cents. Call it before Add mailboxes to see what the order will charge.
Send mailboxes with 1 to 5 entries. A domain holds at most 5 mailboxes, existing ones included.
Take domainId from GET /v3/email-accounts/procurement/domains. The body matches Add mailboxes, so one body works for both.
# Reconnect a purchased mailbox
Source: https://docs.reply.io/api-reference/mailboxes/reconnect-a-purchased-mailbox
/api-reference/bundled.yaml post /v3/email-accounts/{id}/procurement/reconnect
**Coming soon.** This endpoint will be available by early November 2026.
_Requires the `channels:operate` scope (or a broader one that includes it)._
Asks the mail provider to reconnect a mailbox your team bought through mailbox procurement. The provider sends a consent link; the mailbox is reconnected once someone follows it. No request body.
The 202 has an empty body and no job to poll: the reconnect completes outside this request.
Only an active mailbox can be reconnected. Each mailbox allows one reconnect per 60 minutes and 3 per 7 days; reconnects started in the app and automatic retries count toward the same limits. When a limit is reached, the 429 carries a `Retry-After` header with the seconds to wait. Requires access to the team's settings.
# Find pre-warmed domains to buy
Source: https://docs.reply.io/api-reference/pre-warmed-domains/find-pre-warmed-domains-to-buy
/api-reference/bundled.yaml get /v3/email-accounts/procurement/pre-warmed-domains/available
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:read` scope (or a broader one that includes it)._
Lists the pre-warmed bundles currently on sale for one mail provider. Each bundle is a domain plus mailboxes that are already warming, bought as a whole. The list is read live on every request and reserves nothing.
Every bundle shows the same flat prices: `annualDomainPrice` 2500 and `monthlyMailboxPrice` 1500, in cents.
Results are paged with top and skip; top defaults to 100 and cannot exceed 100. The order is stable while the inventory does not change.
# List owned pre-warmed domains
Source: https://docs.reply.io/api-reference/pre-warmed-domains/list-owned-pre-warmed-domains
/api-reference/bundled.yaml get /v3/email-accounts/procurement/pre-warmed-domains
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:read` scope (or a broader one that includes it)._
Pre-warmed domains your team bought through mailbox procurement, newest first. Domains bought as new registrations are listed by GET /v3/email-accounts/procurement/domains; the two lists share one id space and never overlap.
Each entry carries the mail provider, the subscription and setup state, and the expiry date. Pre-warmed domains cannot be renewed.
Results are paged with top and skip; top defaults to 100 and cannot exceed 1000.
# Estimate a domain renewal
Source: https://docs.reply.io/api-reference/purchased-domains/estimate-a-domain-renewal
/api-reference/bundled.yaml post /v3/email-accounts/procurement/domains/{domainId}/renew/estimate
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:read` scope (or a broader one that includes it)._
Previews what renewing one purchased domain would charge, at the provider's current price. Nothing is charged and nothing is renewed. No request body.
It applies the same checks as POST /v3/email-accounts/procurement/domains/{domainId}/renew, so an estimate that succeeds means the renewal can be requested now. The total can still change by the time the renewal is charged, since the provider's price is taken again then.
# List purchased domains
Source: https://docs.reply.io/api-reference/purchased-domains/list-purchased-domains
/api-reference/bundled.yaml get /v3/email-accounts/procurement/domains
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:read` scope (or a broader one that includes it)._
Domains your team bought through mailbox procurement, newest first. Pre-warmed domains are not listed here.
Each entry carries the mail provider, the subscription and setup state, the expiry date, and whether the domain can be renewed now.
Results are paged with top and skip; top defaults to 100 and cannot exceed 1000.
# Renew a purchased domain
Source: https://docs.reply.io/api-reference/purchased-domains/renew-a-purchased-domain
/api-reference/bundled.yaml post /v3/email-accounts/procurement/domains/{domainId}/renew
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:write` scope (or a broader one that includes it)._
Renews one domain your team bought for another year and charges the card on file. Preview the price first with POST /v3/email-accounts/procurement/domains/{domainId}/renew/estimate.
A domain can be renewed while its subscription is active and it expires in 1 to 45 days — `renewStatus` is `renewable` in GET /v3/email-accounts/procurement/domains. Only the team owner, or a member with billing permission, can renew.
Returns a jobId — poll GET /v3/background-jobs/{jobId} for the outcome. Nothing has been charged when the 202 arrives. The job stays Processing until the provider confirms the renewal, which can take up to three days. When it ends as Done, its jsonDataResult carries the new `expireOn` and `renewalPriceCents`, the price the charge was checked against.
When the job ends as Failed, its jsonDataResult carries an `errorCode` and a `failureMessage`. The codes in the first table mean nothing was charged, and you can retry at once:
| `errorCode` | Meaning |
|---|---|
| `procurementDomain.featureDisabled` | Domain renewal is not enabled for your team. |
| `procurementDomain.notFound` | The domain no longer exists. |
| `procurementDomain.validation` | The domain is a pre-warmed domain, which cannot be renewed. |
| `procurementDomain.renewalInProgress` | Another renewal of this domain started in the meantime. Do not retry; check `renewStatus`. |
| `procurementDomain.notRenewable` | Either the domain stopped being renewable (its subscription is not active, or it is outside the 45-to-1-day window), or the renewal cannot be charged for this workspace right now — review the billing settings in the app, then retry. The `failureMessage` says which. |
| `procurementDomain.renewalPriceUnavailable` | The renewal price could not be confirmed: the provider may be temporarily unavailable, or may no longer offer a renewal for this domain. Retry later, or contact support if this persists. |
| `procurementDomain.temporarilyUnavailable` | One of three cases, told apart by the `failureMessage`: a transient failure (retry); the renewal could not be reliably priced (retry, or contact support if this persists); or the discount the renewal was priced with is no longer valid (retry — the renewal is priced without it). |
| `procurementDomain.paymentDeclined` | Either the payment could not be completed — check the payment method in billing settings, then retry — or payments are disabled for this workspace — contact support to enable them, then retry. |
| `procurementDomain.paymentActionRequired` | The saved payment method needs interactive authentication, which this API cannot complete. Update the payment method or complete billing verification in the app, then retry. |
The codes in the second table mean the payment may have been taken. Do not renew again — a new request for the same domain is refused with 409 for 24 hours. Contact support with the jobId:
| `errorCode` | Meaning |
|---|---|
| `procurementDomain.renewalFailed` | The provider reported that the renewal failed, so the domain was not renewed. The charge needs review. |
| `procurementDomain.renewalNotConfirmed` | One of three cases, told apart by the `failureMessage`: the payment was processed, but the renewal could not be confirmed with the provider; the payment may or may not have been charged; or the provider never reported a final status for the renewal. |
If the job ends as Expired, nothing reported progress for 26 hours and the job was closed: jsonDataResult is `{"timedOut": true}`, with no `errorCode`. The outcome is unknown — the payment may have been taken and the domain renewed. Do not renew again: check `expireOn` in GET /v3/email-accounts/procurement/domains, and contact support with the jobId.
# Get API limit packages
Source: https://docs.reply.io/api-reference/rate-limits/get-api-limit-packages
/api-reference/bundled.yaml get /v3/settings/api-limit-packages
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `settings:read` scope (or a broader one that includes it)._
See your organization's pool of API limit packages and the packages you hold. Each active package adds the
standard API rate limits once more for you alone: with 2 active packages every limit is 3 times the standard
one. The organization owner buys packages in Plans & Billing in the Reply app, and each user claims them with
`PUT /v3/settings/api-limit-packages/mine`.
# Get rate limits
Source: https://docs.reply.io/api-reference/rate-limits/get-rate-limits
/api-reference/bundled.yaml get /v3/rate-limits
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_No scope required — any valid API key can call this endpoint._
See how much of each rate limit you have used and when it resets. Every named limit comes with the standard
limit, the limit that applies to you, the requests used and remaining in the current window, and the time
the count resets — so you can plan around a limit before you hit `429`. Calls to this endpoint count toward
your limits like any other request.
# Set your API limit packages
Source: https://docs.reply.io/api-reference/rate-limits/set-your-api-limit-packages
/api-reference/bundled.yaml put /v3/settings/api-limit-packages/mine
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `settings:write` scope (or a broader one that includes it)._
Set how many packages from the pool raise your own limits. `count` is the total you want to hold, not the
number to add, and `0` releases all of yours to the pool. You can raise your count by at most
`pool.available`; lowering it always succeeds. Your new limits apply within about 30 seconds, and
`GET /v3/rate-limits` shows them.
# List country states
Source: https://docs.reply.io/api-reference/registration/list-country-states
/api-reference/bundled.yaml get /v3/email-accounts/procurement/geo/states
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:read` scope (or a broader one that includes it)._
State and region names the mailbox provider recognizes for a country, sorted alphabetically. Use one as state when you register the domain owner.
Pass countryCode as a 2-letter ISO 3166-1 alpha-2 code, e.g. US. A country without regions returns an empty list.
# Register domain owner details
Source: https://docs.reply.io/api-reference/registration/register-domain-owner-details
/api-reference/bundled.yaml post /v3/email-accounts/procurement/users
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `channels:write` scope (or a broader one that includes it)._
Contact details and postal address that domain registrations are filed under.
Register once per team — the other Mailbox Procurement endpoints return 403 until you do.
# Schemas
Source: https://docs.reply.io/api-reference/schemas
Object models used across the Reply API v3, grouped by resource domain.
Reference for the objects the Reply API v3 accepts and returns. Each entry links to a dedicated page with the full field list, types, and descriptions.
## Contacts & lists
| Schema | Description |
| - | - |
| [Contact](/api-reference/schemas/contact) | Contact response model |
| [Contact Account](/api-reference/schemas/contact-account) | A contact account representing a company or organization |
| [Contact Account Contact](/api-reference/schemas/contact-account-contact) | A contact linked to a contact account |
| [Contact Account Details](/api-reference/schemas/contact-account-details) | A single contact account, including the resolved email provider |
| [Contact Account List](/api-reference/schemas/contact-account-list) | Account list entity |
| [Contact Account Note](/api-reference/schemas/contact-account-note) | A free-text note recorded on an account |
| [Contact Account Stage](/api-reference/schemas/contact-account-stage) | Stage assigned to a contact account |
| [Contact Enrollment Result](/api-reference/schemas/contact-enrollment-result) | Outcome of enrolling one imported contact into `options.sequenceId`. |
| [Contact Import Enrollment Summary](/api-reference/schemas/contact-import-enrollment-summary) | Enrollment totals for the request, so a large import can be checked without walking every item. |
| [Contact Inbox Thread](/api-reference/schemas/contact-inbox-thread) | Inbox thread summary as it appears on a single contact's timeline. |
| [Contact List](/api-reference/schemas/contact-list) | Contact list entity |
| [Contact List Reference](/api-reference/schemas/contact-list-ref) | Lightweight contact list reference |
| [Contact Note](/api-reference/schemas/contact-note) | A free-text note recorded on a contact's timeline |
## Sequences
| Schema | Description |
| - | - |
| [AI SDR sequence settings](/api-reference/schemas/sequence) | AI SDR-specific settings of a sequence. |
| [Sequence](/api-reference/schemas/sequence-response) | Full representation of a sequence, including its schedule and the email and LinkedIn accounts used to send from it. |
| [Sequence Contact](/api-reference/schemas/sequence-contact-item) | A contact enrolled in a sequence with sequence-specific metadata |
| [Sequence Contact Not Processed Item](/api-reference/schemas/sequence-contact-not-processed-item) | Why one contact was not enrolled. |
| [Sequence Contact Not Processed Reason Group](/api-reference/schemas/sequence-contact-not-processed-reason-group) | How many contacts a single reason accounts for, so a large batch can be reported without walking every entry of `notProcessed`. |
| [Sequence Contacts List](/api-reference/schemas/sequence-contact) | Response model for listing contacts in a sequence with pagination |
| [Sequence Contacts List with Extended State](/api-reference/schemas/sequence-contact-state) | Response model for listing contacts in a sequence with pagination, including extended state columns |
| [Sequence Email Account](/api-reference/schemas/sequence-email-account) | An email account linked to a sequence for sending outbound emails. |
| [Sequence Folder](/api-reference/schemas/sequence-folder) | A folder for organizing sequences |
| [Sequence LinkedIn Account](/api-reference/schemas/sequence-linkedin-account) | A LinkedIn account linked to a sequence |
| [Sequence Step Info](/api-reference/schemas/sequence-step-info) | Position of the contact within a sequence's step graph. |
| [Sequence structure](/api-reference/schemas/sequence-structure-response) | A reusable outline of AI SDR sequence steps: which channels the steps use and in what order. |
| [Sequence Template](/api-reference/schemas/sequence-template-base) | A sequence template |
| [Sequence Templates List](/api-reference/schemas/sequence-templates-list) | Response model for listing sequence templates grouped by scope |
| [Step Variant](/api-reference/schemas/variant) | A text variant for a sequence step |
## Email accounts
| Schema | Description |
| - | - |
| [Email Account Detail](/api-reference/schemas/email-account-detail) | Full detailed representation of an email account, including all configuration sections. |
| [Email Account Stats](/api-reference/schemas/email-account-stats) | |
| [Email Account Tag](/api-reference/schemas/email-account-tag) | An email account tag used for organizing and filtering accounts. |
## Email templates
| Schema | Description |
| - | - |
| [Email Template](/api-reference/schemas/email-template) | Full representation of an email template including timestamps. |
| [Email Template Attachment](/api-reference/schemas/email-template-attachment) | Attachment associated with an email template. |
| [Email Template Folder](/api-reference/schemas/email-template-folder) | An email template folder for organizing templates. |
| [Email Template Variables](/api-reference/schemas/email-template-variables) | Available template variables grouped by category. |
| [Render Error](/api-reference/schemas/email-template-render-error) | An error encountered during template rendering. |
| [Render Template Result](/api-reference/schemas/email-template-render-result) | Result of rendering an email template with variable substitution. |
| [Variable Info](/api-reference/schemas/email-template-variable-info) | Information about a single template variable. |
## Inbox
| Schema | Description |
| - | - |
| [Inbox Category](/api-reference/schemas/category) | Inbox thread category. |
| [Inbox Thread](/api-reference/schemas/thread) | Full inbox thread with the contact, channel-specific account ids, sequence, category, meeting-intent flag, and the ordered list of messages. |
| [Inbox Thread AI Draft](/api-reference/schemas/thread-ai-draft) | The thread's pending AI-drafted reply, awaiting review. |
| [Inbox Thread Category Reference](/api-reference/schemas/thread-category) | Minimal category reference embedded in thread responses. |
| [Inbox Thread Change](/api-reference/schemas/thread-change) | One changed inbox thread, as of its latest activity. |
| [Inbox Thread Contact](/api-reference/schemas/thread-contact) | Contact party on the other end of an inbox thread. |
| [Inbox Thread Message Status](/api-reference/schemas/thread-message-status) | Per-message status. |
| [Inbox Thread Sequence](/api-reference/schemas/thread-sequence) | Minimal sequence reference attached to an inbox thread. |
| [Inbox Thread Status](/api-reference/schemas/thread-status) | Aggregated thread state, derived from the latest message. |
## Tasks
| Schema | Description |
| - | - |
| [Task](/api-reference/schemas/task-response) | Full task detail returned by GET by ID, Create, and Update endpoints. |
## LinkedIn
| Schema | Description |
| - | - |
| [Connection Link](/api-reference/schemas/connection-link) | A link for connecting a LinkedIn account via browser extension. |
| [Connection Link With Pending](/api-reference/schemas/connection-link-with-pending) | A connection link with the associated pending account ID. |
| [LinkedIn Account](/api-reference/schemas/linkedin-account) | Full representation of a LinkedIn account. |
| [LinkedIn Account Limits](/api-reference/schemas/linkedin-account-limits) | Daily limits configuration for a LinkedIn account. |
| [LinkedIn Account Limits Values](/api-reference/schemas/linkedin-account-limits-values) | Individual daily limit values for LinkedIn automation actions. |
| [LinkedIn Account Revoke Settings](/api-reference/schemas/linkedin-account-revoke-settings) | Connection revocation settings for a LinkedIn account. |
| [LinkedIn Account Toggle Status](/api-reference/schemas/linkedin-account-toggle-status) | Response after toggling a LinkedIn account status. |
| [LinkedIn Account Usage](/api-reference/schemas/linkedin-account-usage) | Daily usage statistics for a LinkedIn account. |
| [LinkedIn Account Voice Profile](/api-reference/schemas/linkedin-account-voice-profile) | Voice profile associated with a LinkedIn account. |
| [LinkedIn Action Item](/api-reference/schemas/linkedin-action-item) | Individual LinkedIn action record in a reporting list |
| [Pending LinkedIn Account](/api-reference/schemas/pending-linkedin-account) | A LinkedIn account that is pending connection. |
## Schedules & holidays
| Schema | Description |
| - | - |
| [Holiday](/api-reference/schemas/holiday) | A single holiday entry within a calendar. |
| [Holiday Calendar](/api-reference/schemas/holiday-calendar) | Full representation of a holiday calendar including individual holidays. |
| [Holiday Input](/api-reference/schemas/holiday-input) | A holiday entry for creating or updating a calendar. |
| [Schedule](/api-reference/schemas/schedule) | Full representation of a schedule with timing configuration. |
| [Schedule Time](/api-reference/schemas/schedule-time) | A time of day represented as hour and minute. |
| [Schedule Timing](/api-reference/schemas/schedule-timing) | Timing configuration for a single day of the week. |
| [Schedule Timing Time Range](/api-reference/schemas/schedule-timing-time-range) | A time range within a day. |
## Blocklist rules
| Schema | Description |
| - | - |
| [Domain Blacklist Rule](/api-reference/schemas/domain-rule) | A blacklist rule that blocks a domain pattern |
| [Email Blacklist Rule](/api-reference/schemas/email-rule) | A blacklist rule that blocks an email pattern |
| [Email Exception Blacklist Rule](/api-reference/schemas/email-exception-rule) | An exception rule that allows an email pattern even if it matches a blacklist rule |
## AI SDR
| Schema | Description |
| - | - |
| [Knowledge Base](/api-reference/schemas/knowledge-base) | Detailed representation of a knowledge base. |
| [Knowledge Base Document](/api-reference/schemas/knowledge-base-document) | A file document attached to a knowledge base. |
| [Knowledge Base Link](/api-reference/schemas/knowledge-base-link) | A web link attached to a knowledge base. |
| [Knowledge Base Media](/api-reference/schemas/knowledge-base-media) | A media file attached to a reply handler or reengagement card. |
| [Offer](/api-reference/schemas/offer) | Detailed representation of an offer — the bundle of company-context inputs the AI SDR uses to personalize outreach. |
| [Playbook](/api-reference/schemas/playbook) | Detailed representation of a playbook, returned by get/create/update responses. |
| [Playbook draft](/api-reference/schemas/playbook-draft) | The AI-generated playbook draft for a sequence. |
| [Playbook Sequence](/api-reference/schemas/playbook-sequence) | An AI SDR sequence the playbook is attached to. |
| [Playbook Style File](/api-reference/schemas/playbook-style-file) | A single style file attached to a playbook. |
| [Reengagement Card](/api-reference/schemas/reengagement-card) | Detailed representation of a reengagement card. |
| [Reply Handler](/api-reference/schemas/reply-handler) | Detailed representation of a reply handler. |
## Reports & analytics
| Schema | Description |
| - | - |
| [Calls Overview Response](/api-reference/schemas/calls-overview-response) | Aggregated call statistics with per-member breakdown |
| [Channel Efficiency Overview Response](/api-reference/schemas/channel-efficiency-overview-response) | Cross-channel efficiency statistics |
| [Emails Overview Response](/api-reference/schemas/emails-overview-response) | Email delivery and engagement metrics |
| [LinkedIn Overview Response](/api-reference/schemas/linkedin-overview-response) | LinkedIn engagement metrics overview |
| [Sequence Email Stats Response](/api-reference/schemas/sequence-email-stats-response) | Email stats for one sequence, broken down per step and per A/B variant — the figures on the sequence's Stats → Email tab. |
| [Sequence LinkedIn Stats Response](/api-reference/schemas/sequence-linkedin-stats-response) | LinkedIn stats for one sequence, broken down per step and per A/B variant — the figures on the sequence's Stats → LinkedIn tab. |
| [Sequence Stats Response](/api-reference/schemas/sequence-stats-response) | Aggregated email and LinkedIn stats for a single sequence |
| [Tasks Overview Response](/api-reference/schemas/tasks-overview-response) | Aggregated task statistics broken down by type, with per-member breakdown |
| [Team Performance Overview Response](/api-reference/schemas/team-performance-overview-response) | Team performance metrics including meetings, contacts, and engagement rates |
## Live data
| Schema | Description |
| - | - |
| [Live Data search](/api-reference/schemas/search) | Summary of a Live Data search. |
| [Live Data search details](/api-reference/schemas/search-details) | A single Live Data search, including the filters it was run with. |
## Attachments
| Schema | Description |
| - | - |
| [Attachment](/api-reference/schemas/attachment) | Uploaded file attachment usable across email templates, sequence steps, and direct emails. |
| [Voice Attachment](/api-reference/schemas/voice-attachment) | Uploaded voice message attachment. |
## Background jobs
| Schema | Description |
| - | - |
| [Background Job](/api-reference/schemas/background-job) | A long-running background operation tracked by the API. |
## Billing
| Schema | Description |
| - | - |
| [Active Contacts Billing](/api-reference/schemas/active-contacts-billing) | Active contacts usage, shaped by `billingScope`. |
| [Active Contacts Daily Usage](/api-reference/schemas/active-contacts-daily-usage) | Active contacts for one day of the billing month. |
| [Active Contacts Usage](/api-reference/schemas/active-contacts-usage) | Active contacts consumed in the current billing month, with a day-by-day breakdown. |
| [Billing Details](/api-reference/schemas/billing-details) | The current subscription and the active contacts consumed so far this billing month. |
| [Billing Subscription](/api-reference/schemas/billing-subscription) | The plan a team is on, and the dates of its current billing term. |
| [Team Active Contacts Usage](/api-reference/schemas/team-active-contacts-usage) | One team's own subscription and active contacts usage. |
| [Team Daily Active Contacts](/api-reference/schemas/team-daily-active-contacts) | One team's share of the contacts first touched on a single day. |
## Rate limits
| Schema | Description |
| - | - |
| [API Limit Packages](/api-reference/schemas/api-limit-packages) | Your organization's pool of API limit packages and the packages you hold. |
| [API Limit Packages Pool](/api-reference/schemas/api-limit-packages-pool) | The packages bought for your organization and shared by its users. |
| [API Limit Packages Seat](/api-reference/schemas/api-limit-packages-seat) | The packages you hold. |
| [Rate Limit](/api-reference/schemas/rate-limit) | One named limit for one window. |
| [Rate Limits](/api-reference/schemas/rate-limits) | Every named rate limit that applies to you, with your current usage. |
## Webhooks
| Schema | Description |
| - | - |
| [Webhook](/api-reference/schemas/webhook) | A webhook subscription. |
| [Webhook events schema](/api-reference/schemas/webhook-events) | Catalog of event types that a webhook subscription can subscribe to. |
| [Webhook Log](/api-reference/schemas/webhook-log) | One delivery-attempt record for a webhook subscription. |
## Common
| Schema | Description |
| - | - |
| [Create Item Result](/api-reference/schemas/create-item-result) | Per-item result for non-atomic bulk create operations. |
| [Not Processed Item Result](/api-reference/schemas/not-processed-item-result) | Per-item error for non-atomic bulk operations. |
| [Validation Error](/api-reference/schemas/validation-error) | A single field-level validation error. |
| [Validation Problem](/api-reference/schemas/validation-problem) | Input-validation error response at 400. |
## Other
| Schema | Description |
| - | - |
| [AI Field Definition](/api-reference/schemas/ai-field-definition) | The prompt an AI custom field runs against each contact. |
| [AI Learning](/api-reference/schemas/ai-learning) | A standing rule that shapes how the AI writes, together with the learnings it contradicts. |
| [AI Learning Conflict](/api-reference/schemas/ai-learning-conflict) | Another AI learning that contradicts the one being read, and which of the two currently applies. |
| [AI Prompt](/api-reference/schemas/ai-prompt) | An AI prompt available for configuring a sequence step. |
| [Available Domain](/api-reference/schemas/available-domain) | A domain name offered for purchase, with its first-term and renewal prices in cents. |
| [Available Pre Warmed Domain](/api-reference/schemas/available-pre-warmed-domain) | A pre-warmed bundle on sale — one domain plus the mailboxes already warming on it, bought as a whole. |
| [Background Noise](/api-reference/schemas/background-noise) | A background noise preset available for AI voice message steps |
| [Business Problem](/api-reference/schemas/business-problem) | Domain error response carrying a stable, namespaced error slug. |
| [Count Result](/api-reference/schemas/count-result) | |
| [Custom Field](/api-reference/schemas/custom-field) | A user-defined field for storing additional data on contacts. |
| [Custom Field Enrichment](/api-reference/schemas/custom-field-enrichment) | The queued enrichment run. |
| [Custom Field Preview](/api-reference/schemas/custom-field-preview) | The value an AI custom field's prompt produced for one contact. |
| [Custom Field Prompt Action](/api-reference/schemas/custom-field-prompt-action) | A Prompt Action that writes into the custom field. |
| [Direct Send](/api-reference/schemas/direct-send) | One direct send - an email or a LinkedIn action sent to a contact outside any sequence - read by its reference. |
| [Email Validation Estimate](/api-reference/schemas/email-validation-estimate-response) | Synchronous probe result returned by `/v3/email-validations/estimate`. |
| [Email Validation Schedule](/api-reference/schemas/email-validation-schedule-response) | Acknowledgement returned by `/v3/email-validations/schedule`. |
| [Estimate Seats](/api-reference/schemas/estimate-seats) | Paid-seat counts and unit price for one seat type in an order estimate. |
| [Filter condition](/api-reference/schemas/filter-condition) | One field''s rules: an `operator` with its `value`, an `and` list of rules that must all match, or an `or` list of alternatives. |
| [Filter fields](/api-reference/schemas/filter-fields-response) | The fields a filter accepts in your workspace, with their operators and values. |
| [Intent Signal Industry](/api-reference/schemas/intent-industry-item) | A single industry entry from the typeahead list, used in intent-signal configuration. |
| [Intent Signal Technology](/api-reference/schemas/intent-technology-item) | A single technology entry from the typeahead list, used in intent-signal configuration. |
| [Problem Details](/api-reference/schemas/problem-details) | Bare RFC 9457 problem-details envelope. |
| [Procurement Domain](/api-reference/schemas/procurement-domain) | A domain your team bought through mailbox procurement, with its subscription, setup and renewal state. |
| [Procurement Pre Warmed Domain](/api-reference/schemas/procurement-pre-warmed-domain) | A pre-warmed domain your team bought through mailbox procurement, with its subscription and setup state. |
| [Prompt Action](/api-reference/schemas/prompt-action) | A reusable AI prompt that runs against contacts and writes its results into contact custom fields. |
| [Prompt Action Output](/api-reference/schemas/prompt-action-output) | One value a Prompt Action produces, together with the contact custom field it is written into. |
| [Reengagement Flow](/api-reference/schemas/reengagement-flow) | |
| [Reengagement Flow State](/api-reference/schemas/reengagement-flow-state) | |
| [Selected sequence structure](/api-reference/schemas/selected-sequence-structure) | The sequence structure an AI SDR sequence's steps were built from |
| [Settings](/api-reference/schemas/settings) | Team and user settings. |
| [Support Request File Response](/api-reference/schemas/support-request-file-response) | A file added to a support request. |
| [Support Request Message Model](/api-reference/schemas/support-request-message) | One message in a support request's conversation. |
| [Support Request Model](/api-reference/schemas/support-request) | A support request with its conversation and files. |
| [Support Request Open Limit Problem](/api-reference/schemas/support-request-open-limit-problem) | You already have the maximum number of open support requests. |
| [Voice](/api-reference/schemas/voice) | A cloned voice available for AI voice message steps |
# Get settings
Source: https://docs.reply.io/api-reference/settings/get-settings
/api-reference/bundled.yaml get /v3/settings
_Requires the `settings:read` scope (or a broader one that includes it)._
Read your settings in one call: profile and time zone, email and inbox preferences, and the team-wide values you work under.
# Update settings
Source: https://docs.reply.io/api-reference/settings/update-settings
/api-reference/bundled.yaml patch /v3/settings
_Requires the `settings:write` scope (or a broader one that includes it)._
Change part of your settings without resending the whole object. Anything you leave out stays exactly as it is.
# Add a file to a support request
Source: https://docs.reply.io/api-reference/support-requests/add-a-file-to-a-support-request
/api-reference/bundled.yaml post /v3/support/requests/{id}/attachments
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `support:write` scope (or a broader one that includes it)._
Adds a file to the request, such as a screenshot, a log or a HAR file. Send it as multipart/form-data in
a single field named `file`, up to 25 MB. A request holds up to 10 of your files. Returns the file's ID,
which also appears in the request's `fileIds`.
# Cancel a support request
Source: https://docs.reply.io/api-reference/support-requests/cancel-a-support-request
/api-reference/bundled.yaml post /v3/support/requests/{id}/cancel
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `support:write` scope (or a broader one that includes it)._
Cancels the request: support stops working on it and its status becomes `done`. Returns the updated
request. The body is optional; a `reason` helps support understand what changed.
# Create a support request
Source: https://docs.reply.io/api-reference/support-requests/create-a-support-request
/api-reference/bundled.yaml post /v3/support/requests
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `support:write` scope (or a broader one that includes it)._
Raises a support request with Reply's support team. Support's answers arrive in the request's
`messages`, and by email at your account's address. You can have up to 3 open requests (any status but
`done`) and raise up to 10 in 24 hours, at most 3 a minute. See [Support](/api-reference/support) for
what to include so support can help quickly.
# Get a support request
Source: https://docs.reply.io/api-reference/support-requests/get-a-support-request
/api-reference/bundled.yaml get /v3/support/requests/{id}
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `support:read` scope (or a broader one that includes it)._
Returns a support request with its conversation and the files you added. `messages` holds what you and
support wrote, oldest first.
# Get a support request file
Source: https://docs.reply.io/api-reference/support-requests/get-a-support-request-file
/api-reference/bundled.yaml get /v3/support/requests/{id}/attachments/{file_id}
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `support:read` scope (or a broader one that includes it)._
Downloads a file you added to the request. The original file name comes in the `Content-Disposition`
header. Only your own files, the ones in the request's `fileIds`, can be downloaded.
# List support requests
Source: https://docs.reply.io/api-reference/support-requests/list-support-requests
/api-reference/bundled.yaml get /v3/support/requests
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `support:read` scope (or a broader one that includes it)._
Lists the support requests you raised through the API, newest first. Requests raised elsewhere, such as
in the Reply app's chat, aren't included. A request you have just raised can take a few seconds to show
up here; `GET /v3/support/requests/{id}` returns it right away. See
[Support](/api-reference/support) for how a request moves between statuses.
# Send an answer to a support request
Source: https://docs.reply.io/api-reference/support-requests/send-an-answer-to-a-support-request
/api-reference/bundled.yaml post /v3/support/requests/{id}/respond
**Coming soon.** This endpoint will be available by mid November 2026.
_Requires the `support:write` scope (or a broader one that includes it)._
Adds your answer to the request's conversation and returns the updated request. Answer when the status
is `needsResponse`, or whenever you have more to add. A request that is `done` can't be answered; raise
a new one instead.
# Add existing users to a team
Source: https://docs.reply.io/api-reference/teams/add-existing-users-to-a-team
/api-reference/bundled.yaml post /v3/teams/{team_id}/users/bulk
**New.** This endpoint shipped recently. If anything about it is unclear or could work better for you, tell us in the [developer Slack](/slack).
_Requires the `teams:write` scope (or a broader one that includes it)._
Give up to 50 users of your organization access to another of its teams (workspaces), each with a role of that team (`roleName`). Users are identified by email and get a separate user ID in the team. The acting user needs the permissions to add existing organization members to a team and to assign roles; the organization owner has both.
The response has one entry per user, in request order, each with the `email` it was sent with: the user's `id` in the team, or `error` and `errorDetails` with `id` `0`. A failed entry does not stop the others. A user already in the team comes back as `alreadyInTeam` with their `id` and role unchanged, so retries are safe.
Keys with `*:*` do not include `teams:write`. A user in several teams must name the team in the `X-TEAM-ID` header of access-token calls.
# Get current user
Source: https://docs.reply.io/api-reference/user-account/get-current-user
/api-reference/bundled.yaml get /v3/whoami
_No scope required — any valid API key can call this endpoint._
See which user an API key acts as — its userId, username, and teamId. The quickest way to confirm a key is valid.
# List team users
Source: https://docs.reply.io/api-reference/user-account/list-team-users
/api-reference/bundled.yaml get /v3/whoami/team-users
_No scope required — any valid API key can call this endpoint._
List the teams (workspaces) of your organization together with their members — one row per user per team, so a user who belongs to several teams appears once for each of them. Handy for turning a userId into a name and email address.
What you see depends on your access level: the organization owner gets every team in the organization; any other user gets only the teams they are a member of, with all members of those teams.
Each row also reports whether the user owns the team and which team and organization roles they hold, so you can tell members apart by role without a separate lookup.
All filters are optional and combine with AND. `teamName`, `userName` and `userEmail` match any part of the value, ignoring case; `teamRole` and `organizationRole` match the whole role name, ignoring case. Without filters the full list is returned.
Available only for accounts that belong to an organization.
# Create a webhook subscription
Source: https://docs.reply.io/api-reference/webhooks/create-a-webhook-subscription
/api-reference/bundled.yaml post /v3/webhooks
_Requires the `webhooks:write` scope (or a broader one that includes it)._
Have Reply call your service as activity happens. Set eventType to one supported event and url to an absolute endpoint.
# Delete a webhook subscription
Source: https://docs.reply.io/api-reference/webhooks/delete-a-webhook-subscription
/api-reference/bundled.yaml delete /v3/webhooks/{id}
_Requires the `webhooks:write` scope (or a broader one that includes it)._
Delete a subscription for good. Deliveries stop at once and its failure log goes too, so read the logs first if needed.
# Disable a webhook subscription
Source: https://docs.reply.io/api-reference/webhooks/disable-a-webhook-subscription
/api-reference/bundled.yaml post /v3/webhooks/{id}/disable
_Requires the `webhooks:operate` scope (or a broader one that includes it)._
Stop a subscription delivering without deleting it. It keeps its event, url, and settings until you enable it again.
# Enable a webhook subscription
Source: https://docs.reply.io/api-reference/webhooks/enable-a-webhook-subscription
/api-reference/bundled.yaml post /v3/webhooks/{id}/enable
_Requires the `webhooks:operate` scope (or a broader one that includes it)._
Start a paused subscription delivering again, including one Reply disabled after repeated delivery failures.
# Get a webhook subscription
Source: https://docs.reply.io/api-reference/webhooks/get-a-webhook-subscription
/api-reference/bundled.yaml get /v3/webhooks/{id}
_Requires the `webhooks:read` scope (or a broader one that includes it)._
Get one subscription by id: the event it listens to, its url, scope, enabled flag, creation date, and payload flags.
# Get webhook delivery logs
Source: https://docs.reply.io/api-reference/webhooks/get-webhook-delivery-logs
/api-reference/bundled.yaml get /v3/webhooks/{id}/logs
_Requires the `webhooks:read` scope (or a broader one that includes it)._
See where deliveries went wrong. Only failed attempts are logged, each with the event id, HTTP status, and date.
# List supported event types
Source: https://docs.reply.io/api-reference/webhooks/list-supported-event-types
/api-reference/bundled.yaml get /v3/webhooks/events
_Requires the `webhooks:read` scope (or a broader one that includes it)._
Get the exact event names a subscription can listen to. Any value here works as eventType when you create or update one.
# List webhook subscriptions
Source: https://docs.reply.io/api-reference/webhooks/list-webhook-subscriptions
/api-reference/bundled.yaml get /v3/webhooks
_Requires the `webhooks:read` scope (or a broader one that includes it)._
See the webhook subscriptions you've set up, each with its event, url, scope, enabled flag, and payload flags.
# Send a test payload
Source: https://docs.reply.io/api-reference/webhooks/send-a-test-payload
/api-reference/bundled.yaml post /v3/webhooks/{id}/test
_Requires the `webhooks:operate` scope (or a broader one that includes it)._
Check your receiving endpoint is wired up before real activity arrives. Reply posts a sample payload and reports back.
# Update a webhook subscription
Source: https://docs.reply.io/api-reference/webhooks/update-a-webhook-subscription
/api-reference/bundled.yaml put /v3/webhooks/{id}
_Requires the `webhooks:write` scope (or a broader one that includes it)._
Repoint a subscription at a different url, event, or scope. It replaces the whole thing, so repeat the flags you keep.
# Using the CLI from agents & scripts
Source: https://docs.reply.io/cli/agents
The reply CLI's machine contract — JSON output, exit codes, the two error shapes, retries, impersonation headers, and composition patterns.
The `reply` CLI is built to be driven by coding agents, shell scripts, and CI. It handles the parts
that are tedious to reimplement — browser login, token refresh, the team header, retries — and
exposes the whole [v3 API](/api-reference/introduction) through
[`reply api`](/cli/overview#raw-api-access). That command is the agent surface today; there are no
dedicated resource commands yet.
## The `--json` contract
Every command accepts `--json` (compact) and `--pretty` (indented). **Data goes to stdout, status
and errors go to stderr** — pipes stay clean:
```bash theme={null}
reply api /v3/sequences --json | jq '.data.items[].id'
reply auth whoami --json | jq -r '.username'
reply team list --json | jq -r '.teams[].team_id'
```
`reply api` always emits JSON, with or without a flag — `{"code": , "data": }`.
`--pretty` only changes the indentation.
## Exit codes
| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | API failure (HTTP `>= 400`) or runtime failure (network, corrupt credential store) |
| `2` | Usage error — unknown flag, missing argument, no credential to use |
## The two error shapes
**`reply api` never hides an HTTP response.** Any status, including `4xx` and `5xx`, is printed on
stdout as `{code, data}`, where `data` is the v3 `problem+json` body verbatim. The exit code is `1`
for `>= 400`. Branch on `.code`:
```bash theme={null}
out=$(reply api /v3/contacts/999) || true
echo "$out" | jq -e '.code == 404' >/dev/null && echo "not found"
```
**Every other command** reports failures as a single machine-readable line on **stderr** when
`--json` or `--pretty` is set:
```json theme={null}
{"error":{"status":404,"code":"contact.notFound","title":"Not Found","detail":"Contact with ID 999 not found","hint":"Resource not found."}}
```
Branch on `code`, surface `hint` to the user. Every field except `title` is optional.
## Retries and rate limits
Handled inside the CLI, on both paths:
* `429`, `500`, `502`, `503`, and `504` are retried up to 3 times.
* `Retry-After` is honored when present, capped at 30 seconds; otherwise the backoff is exponential
from 500 ms.
* Network failures are retried on the same schedule, then surface as a runtime error (exit `1`).
Don't wrap your own retry loop around write calls — a retried `POST` can double-create. Verify with
a follow-up `GET` instead. [Rate limits](/api-reference/rate-limits) documents the API-side windows.
## Teams and impersonation
Requests carry the team header from `--team-id` → `REPLY_TEAM_ID` → the profile's pinned team. If a
call needs a team and the credential spans several, the API returns `TEAM_REQUIRED` and the CLI adds
a one-line fix-it hint on stderr. Pin one non-interactively:
```bash theme={null}
reply team use 1045 # persists on the active profile
reply --team-id 1045 api /v3/sequences # or scope a single call
```
With an [organization API key](/api-reference/authentication#special-api-keys), name the acting user
with `--user-id ` or `--user-email ` (which also needs a team id). Pass exactly one.
These are **flag-only** — never read from the environment, never written to disk — so an agent must
supply them per invocation:
```bash theme={null}
reply --api-key "$ORG_KEY" --user-id 12345 api /v3/whoami
reply --api-key "$ORG_KEY" --team-id 1045 --user-email rep@acme.com api /v3/sequences
```
Rejection codes for organization keys are listed under
[Rejection responses](/api-reference/authentication#rejection-responses).
## Safety is the caller's job
> [!WARNING]
>
> The CLI has **no `--dry-run` and no confirmation gates**. `reply api` sends exactly the request you
> give it — a `DELETE` deletes, and a `POST /v3/sequences/{id}/start` begins real outreach. The only
> interactive prompt in the whole CLI is `reply profile delete`, which `-y` skips.
An agent driving `reply api` owns the guardrails the [platform safety rules](/agents/safety)
describe: confirm high-stakes actions with the user first, echo the exact request you're about to
send, and prefer a read-back over a retry. Two habits that help:
* Resolve ids with a `GET` before mutating; never invent numeric ids.
* Use `--verbose` while developing a call — it prints the full request and response to stderr with
credentials redacted, leaving stdout pipeable.
## Non-interactive environments
CI and agent sandboxes have no browser, so `reply auth login` won't work. Supply a key instead:
```bash theme={null}
export REPLY_API_KEY="$REPLY_KEY" # or pass --api-key per call
reply auth whoami --json # verify before doing work
```
Add `-q/--quiet` to silence progress messages on stderr; warnings and errors are still printed.
`REPLY_CONFIG_DIR` relocates the credential store when the default home directory isn't writable.
## Composition patterns
```bash theme={null}
# every active sequence's id and name, as TSV
reply api '/v3/sequences?status=active' --json \
| jq -r '.data.items[] | [.id, .name] | @tsv'
# pause every active sequence whose reply rate was under 1% last week
reply api /v3/sequences/stats --body '{"filters":{"dateRangePreset":"lastWeek"}}' --json \
| jq -r '.data[] | select(.status == "active" and .emailOverview.repliedPercentage < 1) | .sequenceId' \
| xargs -I{} reply api /v3/sequences/{}/pause --method POST
# fail a CI job when the credential no longer works
reply auth whoami --json >/dev/null || exit 1
```
The CLI composes with cron for scheduled jobs, `jq` for filtering, and the
[Reply Skills](/skills/overview) for procedure — the skill supplies the plan, the CLI executes it.
Install them with `reply skills install`.
## Drop-in prompt
A ready-to-paste system prompt encoding this contract lives at
[Drop-in system prompts → CLI variant](/agents/prompts#cli-variant).
# Reply CLI
Source: https://docs.reply.io/cli/overview
The Reply.io command line — sign in once, then run any v3 API call as yourself from your terminal, your scripts, or CI.
[`reply`](https://www.npmjs.com/package/reply-cli) is the official command-line interface for
Reply.io. Sign in once and every request runs as you. Today it covers **authentication and
identity**, [`reply api`](#raw-api-access) gives you authenticated access to the full
[v3 API](/api-reference/introduction) — no HTTP client, no header wrangling — and
[`reply skills`](#skills) installs Reply's agent skill packs into your AI assistants. Higher-level
commands for sequences, contacts, and the inbox are on the way.
| | |
| - | - |
| **Package** | [`reply-cli`](https://www.npmjs.com/package/reply-cli) (npm) |
| **Command** | `reply` |
| **Runtime** | Node.js 20 or newer |
| **Auth** | OAuth browser login, or an API key |
| **Output** | Human-readable by default; `--json` / `--pretty` for machines |
| **Source** | [github.com/reply-team/reply-cli](https://github.com/reply-team/reply-cli) |
| **Status** | Pre-1.0 — see [Versioning](#versioning) |
## Install
```bash theme={null}
npm install -g reply-cli # installs the `reply` command (Node 20+)
reply --version
```
Or run it without installing:
```bash theme={null}
npx -y reply-cli auth login
```
## Authenticate
Log in through your browser — no key to copy, no key to rotate:
```bash theme={null}
reply auth login
```
Prefer an API key? Read it from stdin so it never lands in your shell history:
```bash theme={null}
reply auth login --with-token
```
Keys come from Reply → **Settings → API Keys**; scopes and key types are covered in
[Authentication](/api-reference/authentication).
Inspect and manage the active credential:
```bash theme={null}
reply auth status # who you're signed in as, and how — no secrets shown
reply auth whoami # validate the stored credential against the API
reply auth logout # remove the stored credential
```
### Credential precedence
Resolved in strict order, first hit wins:
1. `--api-key ` flag
2. `REPLY_API_KEY` environment variable
3. the stored credential from `reply auth login`
The flag and the environment variable are used for that one invocation and are never written to
disk.
> [!NOTE]
>
> There is no `.env` file lookup — export `REPLY_API_KEY` yourself, or store a credential with
> `reply auth login`.
### Where credentials live
Credentials are stored as JSON in `~/.config/reply` (`%APPDATA%\reply` on Windows), written `0600`
inside a `0700` directory — the same plaintext-file model as `gh`, `aws`, and `az`. OAuth tokens
refresh automatically; if a refresh fails the record is cleared and you're asked to log in again.
Tokens and keys are redacted in every command's output, `--verbose` included.
## Profiles — more than one Reply.io user
A profile is a signed-in account. Profiles let you keep several Reply.io users authenticated at
once and switch between them, each with its own stored credential. Most people never need one: the
default profile is used until you create another.
Name them however you like — account emails work well:
```bash theme={null}
reply profile add alice@reply.io
reply profile use alice@reply.io # make it the active profile
reply auth login # signs in alice@reply.io
reply profile list # '*' marks the active profile
reply --profile bob@reply.io auth whoami # override for a single command
```
The active profile resolves as `--profile` → `REPLY_PROFILE` → the profile set with
`profile use` → the built-in default.
Manage them after creation:
```bash theme={null}
reply profile show # the active profile — team, auth method, no secrets
reply profile show alice@reply.io # a specific one
reply profile rename alice@reply.io ally # also moves the stored credential
reply profile delete ally # removes it and its stored credential
```
## Teams
A profile can pin a team (workspace). The pinned team is sent as the `X-TEAM-ID` header, with
precedence `--team-id` → `REPLY_TEAM_ID` → the profile's team. The `team` command reads and writes
the **active profile's** team:
```bash theme={null}
reply team list # teams you can act in ('*' marks the profile's team)
reply team current # the pinned team, plus the effective team from whoami
reply team use 1045 # verify 1045 is one of your teams, then pin it
reply team clear # remove the pin
```
If a call needs a team and you belong to more than one, the API answers with a `TEAM_REQUIRED`
error listing your teams — run `reply team use ` to pin one, or pass `--team-id ` for a
single command.
## Raw API access
`reply api` is a raw, authenticated passthrough to any v3 endpoint — the escape hatch for
everything the CLI has no dedicated command for yet.
Use the path exactly as it appears in the [API reference](/api-reference/introduction), starting
with `/v3`; the query string goes in the path. A `--body` switches the method to `POST` (override
with `--method`), and it accepts inline JSON, `@file`, or `-` for stdin.
```bash theme={null}
reply api /v3/whoami # your identity + team
reply api /v3/sequences # list sequences
reply api /v3/contacts --pretty # list contacts, indented
reply api /v3/sequences/12345 # one sequence by id
reply api /v3/contacts --body @contact.json # create a contact (POST)
echo '' | reply api /v3/contacts --body - # body from stdin
reply api /v3/whoami --verbose # full request/response on stderr
```
It prints `{ "code": , "data": }` and exits non-zero on HTTP `>= 400`. See
[Using the CLI from agents & scripts](/cli/agents) for the full machine contract.
## Skills
Reply's outbound expertise ships as three markdown skill packs in
[reply-skills](https://github.com/reply-team/reply-skills). `reply skills` detects the AI assistants
on your machine and installs the packs into each one, resolving dependencies itself:
```bash theme={null}
reply skills install
```
```
✓ detected Claude Code, Codex
✓ Claude Code · ai-sdr-core, reply-adapter, agentic-runtime installed
✓ Codex · ai-sdr-core, reply-adapter, agentic-runtime installed
Start a new session in each assistant so the skills load.
```
| Pack | Alias | What it gives your agent |
| - | - | - |
| `ai-sdr-core` | `core` | Vendor-neutral SDR operations, playbooks, and guardrails |
| `reply-adapter` | `adapter` | Executing those operations against Reply.io |
| `agentic-runtime` | `runtime` | Durable multi-session work: plans, checkpoints, reports |
Naming no pack installs all three. Dependencies come along automatically, so `adapter` pulls `core`:
```bash theme={null}
reply skills install core
reply skills install adapter runtime
reply skills install --agent codex # only this assistant
reply skills install --project # into this repository, not your home directory
```
Then manage them:
```bash theme={null}
reply skills list # what's installed where, and what has an update available
reply skills update # bring installed packs to the latest version
reply skills remove runtime # remove one pack
reply skills remove # remove all of them
```
On Claude Code and Codex the packs are installed through the assistant's own plugin mechanism, so
they keep updating through it. Other `SKILL.md` hosts receive the skills as copied files. Add
`--json` for a machine-readable report and `--dry-run` to see the plan without changing anything.
| Assistant | `--agent` id | How it receives the packs | Paths verified |
| - | - | - | - |
| Claude Code | `claude-code` | its own plugin CLI | Yes |
| Codex | `codex` | its own plugin CLI (`--project` copies files instead) | Yes |
| Cursor | `cursor` | copied files | Not yet |
| Gemini CLI | `gemini-cli` | copied files | Not yet |
| GitHub Copilot | `github-copilot` | copied files | Not yet |
| Windsurf | `windsurf` | copied files | Not yet |
> [!NOTE]
>
> **"Not yet" means that assistant's skills directory comes from its own documentation** and has not
> been confirmed by a verification run — the install works, but Reply cannot promise the assistant
> reads from where the files were put. Those hosts are marked `(paths not yet verified)` in the
> report and carry `"verified": false` in `--json`.
Removing a pack another installed pack depends on is refused — remove both, or run
`reply skills remove` with no pack to remove everything.
> [!NOTE]
>
> Installing skills is not the same as connecting Reply: `reply-adapter` needs a Reply.io credential
> (`reply auth login`) to do anything. See [Reply Skills](/skills/overview).
## Command reference
Run `reply --help` for the exact flags of any command — the installed help always matches
your version.
### `reply auth`
| Command | Description |
| - | - |
| `reply auth login` | Log in via OAuth in the browser |
| `reply auth login --with-token` | Store an API key read from stdin |
| `reply auth status` | Active credential source, method, user, and OAuth expiry — no secrets |
| `reply auth whoami` | Validate the active credential against the API and print the principal |
| `reply auth logout` | Remove the stored credential |
### `reply profile`
| Command | Description |
| - | - |
| `reply profile add ` | Create a profile (`--team-id` optionally pins a team) |
| `reply profile use ` | Make it the active profile, used until changed |
| `reply profile list` | List profiles; `*` marks the active one |
| `reply profile current` | Print the active profile name |
| `reply profile show [name]` | Show a profile's team and authorization — no secrets |
| `reply profile set --team-id ` | Pin a team on a profile |
| `reply profile unset team-id` | Clear the pinned team |
| `reply profile rename ` | Rename a profile and move its stored credential |
| `reply profile delete ` | Delete a profile and its stored credential (`-y` to skip the prompt) |
### `reply team`
| Command | Description |
| - | - |
| `reply team list` | Teams you can act in |
| `reply team current` | The active profile's pinned team and the effective team |
| `reply team use ` | Pin a team (verified against your teams) |
| `reply team clear` | Remove the pin |
### `reply api`
| Command | Description |
| - | - |
| `reply api ` | Raw authenticated request to a v3 endpoint; prints `{code, data}` |
| `reply api --body ` | Send a body (switches the method to `POST`) |
| `reply api --method ` | Override the HTTP method |
### `reply skills`
| Command | Description |
| - | - |
| `reply skills install [packs...]` | Install packs into every detected assistant (default: all three) |
| `reply skills list [packs...]` | Show which packs are installed in which assistant |
| `reply skills update [packs...]` | Update installed packs to the latest published version |
| `reply skills remove [packs...]` | Remove packs from your assistants (default: all of them) |
Pack names accept aliases: `core`, `adapter`, `runtime`. These flags apply to all four subcommands:
| Flag | Effect |
| - | - |
| `-a, --agent ` | Target these assistants instead of auto-detecting |
| `--project` | Install into the current repository instead of your user directory |
| `--dry-run` | Show what would happen and change nothing |
### Global flags
| Flag | Effect |
| - | - |
| `-k, --api-key ` | Use this key for one invocation; overrides the env var and stored credential |
| `-p, --profile ` | Run as this profile for one invocation |
| `--team-id ` | Team/workspace to act in, sent as `X-TEAM-ID` |
| `--user-id ` | Act as this user id — [organization API keys](/api-reference/authentication#special-api-keys) only |
| `--user-email ` | Act as this user email — organization keys only; requires a team id |
| `--json` | Compact JSON on stdout |
| `--pretty` | Indented JSON on stdout |
| `--verbose` | Full request/response on stderr, credentials redacted |
| `-q, --quiet` | Suppress progress messages on stderr; warnings and errors still shown |
| `-v, --version` | Print the CLI version |
### Environment variables
| Variable | Description |
| - | - |
| `REPLY_API_KEY` | API key used as the credential for the current invocation |
| `REPLY_PROFILE` | Profile to use (same as `--profile`) |
| `REPLY_TEAM_ID` | Team/workspace id sent as `X-TEAM-ID` (same as `--team-id`) |
| `REPLY_CONFIG_DIR` | Config directory (default `~/.config/reply`; `%APPDATA%\reply` on Windows) |
## Why a CLI when there's REST and MCP?
* **Authentication is the hard part, and it's solved here.** Browser login, token refresh, multiple
accounts, and the team header are handled for you — `reply api` is a `curl` that is already
authenticated as the right user in the right workspace.
* **Coding agents are exceptionally good at shell commands.** They get composability — pipes, `jq`,
cron — without writing an HTTP client. See [Using the CLI from agents](/cli/agents).
* **Scriptable one-offs.** Terminal and CI access to the API for work that doesn't warrant a real
integration.
## What isn't in the CLI yet
There are no dedicated commands for sequences, contacts, the inbox, or reporting yet — reach them
through `reply api` today, or use the interface that fits:
| Need | Where today |
| - | - |
| Any v3 endpoint, authenticated | `reply api /v3/…` |
| A tool surface for LLM agents | [Reply MCP](/mcp/overview) |
| Procedure and guardrails for an agent | [Reply Skills](/skills/overview) — `reply skills install` |
| Your own integration | [REST API](/api-reference/introduction) |
| Event-driven automation | [Webhooks](/webhook-events) |
## Versioning
`reply-cli` follows [semantic versioning](https://semver.org), with versions derived from
Conventional Commits.
> [!NOTE]
>
> **Pre-1.0.** While the version is `0.x` the CLI is still stabilizing, so — per semver's 0.x rule —
> a minor release (`0.x.0`) may contain breaking changes. Pin an exact version if you need stability
> before `1.0.0`.
From `1.0.0` onward, a major bump is required to remove or rename a command, flag, or argument;
change the meaning of an exit code; change the `--json` / `--pretty` output shape; change the config
format or a `REPLY_*` environment variable; or raise the minimum Node.js version. New commands, new
optional flags, and new fields in `--json` output are additive and ship in minor releases.
## Links
* Package: [npmjs.com/package/reply-cli](https://www.npmjs.com/package/reply-cli)
* Source and issues: [github.com/reply-team/reply-cli](https://github.com/reply-team/reply-cli)
* Next: [Using the CLI from agents & scripts](/cli/agents)
# Decide what to scale or fix
Source: https://docs.reply.io/guides/analyze-performance
Turn raw reporting data into decisions — what to scale, pause, or rewrite.
**Outcome:** a performance readout (delivered, opens, replies, interested, meetings) with a
diagnosis and one or two recommended actions.
## Best interface
> [!NOTE]
>
> **CLI for reporting agents** — [`reply api`](/cli/overview#raw-api-access) with `--json` makes the
> reporting endpoints pipeable and cron-able. **MCP for Q\&A-style analysis** — "compare Q3 sequences"
> resolves to `reply_compare_sequence_performance` in one call.
## Steps
**1. Pull the account-level overview**
Both endpoints take a `filters` object; `dateRangePreset` accepts `lastWeek`, `lastMonth`,
`lastYear`, or `allTime`.
```bash theme={null}
reply api /v3/reporting/emails/overview \
--body '{"filters":{"dateRangePreset":"lastWeek"}}' --json
reply api /v3/sequences/stats \
--body '{"filters":{"dateRangePreset":"lastWeek"}}' --json
```
**2. Drill into per-sequence stats**
```bash theme={null}
reply api /v3/sequences/12345/stats \
--body '{"filters":{"dateRangePreset":"lastMonth"}}' --json
```
MCP: `reply_get_sequence_stats` (one sequence, custom date window) or
`reply_compare_sequence_performance` (up to 25 side by side — align by SequenceId, treat
missing rows as no data).
**3. Diagnose**
Benchmark deliverability (bounces), copy (opens vs replies), and targeting (replies vs
interested). Flag stalled or degraded sequences. The
[`performance-analysis` skill](/skills/catalog#performance-analysis) packages this diagnosis.
**4. Act — with confirmation**
Pausing sequences or editing copy are production changes: recommend, confirm, then execute
([Manage sequences](/guides/improve-sequences) has the loop).
## Availability notes
* Reports, per-sequence stats, and comparisons: **available today**.
* Stats endpoints can throttle earlier than CRUD endpoints — budget calls accordingly
([Rate limits](/api-reference/rate-limits)).
* Meetings are booked via Reply's in-app scheduler; the API **reports** them (meetings ledger) but
can't book them.
## Related
* [Improve sequences every cycle](/guides/improve-sequences) — acting on the diagnosis
* [Skill: `performance-analysis`](/skills/catalog#performance-analysis)
# Automate outbound end-to-end
Source: https://docs.reply.io/guides/automate-outbound
Event-driven and scheduled automation — webhooks for real-time reactions, CLI + cron for recurring hygiene.
**Outcome:** workflows that run without anyone asking — inbound leads answered in minutes, lists
that stay clean, dormant contacts revived on a schedule.
## Best interface
> [!NOTE]
>
> **API + webhooks** — event-driven automation is REST-only: subscribe once, react in real time.
> **CLI + cron** — scheduled jobs like a weekly hygiene sweep are a natural fit for
> [`--json` composition](/cli/agents#composition-patterns).
## Pattern 1: Event-driven (inbound lead follow-up)
Speed-to-lead is most of the conversion rate. This loop is event-driven end to end — no polling:
**1. Receive the signal**
A [webhook event](/webhook-events) (or your product's own signup/demo-request event) tells the
agent a lead arrived. Payload shapes: [Webhook event payloads](/webhook-event-payloads).
**2. Upsert and qualify**
Create/update the contact with source context in custom fields
([Create contacts](/guides/import-contacts)); score against your ICP.
\[!NOTE] Auto-enrichment of the lead is **coming soon** (Enrichment API).
**3. Route to the right sequence**
Hot leads → short, direct sequence; colder → nurture. Add the contact and start
([Launch outreach](/guides/launch-outreach)). For an immediate one-off first response outside
a sequence, use the outreach-action endpoints ([API Reference](/api-reference/introduction)).
**4. Manage the conversation**
Watch reply categories and meeting intent ([Process replies](/guides/convert-replies-to-meetings));
meetings and activity land in reporting automatically.
## Pattern 2: Scheduled (list hygiene + re-engagement)
Deliverability is a compounding asset. A weekly cron sweep keeps the base clean, then re-engages
what survives:
**1. Segment stale and risky contacts**
```bash theme={null}
reply api '/v3/contacts/filter?top=1000' \
--body '{"conditions":[{"field":"lastTouchDate","operator":"moreThanDaysAgo","value":90}]}' --json
```
Filter by last activity, bounce history, or missing fields. `GET /v3/contacts/filter/fields`
lists the fields, operators and values your workspace accepts; page with `top` and `skip` until
`hasMore` is `false`.
**2. Validate and suppress**
Schedule email validation across the segment; add bounced domains, opt-outs, and competitor
domains to blacklist rules (Suppression & Blacklist API — see
[API Reference](/api-reference/introduction)).
**3. Prune and re-segment**
Bulk-update or remove dead records; move survivors into clean lists.
**4. Re-engage the dormant segment**
Run a light-touch sequence (2–3 low-pressure touches) against contacts that finished without
converting. Load reengagement cards into a Jason knowledge base for a fresh angle
([Build an AI SDR](/guides/build-an-ai-sdr)).
\[!NOTE] Re-enrichment before re-engagement ("did they change jobs?") is **coming soon**.
**5. Measure the effect**
Compare bounce and reply rates before/after with `POST /v3/reporting/emails/overview` (its
`compareTo` field returns the trend against a previous period); track the revival rate to decide
if the sweep becomes quarterly.
## Availability notes
* Webhooks, contact CRUD, validation, suppression, sequences, and reporting: **available today**.
* Enrichment-dependent steps (lead auto-enrichment, dormant-refresh): **coming soon**.
## Related
* [Webhook events catalog](/webhook-events) · [Payloads](/webhook-event-payloads)
* [Using the CLI from agents & scripts](/cli/agents)
* [Convert replies into meetings](/guides/convert-replies-to-meetings) · [Build a supervised AI SDR](/guides/build-an-ai-sdr)
# Build a supervised AI SDR
Source: https://docs.reply.io/guides/build-an-ai-sdr
Give Jason a goal, knowledge, and guardrails — then supervise through approval gates instead of operating by hand.
**Outcome:** a supervised, self-improving outbound system — Jason (Reply's AI SDR) writes and sends
outreach and handles replies, while your agent supervises through approval queues and performance
data. The highest-altitude pattern: an agent configuring an agent.
## Best interface
> [!NOTE]
>
> **MCP** — the Jason toolset is richest there: 31 of the 70 tools drive knowledge bases, offers,
> playbooks, reply handlers, reengagement cards, and the approval queue. The REST API covers the
> knowledge/offer/playbook layer.
## Steps
**1. Define the sales goal — available**
Translate the objective into an offer, a target market, and success metrics. Draft offer
content from a website with MCP `reply_generate_offer_from_website` (review, then
`reply_create_offer`).
**2. Build the knowledge base — available**
`reply_create_knowledge_base` → add URL sources (`reply_add_knowledge_base_source`), reply
handlers (how Jason answers pricing/security/… questions), and reengagement cards (win-back
plays). See [MCP tools → Jason AI SDR](/mcp/tools#jason-ai-sdr).
**3. Define offers and playbooks — available**
The offer says *what's being sold and to whom*; the playbook says *how* (tone, structure,
channels). `reply_create_offer`, `reply_create_playbook`, then attach both to the sequence.
**4. Point it at prospects — partly coming soon**
Enroll contacts you already have ([Launch outreach](/guides/launch-outreach)).
\[!WARNING] Intent-signal targeting and Live Data sourcing are **coming soon** — see [Find prospects](/guides/find-ideal-prospects).
**5. Set the reply mode — available, gate it**
`reply_set_sequence_reply_mode` → **Review** (Jason drafts, you approve) is the safe default.
**Autonomous** (Jason sends without approval) is a [high-stakes switch](/agents/safety) —
verify offer/playbook/knowledge base first and confirm explicitly. Recipe:
[Switch Jason to Autonomous](/mcp/recipes#switch-jason-to-autonomous).
**6. Supervise the queue — available**
`reply_list_pending_approvals` → approve (sends immediately), regenerate with feedback, or
reject (removes the contact from the sequence — irreversible). Recipe:
[Supervise Jason in Review mode](/mcp/recipes#supervise-jason-in-review-mode).
**7. Watch conversations and optimize — available**
Replies flow into the unified inbox with AI categorization; escalate high-intent threads to a
human. Read the meetings ledger and per-sequence stats; refine the offer, playbook, and
targeting based on what converts ([Analyze performance](/guides/analyze-performance)).
## Availability notes
* Knowledge bases, reply handlers, reengagement cards, offers, playbooks, reply-mode control, and
the approval queue: **available today via MCP** (and the AI SDR REST module).
* **Coming soon:** intent-signal prospect targeting; full autopilot enrollment loops. Everything
labeled available above is callable now.
## Related
* [MCP recipes: Supervise Jason / Switch to Autonomous](/mcp/recipes#supervise-jason-in-review-mode)
* [Convert replies into meetings](/guides/convert-replies-to-meetings) — the human-approved counterpart
* [Agent safety rules](/agents/safety) — why Autonomous is gated
# Convert replies into meetings
Source: https://docs.reply.io/guides/convert-replies-to-meetings
Triage the inbox, surface interested prospects, and send approved replies — event-driven or conversational.
**Outcome:** every reply triaged, interested prospects surfaced, responses sent with explicit
approval — from both email and LinkedIn, in one inbox.
## Best interface
> [!NOTE]
>
> **The [`inbox-triage` skill](/skills/catalog#inbox-triage)** for approved, gated sending.
> **Webhooks for real-time** — subscribe to [`email_replied` and `reply_categorized`
> events](/webhook-events) instead of polling. **MCP** for conversational triage in a client.
## Steps
**1. Receive the signal (real-time) or poll (simple)**
Real-time: subscribe to [webhook events](/webhook-events) — `email_replied`,
`reply_categorized` — pushed to your endpoint (see
[payloads](/webhook-event-payloads)). Polling:
`reply api /v3/inbox/threads/filter --body '{"source":"unread"}'` or MCP
`reply_get_inbox_emails`.
**2. Triage by category and intent**
Group threads by category and meeting intent. LinkedIn and email replies land in the same
unified inbox with the same categories.
```bash theme={null}
reply api /v3/inbox/threads/categories --json # resolve category ids first
reply api /v3/inbox/threads/filter \
--body '{"categoryIds":[7],"onlyWithMeetingIntent":true}' --json
```
**3. Read the full thread context**
```bash theme={null}
reply api /v3/inbox/threads/58217 --json
reply api /v3/inbox/threads/58217/messages --json
```
**4. Draft, show, confirm, send**
Sending reaches a real prospect — a [high-stakes action](/agents/safety). Nothing here prompts
for confirmation, so show the exact text, get approval, then send. The body's `channel` must
match the thread's, or the call is rejected with `inboxThread.channelMismatch`.
```bash theme={null}
reply api /v3/inbox/threads/58217/messages \
--body '{"channel":"email","message":"Thanks — does Tuesday at 10am work?","applySignature":true}' --json
```
MCP: `reply_send_inbox_reply` (channel must match the thread; body only in v1 — no Cc/Bcc,
attachments, or scheduling). See the [MCP recipe](/mcp/recipes#reply-to-an-inbox-thread).
**5. Categorize and route**
```bash theme={null}
reply api /v3/inbox/threads/58217/category --method PUT --body '{"categoryId":42}' --json
```
Route meeting-intent threads to scheduling; mark contacts as replied to stop further automated
outreach (MCP: `reply_mark_contacts_as_replied`).
## Availability notes
* Inbox triage, replying, categorization, and webhooks: **available today**.
* **Fully automated reply policies (auto-answer) are not in Skill v1** — every send is
human-approved. For AI-drafted replies with an approval queue, see
[Build an AI SDR](/guides/build-an-ai-sdr).
## Related
* [Build a supervised AI SDR](/guides/build-an-ai-sdr) — Jason drafts the replies, you approve
* [Automate outbound end-to-end](/guides/automate-outbound) — the event-driven pattern in full
* [Webhook events catalog](/webhook-events)
# Find your ideal prospects
Source: https://docs.reply.io/guides/find-ideal-prospects
From an ICP definition to a saved, deduplicated prospect list — what works today and what's coming.
**Outcome:** a contact list of prospects matching your ideal customer profile, ready for outreach.
> [!WARNING]
>
> The end-to-end path — searching Reply's 1B+ B2B database from an ICP — depends on the **Live
> Data / prospect-search API, which is not generally available yet**. The same applies to
> waterfall enrichment. This guide describes what works today and labels the rest honestly.
## Best interface today
> [!NOTE]
>
> **Bring your own list.** Until prospect search ships, source prospects externally and enter the
> platform at the import step — [Create and import contacts](/guides/import-contacts) covers the
> fully-available path (bulk import with dedupe via the API or Skills).
## Steps
**1. Define the ICP — available (your agent's logic)**
Turn the goal into concrete filters: job titles, seniority, department, industry, company
size, location. An agent can derive this from your best customers' domains and reporting data.
The [`campaign-planning`](/skills/catalog#campaign-planning) skill covers turning a goal into
constraints, and [`user-memory`](/skills/catalog#user-memory) keeps the resulting ICP for later
sessions.
**2. Search the B2B database — coming soon**
Live Data search over the 1B+ contact database with result preview before committing credits.
Ships as an API module and a `reply` CLI command.
**3. Store results as contacts — available**
Import selected prospects as contact records organized into a named list — today via CSV:
[Create and import contacts](/guides/import-contacts).
**4. Enrich what's missing — coming soon**
Waterfall enrichment (emails, phones, firmographics) depends on the Enrichment API. Until
then, source enrichment externally before import.
**5. Validate before sending — available**
Schedule email validation on the list to protect deliverability — part of
[Automate workflows](/guides/automate-outbound).
## Availability notes
* Prospect search & enrichment: **coming soon** — they'll appear as API modules and CLI commands when
the endpoints ship.
* Everything downstream of a list you already have is fully available today.
## Related
* [Import and clean contacts](/guides/import-contacts) — the available entry point
* [Launch multichannel outreach](/guides/launch-outreach) — the next step once the list exists
* [Skill: `audience-building`](/skills/catalog#audience-building) — shaping a list you already have
# Import and clean contacts
Source: https://docs.reply.io/guides/import-contacts
CSV in, deduplicated contacts out — mapped, verified, and organized into a list ready for outreach.
**Outcome:** clean contact records in your workspace, deduplicated, validated, and organized into a
list ready for sequencing.
## Best interface
> [!NOTE]
>
> **API for bulk import** — one `POST /v3/contacts/import` call handles dedupe, list assignment, and
> per-item outcomes. Drive it from your own code, or from the terminal with
> [`reply api`](/cli/overview#raw-api-access). **MCP** for conversational, one-at-a-time creation.
## Steps
**1. Build the import payload**
Import takes JSON, not CSV — convert your spreadsheet first. The body is
`{"items": [...], "options": {...}}`, where each item uses the contact fields and `options`
controls dedupe and list assignment. **Maximum 1000 items per request** — batch anything larger.
```json theme={null}
{
"items": [
{"email": "john@acme.com", "firstName": "John", "lastName": "Doe", "company": "Acme"}
],
"options": {"skipExisting": true, "listIds": [42]}
}
```
**2. Import, then read the per-item outcome**
```bash theme={null}
reply api /v3/contacts/import --body @import.json --json
```
The response reports added / updated / skipped / failed counts with a per-item outcome — report
exact numbers rather than "done". Nothing is written until you send this call, so validate the
payload locally first: there is no server-side dry-run.
**3. Or create contacts programmatically (API / MCP)**
For one-at-a-time or system-to-system sync, use the Contacts endpoints in the
[API Reference](/api-reference/introduction), or `reply_create_contact` /
`reply_update_contact` via [MCP](/mcp/tools#contacts) (needs a name plus email or LinkedIn URL).
**4. Validate emails before sending**
Schedule email validation on the list — never send to a dead address. Available today via the
API; part of the [list-hygiene loop](/guides/automate-outbound).
**5. Verify list membership**
```bash theme={null}
reply api /v3/contact-lists/42 --json
reply api '/v3/contacts/filter?top=100' --body '{"listId":42}' --json | jq '.data.items | length'
```
## Availability notes
* CSV import, contact CRUD, lists, and email validation: **available today**.
* Waterfall **enrichment** of imported records (fill missing emails/phones/firmographics):
**coming soon** — see [Find prospects](/guides/find-ideal-prospects#availability-notes).
## Related
* [Launch multichannel outreach](/guides/launch-outreach) — enroll the list into a sequence
* [Automate outbound end-to-end](/guides/automate-outbound) — keep the list clean on a schedule
* [Skill: `audience-building`](/skills/catalog#audience-building)
# Improve sequences every cycle
Source: https://docs.reply.io/guides/improve-sequences
Operate running sequences — A/B variants, per-step stats, pausing losers, promoting winners.
**Outcome:** sequences that measurably improve every cycle — data-picked copy on every step, losers
paused, winners promoted to templates.
## Best interface
> [!NOTE]
>
> **CLI for ops loops** — [`reply api`](/cli/overview#raw-api-access) against the stats and
> lifecycle endpoints composes with `jq` and cron for continuous
> optimization. **MCP interactively** — inspect steps and variants, compare sequences, pause/start
> conversationally.
## Steps
**1. Create A/B variants on the steps that matter**
Openers and first follow-ups move the numbers hardest. Add message variants via the Sequences
API (see [API Reference](/api-reference/introduction)); inspect existing ones via MCP:
`reply_get_sequence_steps` → `reply_get_sequence_step_variants`.
**2. Let traffic split**
Run the sequence; the platform distributes contacts across enabled variants automatically.
**3. Read per-variant and per-sequence performance**
```bash theme={null}
reply api /v3/sequences/12345/stats \
--body '{"filters":{"dateRangePreset":"lastMonth"}}' --json
```
MCP: `reply_get_sequence_stats` for one, `reply_compare_sequence_performance` for up to 25
side by side.
**4. Pause the losers — no need to stop the sequence**
```bash theme={null}
reply api /v3/sequences/stats --body '{"filters":{"dateRangePreset":"lastMonth"}}' --json \
| jq -r '.data[] | select(.status == "active" and .emailOverview.repliedPercentage < 1) | .sequenceId' \
| xargs -I{} reply api /v3/sequences/{}/pause --method POST
```
The list endpoint accepts only `lastWeek` or `lastMonth`. Disable underperforming variants
mid-flight via the API; pause whole sequences as above or via MCP.
**5. Promote the winners**
Save winning messages as email templates so every future sequence starts from proven copy —
Templates via the [API](/api-reference/introduction).
**6. Verify the lift**
Confirm the aggregate effect over time with `POST /v3/reporting/emails/overview`, or the
[`performance-analysis` skill](/skills/catalog#performance-analysis).
## Availability notes
* Everything here is **available today**. Per-contact status changes inside a sequence
(pause one person, mark finished) are richest via MCP: `reply_change_status_in_sequence`.
## Related
* [Decide what to scale or fix](/guides/analyze-performance) — the diagnosis layer
* [Launch multichannel outreach](/guides/launch-outreach) — starting new sequences
# Launch multichannel outreach
Source: https://docs.reply.io/guides/launch-outreach
From a contact list to a running multichannel sequence — accounts checked, contacts enrolled, start confirmed.
**Outcome:** a running sequence with assigned mailboxes, a schedule, and enrolled contacts — started
only after explicit confirmation.
## Best interface
> [!NOTE]
>
> **The [`campaign-launch` skill](/skills/catalog#campaign-launch)** runs the whole checklist and
> gates the start on your explicit confirmation. **In an MCP client**, follow the
> [Launch a sequence safely recipe](/mcp/recipes#launch-a-sequence-safely) — same checklist as MCP
> tool calls.
## Steps
**1. Check sending accounts**
Email steps need a connected mailbox; LinkedIn steps need a linked LinkedIn account.
API: `GET /v3/email-accounts`, `GET /v3/linkedin-accounts` (`reply api /v3/email-accounts`).
MCP: `reply_list_email_accounts`, `reply_list_linkedin_accounts`.
**2. Create or select the sequence**
API: `POST /v3/sequences` to create, `GET /v3/sequences` to pick an existing one.
MCP: `reply_search_sequences`. For LinkedIn-first cadences, lead with LinkedIn steps and fall
back to email for prospects who don't accept.
**3. Assign mailboxes and a schedule**
MCP: `reply_assign_email_account_to_sequence`, `reply_assign_schedule_to_sequence` — a
sequence without a mailbox fails to start with `NoEmailAccounts`.
**4. Enroll the contacts**
Add contacts by id, in bulk. Resolve the ids first — never guess them.
```bash theme={null}
reply api /v3/sequences/12345/contact-links/bulk \
--body '{"contactIds":[101,102],"removeFromExisting":false}' --json
```
Per-contact skips (already in sequence, blacklisted) are reported, not failures — read them
and report exact counts.
**5. Confirm, then start**
Starting begins real outreach — a [high-stakes action](/agents/safety) on every surface. Nothing
below asks for confirmation, so ask the user yourself before you run it.
```bash theme={null}
reply api /v3/sequences/12345/start --method POST --json
```
MCP: confirm with the user, then `reply_start_sequence`.
**6. Verify it's running**
API: `reply api /v3/sequences/12345 --json` · MCP: `reply_get_sequence_stats` or
`reply_search_sequences` to confirm the status is Active.
## Availability notes
* Everything in this guide is **available today**, including LinkedIn steps (with a linked
LinkedIn account).
* Complex step editing (A/B variants on live sequences, LinkedIn step authoring) is handed off to
the Reply app in Skill v1.
## Related
* [Improve sequences every cycle](/guides/improve-sequences) — optimize what's now running
* [Convert replies into meetings](/guides/convert-replies-to-meetings) — handle the responses
* [MCP recipe: Launch a sequence safely](/mcp/recipes#launch-a-sequence-safely)
# Building agents
Source: https://docs.reply.io/mcp/agent-guide
Design principles, high-stakes gating, and a drop-in system prompt for agents that use Reply MCP.
Reply MCP executes a successful call **immediately** — there is no undo. These principles keep an
agent safe and effective. They pair with the [tool contract](/mcp/tool-contract) (how calls behave)
and the [workflow recipes](/mcp/recipes) (concrete call graphs). For the platform-wide,
surface-independent versions of these rules, see [Agent safety rules](/agents/safety) and
[Drop-in system prompts](/agents/prompts).
## Design principles
### Resolve before you mutate
Almost every mutating tool takes exact numeric IDs (sequence, contact, task, thread, user,
email-account, LinkedIn-account, schedule, offer, playbook, knowledge-base). **Never invent an ID,
and never ask the user for one** — users don't know internal IDs. Search → confirm the match →
act → verify:
```text theme={null}
User: "Add John from Acme to the Q3 outbound sequence."
1. reply_search_contacts(email or LinkedIn URL) — this tool needs an email/LinkedIn,
not a name; if you only have a name, ask the user for an email first.
2. reply_search_sequences(name: "Q3 outbound")
3. If exactly one contact and one sequence match, confirm and call
reply_add_contact_to_sequence(sequenceId, [contactId]).
4. Read NotProcessed in the result; verify with reply_get_contact_activity(contactId).
```
### Gate high-stakes actions
Confirm with the user before anything that sends to a prospect, starts outreach, enrolls contacts,
changes ownership, blacklists, bulk-approves, or switches Jason to Autonomous. Two traps worth
naming:
* **`reply_reject_message` doesn't just discard a draft** — it removes the contact from the
sequence entirely. To merely revise a draft, use `reply_regenerate_message`.
* **`reply_send_inbox_reply` supports only `threadId` + `channel` + `message` in v1** — no Cc/Bcc,
attachments, or scheduling; 32,000-char max; the channel must match the thread's.
### Separate discovery, configuration, and execution
Discover objects and IDs (`search_*` / `list_*` / `get_*`), configure the sequence (mailboxes,
schedules, offers, knowledge bases, playbooks, reply mode), then execute (start, approve, send,
complete). `reply_start_sequence` fails with `NoEmailAccounts` or `NoContacts` if you skip
configuration.
### MCP is the interactive surface; REST is the exhaustive one
These 71 tools cover most day-to-day operations. Drop to the [REST API](/api-reference/introduction)
(`api.reply.io/v3`) for bulk imports and updates, background jobs, deep report exports, and anything
absent from `tools/list`.
## High-stakes tools
Each of these reaches a prospect or changes ownership/state the instant it succeeds. Require
explicit confirmation in almost any agent UX:
| Tool | Why it's high-stakes |
| - | - |
| `reply_start_sequence` | Begins outreach processing |
| `reply_add_contact_to_sequence` | Enrolls people into outreach |
| `reply_send_inbox_reply` | Sends a real message to a contact |
| `reply_approve_message` / `reply_bulk_approve_messages` | Send Jason's drafts (bulk is atomic, ≤100) |
| `reply_reject_message` | **Irreversible** — discards the draft AND removes the contact from the sequence. Use `reply_regenerate_message` if the user merely dislikes the draft |
| `reply_blacklist_contact` | Suppresses an email (or, with `blockEntireDomain`, a whole company domain — including future contacts) from all outreach |
| `reply_change_contact_owner` | Changes visibility and responsibility; trust only `AffectedContactIds` when reporting what changed |
| `reply_set_sequence_reply_mode` → `Autonomous` | Jason sends without per-message review |
Usually worth confirming too (production-affecting, but not prospect-visible): `reply_pause_sequence`,
`reply_change_status_in_sequence`, the `reply_assign_*` / `reply_attach_*` configuration tools,
`reply_complete_task`, and any create/update/delete on knowledge bases, reply handlers, reengagement
cards, offers, or playbooks. The server's `destructiveHint` annotation marks all 39 mutations — use
it as the machine-readable gate.
## Drop-in system prompt
Add this to an agent's system prompt when it has Reply MCP tools:
```text theme={null}
You have access to Reply.io MCP tools. For every request:
1. Classify it: read-only, configuration, outreach-changing, or prospect-visible send.
The server annotates every tool (readOnlyHint / destructiveHint) — honor them.
2. For any mutation, resolve exact numeric IDs first with search/list/filter tools.
Never guess an ID and never ask the user for one.
3. For high-stakes actions (send, approve, reject, start, enroll, blacklist, change owner,
go Autonomous), summarize the target and side effect, then ask the user to confirm.
Remember: reject_message removes the contact from the sequence — it is not "discard draft".
4. Parse results from result.content[0].text: {"Success":true,"Data":...} or
{"Success":false,"ErrorCode":...,"ErrorMessage":...}. Branch on ErrorCode.
Read per-item results (NotProcessed / AffectedContactIds) and report exact counts.
5. Do not pass unknown arguments (schemas are additionalProperties:false) and never send
empty strings/arrays for required fields.
6. Paginate with top/skip until HasMore is false.
7. On failure, follow the tool's own failure-mode guidance. Do not blindly retry sends,
approvals, starts, or enrollments — a timeout may already have succeeded; verify first.
8. If no tool fits, try reply_get_app_map and reply_search_knowledge_base before saying
you can't; then reply_report_unsupported_request if it is truly missing.
```
Next: [workflow recipes](/mcp/recipes) turn these principles into concrete call graphs.
# Connect
Source: https://docs.reply.io/mcp/connect
Connect Reply MCP to Claude, Cursor, or any MCP client in two steps: create a scoped API key, then point your client at mcp.reply.io.
Connect Reply MCP to your AI client in two steps: get your API key, then point your client at
`https://mcp.reply.io/`.
## 1) Get your API key
Reply MCP authenticates with your Reply.io **personal API key**. Create or copy one under
**Settings → API Key** in the [Reply dashboard](https://run.reply.io).
A personal API key is the preferred credential because it's **scoped**: you grant it only the
permissions your agent needs, and it can call only the tools those permissions cover. A scope is
a permission such as `contacts:read` or `sequences:operate`, grouped by area (contacts,
sequences, inbox, tasks, channels, AI SDR), so you can give an agent exactly the reach it needs
and nothing more. Set the scopes on the key in **Settings → API Key**; see
[Scopes](/api-reference/authentication#scopes) for the full list.
The MCP connection URL is `https://mcp.reply.io/`. You can also open it in the app under
**Execution → Integrations → Reply MCP Server → Configure**, which is where you set up and
configure the MCP connection.
> [!WARNING]
>
> Treat your API key like a password. Don't share it in public repositories, screenshots, or
> chat messages. If it's exposed, generate a new API key in Reply.
## 2) Add it to your client
### Header auth (recommended)
Most modern MCP clients support remote Streamable HTTP servers with header auth. Point the client
at `https://mcp.reply.io/` and pass your key in the `Authorization` header as a bearer token.
```json theme={null}
{
"mcpServers": {
"reply": {
"type": "http",
"url": "https://mcp.reply.io/",
"headers": { "Authorization": "Bearer YOUR_REPLY_API_KEY" }
}
}
}
```
**Claude Code**, one line:
```bash theme={null}
claude mcp add --transport http reply https://mcp.reply.io/ \
--header "Authorization: Bearer YOUR_REPLY_API_KEY"
```
### OAuth (clients without header auth)
Some clients don't let you set an API key or custom headers — typically the **UI / desktop apps**
of Claude, ChatGPT, and Codex, where you add a connector by URL only. For those, use OAuth: add
Reply MCP as a remote/custom connector with the URL `https://mcp.reply.io/` and authorize when
prompted — no key to copy or store.
OAuth grants access to the **full tool catalog** — it's equivalent to an API key with **all
scopes**, and there's no per-scope control over an OAuth connection. So whenever your client does
support header auth, prefer a scoped personal API key (above) to limit what the agent can do.
> [!NOTE]
>
> Some OAuth clients don't support Client ID Metadata Documents (CIMD) and fall back to Dynamic
> Client Registration, which is allow-listed on our side. If your client reports an allow-list or
> registration error when connecting, let us know in the [community Slack](/slack) and we'll
> review it.
### Fallback: `mcp-remote` (clients without native remote MCP)
If your client only supports local (stdio) MCP servers, bridge to the remote server with the
[`mcp-remote`](https://www.npmjs.com/package/mcp-remote) proxy and pass your key in the
`Authorization` header:
```json theme={null}
{
"mcpServers": {
"reply": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://mcp.reply.io/",
"--header",
"Authorization: Bearer YOUR_REPLY_API_KEY"
]
}
}
}
```
> [!NOTE]
>
> Passing credentials in the URL (for example `?api_key=...`) is not supported. Always
> authenticate with the `Authorization` bearer header.
## Handshake
Once connected, MCP clients drive the standard flow automatically. If you're building a client by
hand:
1. Open an HTTP connection to `https://mcp.reply.io/`.
2. Send a JSON-RPC `initialize` with your protocol version and client info.
3. Send the `notifications/initialized` notification if your client library requires it.
4. Call `tools/list` to discover tools, their JSON schemas, and their annotations.
5. Call `tools/call` with a tool name and an argument object.
```json initialize theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": { "name": "your-client", "version": "1.0.0" }
}
}
```
No `Mcp-Session-Id` is required — `initialize` and `tools/list` work without a session.
## Authentication details
An unauthenticated call returns `401 Unauthorized` with an OAuth challenge header:
```http theme={null}
WWW-Authenticate: Bearer resource_metadata="https://mcp.reply.io/.well-known/oauth-protected-resource/"
```
The published protected-resource metadata (`GET /.well-known/oauth-protected-resource/`):
```json theme={null}
{
"resource": "https://mcp.reply.io",
"authorization_servers": ["https://oauth.sandbox.replyapp.io"],
"bearer_methods_supported": ["header"],
"scopes_supported": ["reply-web-api", "mcp:tools"]
}
```
For most agents a scoped personal API key is the recommended path — it gives the finest-grained
control over what the agent can do (see [Scopes](/api-reference/authentication#scopes)). The
OAuth metadata exists for clients (e.g. Claude custom connectors) that prefer a discovery-based
flow; OAuth grants the **full tool catalog** (all scopes), so prefer a scoped personal API key
when you want to limit an agent's reach.
### Unsupported keys
Reply MCP is a single-user connection, so **act-on-behalf API keys are not supported** —
including team-level **Team keys** and **Organization API keys**. These are designed to make
requests on behalf of other users, which a single-user connection doesn't provide. Use a
personal API key or OAuth instead.
## Rate limits
The server allows 120 requests per minute, 3,000 per hour and 150,000 per week. Every successful
response carries the budget of the longest window:
```http theme={null}
X-Rate-Limit-Limit: 7d
X-Rate-Limit-Remaining: 149870
X-Rate-Limit-Reset: 2026-10-11T14:37:12.0000000Z
```
On `429`, wait the number of seconds in the `Retry-After` header before retrying.
## Related
* [Reply MCP overview](/mcp/overview) — what the server exposes
* [Tool reference](/mcp/tools) — all 71 tools
* [Connecting Reply MCP to your AI model (Help Center)](https://support.reply.io/en/articles/12955018-connecting-reply-mcp-to-your-ai-model)
# Reply MCP overview
Source: https://docs.reply.io/mcp/overview
The official, live Reply.io MCP server — 71 tools for sequences, contacts, inbox, tasks, and the Jason AI SDR autopilot.
Reply MCP is an official, live, remote [Model Context Protocol](https://modelcontextprotocol.io)
server that exposes Reply.io's sales-engagement, inbox, AI SDR (Jason), task, account, and help
workflows as **71 tools** for any MCP-compatible client — Claude, Cursor, Make, n8n, and custom agents.
> [!NOTE]
>
> Everything in these pages was read off the running server via an authenticated
> `initialize` + `tools/list` handshake and safe validation probes. Tool names, signatures,
> enum values, annotations, response envelopes, and error codes come from the live server —
> not hand-maintained prose. If any other documentation disagrees, trust the server (see
> [Regenerate this reference](/mcp/tools#regenerate-this-reference)).
## At a glance
| | |
| - | - |
| **Endpoint** | `https://mcp.reply.io/` |
| **Transport** | Streamable HTTP (responses are SSE `text/event-stream` frames carrying JSON-RPC) |
| **Wire format** | JSON-RPC 2.0 over HTTP |
| **MCP protocol** | `2025-06-18` |
| **Auth** | `Authorization: Bearer ` |
| **Rate limit** | 120/minute, 3,000/hour, 150,000/week (`X-Rate-Limit-*` headers on every successful response) |
| **Sessions** | None required — `initialize` and `tools/list` work without an `Mcp-Session-Id` |
| **Tools** | 71 — 32 annotated `readOnlyHint`, 39 annotated `destructiveHint` |
| **Capabilities** | `tools`, `logging` (no prompts or resources advertised) |
> [card] [Connect your client](/mcp/connect)
>
> Add Reply MCP to Claude, Cursor, or any MCP client in a couple of minutes.
> [card] [Tool reference](/mcp/tools)
>
> The full catalog of all 71 tools, grouped by domain.
> [card] [Tool contract & errors](/mcp/tool-contract)
>
> The rules every tool enforces: schemas, envelopes, error codes, retries.
> [card] [Building agents](/mcp/agent-guide)
>
> Design principles, high-stakes gating, and a drop-in system prompt.
> [card] [Guides: what to build](/guides/launch-outreach)
>
> Task-based guides — launch outreach, process replies, build an AI SDR.
> [card] [Choose your interface](/agents/choose-your-interface)
>
> Not sure MCP is the right surface? Compare MCP, Skills, CLI, and API.
## What's exposed
The 71 tools cover the day-to-day Reply.io surface an agent needs:
| Domain | Tools | What it does |
| - | :-: | - |
| **Sequences** | 17 | Discover, inspect, start/pause, enroll contacts, and configure mailboxes, schedules, and AI SDR settings |
| **Contacts** | 8 | Look up, filter, create, update, reassign, blacklist, and read activity |
| **Inbox & conversations** | 3 | List inbox threads, send replies, categorize |
| **Jason AI SDR** | 31 | Approvals & autopilot, knowledge bases, reply handlers, reengagement cards, offers, and playbooks |
| **Tasks** | 3 | List, create, and complete tasks |
| **Workspace resolvers** | 5 | Resolve mailboxes, LinkedIn accounts, schedules, lists, and teammates to their IDs |
| **Help & meta** | 4 | Search the Help Center, read articles, map the app, report unsupported requests |
See the [tool reference](/mcp/tools) for every tool name, its safety annotation, and a one-line purpose.
## MCP vs the REST API
MCP and the [REST API](/api-reference/introduction) are two surfaces over **one product** — same
account, same credit system.
* **MCP** — the interactive surface. 71 curated, annotated tools for agent actions and
natural-language workflows. Best for day-to-day operations.
* **REST** (`https://api.reply.io/v3`) — the exhaustive surface. Use it for bulk imports and
updates, background jobs, deep report exports, webhooks, and template/schedule/mailbox
management not exposed as tools.
> [card] [REST API reference](/api-reference/introduction)
>
> Browse the full v3 REST API — the exhaustive surface for bulk and background operations.
## FAQ
> [accordion] Is the MCP server real, and how current is this page?
>
> Yes — it's an official, live server at `mcp.reply.io`. These pages were generated from an
> authenticated `initialize` + `tools/list` handshake against the running server. If the
> server ever returns a different tool set, the server is newer — trust it, and
> [regenerate the reference](/mcp/tools#regenerate-this-reference) in seconds.
> [accordion] How does authentication work?
>
> Pass your Reply.io API key as an `Authorization: Bearer` header. A call with
> no credentials returns `401` with a `WWW-Authenticate` challenge; OAuth protected-resource
> metadata is also published for clients that prefer a discovery-based flow. See
> [Connect](/mcp/connect).
> [accordion] How do I know which tools are safe to call?
>
> Every tool is annotated in `tools/list`: 32 are `readOnlyHint: true` and 39 are
> `destructiveHint: true`. Agents can — and should — gate on these annotations before adding
> their own confirmation UX for the high-stakes subset. See the
> [tool contract](/mcp/tool-contract).
> [accordion] What do responses look like?
>
> Responses are SSE frames; read the last `data:` frame. A successful `tools/call` returns the
> payload as a JSON string in `result.content[0].text`. Tool failures are **not** HTTP errors —
> they arrive as HTTP 200 with `result.isError = true`. See
> [response envelopes](/mcp/tool-contract#response-envelopes).
> [accordion] When should an agent use MCP instead of the REST API?
>
> Use MCP for interactive, natural-language workflows and everyday operations. Drop to the
> REST API for bulk imports/updates, background jobs, report exports, and anything absent from
> `tools/list`.
> [accordion] Is the Jason AI SDR autopilot really callable here?
>
> Yes. 31 of the 71 tools drive Jason — the approval queue, knowledge bases, reply handlers,
> reengagement cards, offers, playbooks, and the Review/Autonomous reply mode.
# Workflow recipes
Source: https://docs.reply.io/mcp/recipes
Concrete Reply MCP call graphs — resolve IDs, configure, confirm high-stakes steps, verify.
Concrete call graphs an agent can follow. Each one resolves IDs first, configures where needed,
confirms before high-stakes steps, and verifies after. See [Building agents](/mcp/agent-guide) for
the principles behind them.
## Launch a sequence safely
**1. Resolve the sequence**
`reply_search_sequences` by name → resolve the exact `sequenceId` (ask the user if ambiguous).
**2. Inspect its channels**
`reply_get_sequence_steps` → see which channels the sequence uses.
**3. Attach a mailbox (if email steps)**
`reply_list_email_accounts`, then `reply_assign_email_account_to_sequence` if none is attached.
**4. Attach LinkedIn (if LinkedIn steps)**
`reply_list_linkedin_accounts`, then `reply_assign_linkedin_account_to_sequence`; warn if the
account is unhealthy.
**5. Set a schedule**
`reply_list_schedules`, then `reply_assign_schedule_to_sequence` if none is set.
**6. Optional AI SDR config**
`reply_attach_offer_to_sequence` / `reply_attach_playbook_to_sequence` /
`reply_attach_knowledge_base_to_sequence`, then `reply_set_sequence_reply_mode`.
**7. Confirm, then start**
Confirm with the user ("Start sequence X? This begins outreach to its contacts."), then
`reply_start_sequence` — expect `NoContacts` / `NoEmailAccounts` / `Archived` if configuration
was skipped.
**8. Verify**
`reply_get_sequence_stats` or `reply_search_sequences` to confirm it is Active.
## Add a contact to a sequence
**1. Find the contact**
`reply_search_contacts` by email or LinkedIn URL (the tool does not accept names — ask the user
for an email if that's all you have).
**2. Create if missing**
If missing and the user confirms details, `reply_create_contact` (needs a name plus at least one
of email/LinkedIn URL).
**3. Resolve the sequence**
`reply_search_sequences` for the target sequence.
**4. Confirm, then enroll**
Confirm, then `reply_add_contact_to_sequence` (up to 100 IDs; per-contact skips arrive in
`NotProcessed`, e.g. `ContactAlreadyInSequence`, `ContactInBlackList`).
**5. Verify**
`reply_get_contact_activity` to verify enrollment.
## Supervise Jason in Review mode
**1. Ensure Review mode**
`reply_set_sequence_reply_mode` → `Review` (if not already).
**2. Read the queue**
`reply_list_pending_approvals` — filter by sequence, owner, or channel.
**3. Act on each draft (addressed by sequenceId + contactId)**
Inspect the contact and context, compare against the attached playbook/knowledge base, then:
* `reply_approve_message` (optionally overriding body/subject) — **sends immediately**;
* `reply_regenerate_message` with specific feedback to revise the draft;
* `reply_reject_message` **only** if the contact should leave the sequence entirely — rejection
is irreversible and removes them from the sequence.
**4. Bulk approve carefully**
`reply_bulk_approve_messages` only after every draft in the batch was reviewed — the batch is
atomic: one stale reference rejects the whole batch and nothing is sent.
## Switch Jason to Autonomous
**1. Verify configuration**
Verify the sequence has an offer, playbook, and knowledge base attached and reviewed.
**2. Confirm explicitly**
Autonomous mode sends replies **without per-message approval**. Get explicit confirmation.
**3. Switch**
`reply_set_sequence_reply_mode` → `Autonomous`.
**4. Keep watching**
Keep watching `reply_get_inbox_emails` and `reply_get_sequence_stats`.
## Reply to an inbox thread
**1. Find the thread**
`reply_get_inbox_emails` (pagination only in v1 — no filters; previews only, not full bodies) →
resolve the exact `threadId` and note its channel.
**2. Draft and confirm**
Draft the reply and show it to the user for approval.
**3. Send**
`reply_send_inbox_reply` with the matching channel (`Email` or `LinkedIn`) — v1 supports message
body only (max 32,000 chars); no Cc/Bcc, attachments, or scheduling. Expect `ChannelMismatch`,
`ContactOptedOut`, or `ThreadSendFailed` as the named failure modes.
**4. Optionally categorize**
`reply_change_inbox_category` to reflect the new state.
## Handle an unsupported request
**1. Confirm no tool fits**
Confirm no tool in `tools/list` can do it.
**2. Check the app map**
`reply_get_app_map` — the action may be a UI-only setting; return the exact in-app link.
**3. Check the Help Center**
`reply_search_knowledge_base` + `reply_get_knowledge_base_article` — answer a how-to and cite
the source.
**4. Report if truly missing**
Only if genuinely missing, `reply_report_unsupported_request` with a stable kebab-case
`requestKey` and a `category` from its enum — then tell the user plainly you cannot do it. Offer
the [REST API](/api-reference/introduction) if it covers the gap.
## Related guides
These recipes power the task-based guides, which add the cross-surface view (CLI, Skills, API):
* [Launch multichannel outreach](/guides/launch-outreach) · [Convert replies into meetings](/guides/convert-replies-to-meetings) ·
[Build a supervised AI SDR](/guides/build-an-ai-sdr) · [Improve sequences every cycle](/guides/improve-sequences)
# Tool contract & errors
Source: https://docs.reply.io/mcp/tool-contract
The rules every Reply MCP tool enforces — schemas, pagination, response envelopes, error codes, and retries.
These rules apply to **every one of the 71 tools**, verified against the served JSON schemas and
live validation probes. An agent that follows them will rarely hit an avoidable error.
## Contract rules the schemas enforce
* **Unknown arguments are invalid.** Every `inputSchema` sets `additionalProperties: false`. Don't
pass extra keys "just in case" — the call fails validation.
* **Required means non-empty.** Required string and array fields reject `null`, `""`, and `[]`
alike. In the server's own words: *"null, empty strings, and empty arrays are not accepted for
required fields."*
* **Every tool is annotated.** `readOnlyHint: true` (32 tools) or `destructiveHint: true` (39
tools) arrives in `tools/list`. Gate on these before adding your own confirmation UX.
* **Pagination is uniform.** List/search tools take `top` (default 20, max 100) and `skip`;
responses return `Data.Items` plus `HasMore`. Iterate with `skip += top` until `HasMore` is
`false`.
* **Patch semantics on updates.** Every `update_*` tool changes only the fields you pass;
omitted/null fields keep their current value. A passed list field replaces the whole list.
* **IDs come from resolvers.** Mutating tools require exact numeric IDs from prior
`search_*` / `list_*` / `filter_*` output. The descriptions repeat one rule verbatim: *"Never
invent, estimate, default, or ask the user."*
* **Approvals are addressed by pair.** Approve/reject/regenerate identify a Jason draft by
`sequenceId` + `contactId` — there is no separate draft/message ID.
* **Batches are bounded and explicit.** Bulk tools cap at 100 items. `reply_bulk_approve_messages`
is atomic (any stale reference rejects the whole batch; nothing is sent). Contact batches return
per-item results (`Affected` / `AffectedContactIds` / `NotProcessed`) — the authoritative record
of what actually happened; report exact counts ("reassigned 48 of 50").
## Enum quick reference
Every closed value set the server declares, in one place. All are case-insensitive unless noted.
| Field | Values | Used by |
| - | - | - |
| `channel` | `Email`, `LinkedIn` | `send_inbox_reply`, `list_pending_approvals` filter |
| Per-sequence contact status | `Active`, `Paused`, `Finished`, `Inactive`, `OutOfOffice` | `change_status_in_sequence` |
| Sequence search status | `New`, `Active`, `Paused` | `search_sequences` |
| Reply mode | `Review`, `Autonomous` (+ `sendExistingDrafts` boolean) | `set_sequence_reply_mode` |
| `toneOfVoice` | `Confident`, `Persuasive`, `Witty`, `Straightforward`, `Empathetic` | reply handlers, reengagement cards |
| `responseLength` | `SuperShort`, `Short`, `Medium`, `Long` | reply handlers, reengagement cards |
| `taskType` | `ToDo`, `Call`, `Meeting`, `LinkedIn`, `ManualEmail`, `Sms`, `WhatsApp` | `create_task`, `list_my_tasks` |
| `linkedInTaskType` | `Message`, `Connect`, `InMail`, `ViewProfile` | `create_task` (required when `taskType=LinkedIn`) |
| `callResolution` | `Positive`, `ToCall`, `Negative` | `complete_task` (recommended for Call tasks) |
| Playbook visibility | `Team` (default), `Organization` | `create_playbook`, `duplicate_playbook` |
| `category` | `integrations`, `reporting`, `sequences`, `contacts`, `email`, `linkedIn`, `ai`, `other` | `report_unsupported_request` |
| `sortMode` | `NewestFirst` (default), `OldestFirst` | `list_pending_approvals` |
## Response envelopes
**Transport.** Responses are SSE frames (`text/event-stream`) whose `data:` lines carry ordinary
JSON-RPC payloads. Read the last `data:` frame for the result.
**Success.** A successful `tools/call` returns `result.isError = false`, and the actual payload is
a JSON string inside `result.content[0].text`:
```json theme={null}
{ "Success": true, "Data": { "Items": [ ... ], "HasMore": false } }
```
**Error.** Tool failures are **not** HTTP errors — they come back as **HTTP 200**, JSON-RPC
success, with `result.isError = true` and the error as a JSON string in `result.content[0].text`:
```json theme={null}
{ "Success": false, "ErrorCode": "InvalidArguments", "ErrorMessage": "..." }
```
Parse the inner JSON; branch on `Success`, then on `ErrorCode`. Real captured examples:
```json theme={null}
{"Success":false,"ErrorCode":"InvalidArguments","ErrorMessage":"Tool 'reply_get_sequence_steps' arguments failed validation: SequenceId: 'Sequence Id' must be greater than '0'."}
{"Success":false,"ErrorCode":"InvalidArguments","ErrorMessage":"Tool 'reply_send_inbox_reply' is missing required argument(s): message. Supply a real value for each; null, empty strings, and empty arrays are not accepted for required fields."}
{"Success":false,"ErrorCode":"InvalidArguments","ErrorMessage":"Tool 'reply_search_contacts' arguments failed validation: : At least one of Email or LinkedIn must be provided. If the user gave only a name or company, ask them for an email address or LinkedIn URL instead."}
```
## Error model
Handle failures at three layers:
1. **Transport / auth.** `401` (missing/invalid key), `403` (valid key, missing scope or plan
feature), `429` (rate limit — back off using `Retry-After`), `5xx` (transient).
2. **Tool-level `ErrorCode`s** (inside the envelope): `InvalidArguments`, `NotFound`, `Forbidden`,
`Conflict`, `InvalidInput`, `InvalidParameter`, `UpstreamFailure`, `ServiceUnavailable`, plus
domain-specific codes named per tool (`NoEmailAccounts`, `NoContacts`, `ContactLimitExceeded`,
`ChannelMismatch`, `ContactOptedOut`, `ThreadSendFailed`, `InvalidStatusTransition`,
`ArticleNotFound`, `PERMISSION_DENIED`, …). Each tool's description states which codes it can
return and what to do about each.
3. **Per-item partial results.** Batch tools report per-contact skips in `NotProcessed` (e.g.
`ContactAlreadyInSequence`, `ContactInBlackList`, `NotFound`) while the call as a whole
succeeds. Read them; never claim an item succeeded unless it appears in the affected list.
## Safe-retry matrix
> [!WARNING]
>
> A timed-out **send** may already have succeeded server-side. Verify with a read before retrying
> anything that reaches a prospect.
| When | Tools | Policy |
| - | - | - |
| Auto-retry once on transient `ServiceUnavailable` / `UpstreamFailure` / timeout | all read tools — `search_*`, `list_*`, `get_*`, `filter_*`, `*_stats`, `compare_*`, `get_app_map`, `search_knowledge_base` | Safe to retry |
| Retry only **after a verifying read** | `create_*`, `update_*`, `add_contact_to_sequence`, `change_status_in_sequence`, `assign_*`, `attach_*`, `complete_task`, `mark_contacts_as_replied` | Read first, then retry |
| **Never** auto-retry — confirm with the user first | `send_inbox_reply`, `approve_message`, `bulk_approve_messages`, `reject_message`, `start_sequence`, `blacklist_contact`, `change_contact_owner`, switching to Autonomous | Verify server state, then decide |
Next: [Building agents](/mcp/agent-guide) for how to sequence these calls, and the
[tool reference](/mcp/tools) for the full catalog.
# Tool reference
Source: https://docs.reply.io/mcp/tools
The full catalog of all 71 Reply MCP tools, grouped by domain, with safety annotations.
All 71 tools, grouped by domain. This is a **map**, not a schema dump — the authoritative,
per-argument JSON schema for every tool is served live by `tools/list`, and an agent should read it
from there. Each tool's served description also states its exact ID rules, enum values, batch
limits, and per-code failure guidance. See the [tool contract](/mcp/tool-contract) for the rules
shared across all of them.
**Legend:** 📖 read-only (`readOnlyHint`) · ✏️ mutation (`destructiveHint`) · ⭐ high-stakes
(prospect-visible or irreversible — always confirm; see [Building agents](/mcp/agent-guide#high-stakes-tools)).
## Sequences
### Discover & inspect
| Tool | | Purpose |
| - | :-: | - |
| `reply_search_sequences` | 📖 | Find sequences by name / status / archive flag; returns per-sequence summary fields |
| `reply_filter_sequence_contacts` | 📖 | Filter one sequence's contacts by what happened in it (opened, replied, status, current step) and by contact fields |
| `reply_get_sequence_steps` | 📖 | List a sequence's ordered steps (type, delay, position, variant count) |
| `reply_get_sequence_step_variants` | 📖 | Read a message step's A/B content variants (subject, body) |
| `reply_get_sequence_stats` | 📖 | Email + LinkedIn performance metrics for one sequence |
| `reply_compare_sequence_performance` | 📖 | Side-by-side metrics for up to 25 sequences |
### Control & configuration
| Tool | | Purpose |
| - | :-: | - |
| `reply_start_sequence` | ✏️⭐ | Start or resume a sequence so it begins sending |
| `reply_pause_sequence` | ✏️ | Pause a sequence; halt in-flight scheduled steps |
| `reply_add_contact_to_sequence` | ✏️⭐ | Enroll up to 100 existing contacts into a sequence |
| `reply_change_status_in_sequence` | ✏️ | Set one contact's per-sequence status |
| `reply_assign_email_account_to_sequence` | ✏️ | Link a mailbox to a sequence |
| `reply_assign_linkedin_account_to_sequence` | ✏️ | Link a LinkedIn account to a sequence |
| `reply_assign_schedule_to_sequence` | ✏️ | Set the sending schedule (business-hours window) |
| `reply_attach_offer_to_sequence` | ✏️ | Attach an offer to an AI SDR sequence |
| `reply_attach_playbook_to_sequence` | ✏️ | Attach a playbook to an AI SDR sequence |
| `reply_attach_knowledge_base_to_sequence` | ✏️ | Attach a knowledge base to an AI SDR sequence |
| `reply_set_sequence_reply_mode` | ✏️⭐ | Set Jason's Review / Autonomous reply mode |
## Contacts
| Tool | | Purpose |
| - | :-: | - |
| `reply_search_contacts` | 📖 | Look up contacts by exact email or LinkedIn URL |
| `reply_filter_contacts` | 📖 | List contacts by list membership, free-text search and contact field conditions |
| `reply_create_contact` | ✏️ | Create a contact (needs a name + email or LinkedIn URL) |
| `reply_update_contact` | ✏️ | Patch fields on an existing contact |
| `reply_get_contact_activity` | 📖 | Activity history for one contact (sends, opens, replies, calls) |
| `reply_mark_contacts_as_replied` | ✏️ | Mark up to 100 contacts as replied (or clear the flag) |
| `reply_change_contact_owner` | ✏️⭐ | Reassign up to 100 contacts to another user |
| `reply_blacklist_contact` | ✏️⭐ | Blacklist a contact's email (or whole domain) from outreach |
## Inbox & conversations
| Tool | | Purpose |
| - | :-: | - |
| `reply_get_inbox_emails` | 📖 | List inbox threads (email + LinkedIn) with short previews |
| `reply_send_inbox_reply` | ✏️⭐ | Send a reply on an existing thread (body only in v1) |
| `reply_change_inbox_category` | ✏️ | Assign or clear a thread's workspace category |
## Jason AI SDR
### Approvals & autopilot
| Tool | | Purpose |
| - | :-: | - |
| `reply_list_pending_approvals` | 📖 | The queue of Jason drafts awaiting approval |
| `reply_approve_message` | ✏️⭐ | Approve one draft and send it immediately |
| `reply_bulk_approve_messages` | ✏️⭐ | Approve and send up to 100 drafts (atomic batch) |
| `reply_reject_message` | ✏️⭐ | Reject a draft **and remove the contact from the sequence** |
| `reply_regenerate_message` | ✏️ | Ask Jason to rewrite a pending draft (optionally with feedback) |
### Knowledge bases
| Tool | | Purpose |
| - | :-: | - |
| `reply_list_knowledge_bases` | 📖 | List Jason knowledge bases |
| `reply_get_knowledge_base` | 📖 | Full detail of one knowledge base (instructions, URL sources) |
| `reply_create_knowledge_base` | ✏️ | Create a knowledge base |
| `reply_update_knowledge_base` | ✏️ | Rename or edit a knowledge base's instructions |
| `reply_add_knowledge_base_source` | ✏️ | Add a web-page URL source to a knowledge base |
| `reply_delete_knowledge_base_source` | ✏️ | Remove a URL source from a knowledge base |
### Reply handlers
| Tool | | Purpose |
| - | :-: | - |
| `reply_list_reply_handlers` | 📖 | List reply handlers in a knowledge base |
| `reply_get_reply_handler` | 📖 | Full detail of one reply handler |
| `reply_create_reply_handler` | ✏️ | Add a reply handler (question type → instructions) |
| `reply_update_reply_handler` | ✏️ | Patch a reply handler |
| `reply_delete_reply_handler` | ✏️ | Remove a reply handler |
### Reengagement cards
| Tool | | Purpose |
| - | :-: | - |
| `reply_list_reengagement_cards` | 📖 | List reengagement (win-back) cards in a knowledge base |
| `reply_get_reengagement_card` | 📖 | Full detail of one reengagement card |
| `reply_create_reengagement_card` | ✏️ | Add a reengagement card (with send-after days) |
| `reply_update_reengagement_card` | ✏️ | Patch a reengagement card |
| `reply_delete_reengagement_card` | ✏️ | Remove a reengagement card |
### Offers
| Tool | | Purpose |
| - | :-: | - |
| `reply_list_offers` | 📖 | List Jason offers (id + name) |
| `reply_get_offer` | 📖 | Full offer content (ICP, value props, proof points, CTAs) |
| `reply_create_offer` | ✏️ | Create an offer Jason can pitch |
| `reply_update_offer` | ✏️ | Patch an offer |
| `reply_generate_offer_from_website` | 📖 | Draft offer fields from a company website (does not save) |
### Playbooks
| Tool | | Purpose |
| - | :-: | - |
| `reply_list_playbooks` | 📖 | List Jason playbooks (id, name, visibility) |
| `reply_get_playbook` | 📖 | Full playbook, including the instruction body |
| `reply_create_playbook` | ✏️ | Create a playbook (Team or Organization visibility) |
| `reply_update_playbook` | ✏️ | Patch a playbook |
| `reply_duplicate_playbook` | ✏️ | Duplicate a playbook into a new one |
## Tasks
| Tool | | Purpose |
| - | :-: | - |
| `reply_list_my_tasks` | 📖 | List your tasks, filterable by type / status / due window / contact |
| `reply_create_task` | ✏️ | Create a standalone task (ToDo / Call / Meeting / LinkedIn / …) |
| `reply_complete_task` | ✏️ | Mark a task completed (with optional call resolution) |
## Workspace resolvers & accounts
| Tool | | Purpose |
| - | :-: | - |
| `reply_list_email_accounts` | 📖 | List mailboxes with connection status, daily limits, tags |
| `reply_list_linkedin_accounts` | 📖 | List connected LinkedIn accounts with health and tier |
| `reply_list_schedules` | 📖 | List sending schedules (timezone, default flag, slot counts) |
| `reply_search_lists` | 📖 | Resolve a contact list name to its `ListId` |
| `reply_search_team_members` | 📖 | Resolve a teammate name/email to their `UserId` |
## Help & meta
| Tool | | Purpose |
| - | :-: | - |
| `reply_search_knowledge_base` | 📖 | Search the Reply.io Help Center for how-to articles |
| `reply_get_knowledge_base_article` | 📖 | Read a full Help Center article by slug |
| `reply_get_app_map` | 📖 | Catalog of app areas with in-app navigation steps and links |
| `reply_report_unsupported_request` | 📖 | Log a capability Reply.io doesn't have, for the product team |
## Regenerate this reference
This catalog is not hand-maintained trust — regenerate it in seconds by probing the running server:
```bash theme={null}
# 1) initialize
curl -s -X POST https://mcp.reply.io/ \
-H "Authorization: Bearer YOUR_REPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize",
"params":{"protocolVersion":"2025-06-18","capabilities":{},
"clientInfo":{"name":"probe","version":"0.1"}}}'
# 2) list tools
curl -s -X POST https://mcp.reply.io/ \
-H "Authorization: Bearer YOUR_REPLY_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
```
Responses are SSE — take the JSON after the last `data:` line. If the returned tool set differs
from this page, the server is newer — **trust the server**.
# Skill catalog
Source: https://docs.reply.io/skills/catalog
All 18 Reply skills by pack — what each one does, when it triggers, its maturity, and the skills it builds on.
Every skill in [reply-skills](https://github.com/reply-team/reply-skills), grouped by the pack that
ships it. Install once and you get the whole pack — see [Install](/skills/overview#install).
> [!NOTE]
>
> Each skill's own frontmatter is the source of truth, and
> [`INDEX.md`](https://github.com/reply-team/reply-skills/blob/main/INDEX.md) in the repo is generated
> from it on every change. Treat the maturity levels below as a snapshot; `INDEX.md` is always current.
**Maturity levels:** `draft` — structurally complete, content plausible · `reviewed` — a maintainer or
domain expert signed off · `validated` — real executions confirmed the guidance · `production` —
safe to follow blindly.
## `ai-sdr-core` — 9 skills
Vendor-neutral SDR expertise: the business-operation contract, outbound strategy and playbooks, and
the guardrails that keep automated outreach safe. **The base pack** — every other pack builds on it,
and it carries no dependencies of its own.
### sdr-operations
*The vendor-neutral contract of atomic SDR business operations.*
Names each operation an SDR actually performs — add a contact, enrol it into a sequence, pause, reply,
classify a conversation, read engagement — in practitioner language with no provider detail. Every
other skill plans against these names, which is what lets a different provider adapter drop in without
rewriting the strategy layer. Ships an `references/operation-catalog.md` with the full operation list,
each one's effect, reversibility, and approval level.
Triggers when planning any outbound work, when writing a plan something else must execute, or before
reaching for a provider-specific execution skill.
**Category** operations · **Maturity** `draft` · **Recommends** `approval-boundaries`, `campaign-planning`
> [!WARNING]
>
> Changing an operation's effect, reversibility, or approval level here is a breaking change — every
> guardrail downstream reads those.
### campaign-planning
*Turn a vague outbound goal into an executable plan.*
Clarifies the objective until success is observable, surfaces the constraints that shape it, composes
the work from known operations and playbooks, and decides the checkpoints. This is the entry point
when someone states a business outcome rather than an action.
Triggers on a business goal — book meetings, launch a campaign, grow pipeline — rather than a single
concrete request.
**Category** strategy · **Maturity** `draft` · **Depends on** `sdr-operations` · **Recommends** `audience-building`, `campaign-launch`, `inbox-triage`, `performance-analysis`, `sending-guardrails`, `durable-work`
### audience-building
*Turn raw prospect data into a clean, deliberately-shaped audience.*
Decides who belongs, maps and sanity-checks the incoming fields, chooses a duplicate policy, and
organises people into named lists. Handles the messy-data questions explicitly rather than importing
whatever arrives.
Triggers when the user wants to import contacts, build or extend a list, define a segment, or asks
what to do about duplicates.
**Category** strategy · **Maturity** `draft` · **Depends on** `sdr-operations` · **Recommends** `campaign-launch`, `sending-guardrails`, `approval-boundaries`
**Guide** [Import and clean contacts](/guides/import-contacts)
### campaign-launch
*Prepare and launch a sequence with every precondition checked and the send explicitly approved.*
Covers sending capability, step content, schedule, enrolment, and the go-live gate. Nothing starts
until the user has approved what will actually be sent.
Triggers when the user wants to create or start a sequence, launch a campaign, add contacts to a
sequence, or begin sending.
**Category** strategy · **Maturity** `draft` · **Depends on** `sdr-operations`, `approval-boundaries` · **Recommends** `audience-building`, `sending-guardrails`, `linkedin-guardrails`, `performance-analysis`
**Guide** [Launch multichannel outreach](/guides/launch-outreach)
### inbox-triage
*Work the inbound replies — surface what matters, draft together, send only what was approved.*
Orders conversations by what deserves attention first, gives compact thread context, drafts responses
with the user, sends only explicitly approved text, and records each conversation's outcome.
Triggers when the user asks about replies, inbox triage, responding to prospects, or finding the
interested leads.
**Category** strategy · **Maturity** `draft` · **Depends on** `sdr-operations`, `approval-boundaries` · **Recommends** `performance-analysis`, `campaign-launch`
**Guide** [Convert replies into meetings](/guides/convert-replies-to-meetings)
### performance-analysis
*An honest read on outreach performance, with a diagnosis that separates the causes.*
Account and per-campaign figures over a stated window, then a diagnosis that distinguishes
deliverability from copy from targeting — followed by one or two high-impact recommendations rather
than a list of everything observable.
Triggers when the user asks how campaigns are performing, what is underperforming, what to fix or
pause, or wants outreach analytics.
**Category** strategy · **Maturity** `draft` · **Depends on** `sdr-operations` · **Recommends** `sending-guardrails`, `campaign-launch`, `inbox-triage`, `approval-boundaries`
**Guides** [Decide what to scale or fix](/guides/analyze-performance) · [Improve sequences every cycle](/guides/improve-sequences)
### approval-boundaries
*Where an agent must stop and ask — and the one case where acting first is correct.*
Defines what a valid confirmation looks like, when an earlier approval still applies, and how bulk
writes, sending to real people, unattended runs, retries, and anomaly stop-rules are gated. Every
other skill defers to this one rather than restating the rules, so they cannot drift.
Triggers before any operation touching a real prospect, when deciding whether an approval still
applies, or when configuring an agent to run unattended.
**Category** protection · **Maturity** `draft` · **Depends on** `sdr-operations` · **Recommends** `sending-guardrails`, `linkedin-guardrails`
**See also** [Agent safety rules](/agents/safety)
### sending-guardrails
*Protect sender reputation and inbox placement.*
Domain authentication, warm-up, volume pacing, bounce interpretation, and recovery when deliverability
degrades.
Triggers before launching significant email volume, when bounce rates rise, when replies collapse, or
when a sending account or domain is new.
**Category** protection · **Maturity** `draft` · **Depends on** `sdr-operations` · **Recommends** `campaign-launch`, `performance-analysis`, `approval-boundaries`
> [!NOTE]
>
> Ships as an honest skeleton with `TODO(expert)` markers — the structure and safety posture are
> final; the specific thresholds await expert validation.
### linkedin-guardrails
*Keep social accounts safe under automation.*
Invitation pacing, messaging cadence, daily limits, and recovery when the platform flags activity.
Triggers before any LinkedIn outreach volume, when configuring account limits, or when an account
shows a warning.
**Category** protection · **Maturity** `draft` · **Depends on** `sdr-operations` · **Recommends** `campaign-launch`, `approval-boundaries`
> [!NOTE]
>
> Also an honest skeleton with `TODO(expert)` markers.
## `reply-adapter` — 5 skills
Executes the core operation contract against Reply.io — the endpoints, auth, call ordering, and error
translation that turn a planned operation into a real one. **Requires `ai-sdr-core`** and a Reply.io
account.
### reply-cli
*Operate Reply.io from the terminal with the `reply` CLI.*
Sign in via OAuth or an API key, manage profiles and team context, and call any v3 endpoint through
`reply api`. This is the skill the others lean on when they need commands actually executed.
Triggers when executing any Reply.io operation from a shell, setting up authentication, or when
another Reply skill needs commands run.
**Category** execution · **Maturity** `reviewed` · **Recommends** `reply-api`, `reply-auth`, `reply-operations-mapping`
**Docs** [Reply CLI](/cli/overview) · [Using the CLI from agents](/cli/agents)
### reply-api
*Work with Reply.io API v3 correctly.*
Discover endpoints through the machine-readable docs, respect scopes and rate limits, and handle
`problem+json` errors and background jobs. Reading this before choosing an endpoint is what stops an
agent inventing paths.
Triggers before calling any non-trivial v3 endpoint, when choosing an endpoint for a task, or when a
call fails and needs interpretation.
**Category** execution · **Maturity** `reviewed` · **Depends on** `reply-cli` · **Recommends** `reply-auth`, `reply-operations-mapping`
**Docs** [API introduction](/api-reference/introduction) · [Rate limits](/api-reference/rate-limits) · [Machine-readable](/agents/machine-readable)
### reply-auth
*Reply.io credentials in depth.*
API key types (personal, Team, Organization), the `domain:verb` scopes model, acting-user headers, and
the team/organization resolution errors — `TEAM_REQUIRED`, `USER_REQUIRED` and friends.
Triggers when choosing or creating a key for an agent, resolving `401`/`403` errors, or working across
multiple teams.
**Category** execution · **Maturity** `reviewed` · **Recommends** `reply-cli`, `reply-mcp`, `approval-boundaries`
**Docs** [Authentication](/api-reference/authentication)
### reply-mcp
*Connect Reply.io to an MCP-compatible client, and know when to prefer it.*
Wiring `mcp.reply.io` into Claude, ChatGPT, Codex, or Cursor, choosing the right auth for the client,
and deciding when MCP tools beat CLI commands.
Triggers when setting up the Reply MCP connection or choosing between MCP and CLI execution.
**Category** execution · **Maturity** `reviewed` · **Recommends** `reply-cli`, `reply-auth`
**Docs** [Reply MCP](/mcp/overview) · [Connect](/mcp/connect)
### reply-operations-mapping
*The join table: each vendor-neutral operation → its Reply.io execution.*
For every operation named in `sdr-operations`, which v3 endpoint group and doc page serves it, which
scope it needs, what order composite work must run in, and how Reply's errors translate back into
operation outcomes.
Triggers when a plan names an operation and it has to actually run against Reply, or when a Reply
response needs interpreting in business terms.
**Category** execution · **Maturity** `draft` · **Depends on** `reply-api`, `reply-cli`, `sdr-operations` · **Recommends** `reply-auth`, `reply-mcp`
**Covers** contacts · contact lists · sequences · sequence steps · sequence contacts · inbox · reports · email accounts · LinkedIn accounts · schedules · background jobs
## `agentic-runtime` — 4 skills
Durable multi-session work in a plain-markdown workspace the user owns. **Requires `ai-sdr-core`.**
Optional — skip it if your orchestrator already provides durable work.
### durable-work
*How long-running work survives a session ending.*
Goals, plans, work items, checkpoints, approval pauses, recovery, and resumption — all kept as plain
markdown the user can read and edit. Ships `references/workspace-spec.md` plus `templates/plan.md` and
`templates/work-item.md` so the shapes are concrete rather than described.
Triggers when work spans more than one session, when resuming work something else started, or when a
plan needs persisting rather than holding in conversation.
**Category** runtime · **Maturity** `draft` · **Depends on** `sdr-operations` · **Recommends** `execution-reporting`, `user-memory`, `campaign-planning`, `approval-boundaries`
### execution-reporting
*Write execution reports that become organisational memory.*
Structure, evidence, honest deviations, and feeding results back into the next planning pass. Ships
`templates/report.md`.
Triggers after completing meaningful execution, at a plan checkpoint, or when closing a work item.
**Category** runtime · **Maturity** `draft` · **Depends on** `durable-work` · **Recommends** `user-memory`, `performance-analysis`
### orchestrator-integration
*How durable work is driven when nobody is watching.*
Which orchestrator owns scheduling and resumption, how to stop two of them fighting over the same
workspace, and what changes when a run is unattended.
Triggers when setting up background or recurring outbound work, or when more than one orchestration
runtime is available.
**Category** runtime · **Maturity** `draft` · **Depends on** `durable-work` · **Recommends** `approval-boundaries`, `execution-reporting`
**Guide** [Automate outbound end-to-end](/guides/automate-outbound)
### user-memory
*How agents store and reuse knowledge about the user.*
Preferences, ICP definitions, playbooks, and other durable context, kept in the workspace so a fresh
session does not have to ask again.
Triggers when learning something about the user worth keeping — tone, constraints, ICP — or before
drafting content that should reflect their preferences.
**Category** user-knowledge · **Maturity** `draft` · **Depends on** `durable-work` · **Recommends** `inbox-triage`, `campaign-planning`, `audience-building`
## Related
* [Install and manage the packs](/skills/overview)
* [Choose your interface](/agents/choose-your-interface) — Skills vs MCP vs CLI vs API
* [Agent safety rules](/agents/safety)
* [`INDEX.md`](https://github.com/reply-team/reply-skills/blob/main/INDEX.md) — the generated, always-current catalog
* [`docs/skill-contract.md`](https://github.com/reply-team/reply-skills/blob/main/docs/skill-contract.md) — the contract every skill follows
# Reply Skills
Source: https://docs.reply.io/skills/overview
Outbound expertise as markdown skills — three installable packs that teach your agent what to run, in what order, and with which guardrails.
[reply-skills](https://github.com/reply-team/reply-skills) packages Reply.io's outbound expertise as
plain-markdown **Agent Skills**: 18 skills across three independently installable packs. A skill is a
folder containing a `SKILL.md` — a description your agent's router matches on, plus the guidance it
loads when the description matches. No runtime, no code, nothing to host.
Skills use the open [Agent Skills](https://agentskills.io) format, so they load in Claude Code,
Codex, and any other `SKILL.md`-compatible host.
> [!NOTE]
>
> **MCP gives your agent tools. Skills give it judgement.** MCP and the CLI are *execution*
> surfaces — individual operations your agent can call. Skills are *procedure*: which operations to
> compose, in what order, what to verify, and where to stop and ask. See
> [Choose your interface](/agents/choose-your-interface).
## The three packs
The packs split along a clean line: the SDR methodology, the Reply.io execution layer, and the
durable-work runtime each install on their own, so you take the pieces your setup calls for.
| Pack | Alias | Skills | What your agent gains | Requires |
| - | - | - | - | - |
| **`ai-sdr-core`** | `core` | 9 | What an SDR operation *is*, outbound strategy and playbooks, and the guardrails — sending limits, channel limits, approval boundaries | — |
| **`reply-adapter`** | `adapter` | 5 | Executing those operations against Reply.io: the CLI, API v3, MCP, auth and scopes, error translation | `ai-sdr-core` + a Reply.io account |
| **`agentic-runtime`** | `runtime` | 4 | Durable multi-session work: goals, plans, work items, checkpoints, resumability, reports, user memory | `ai-sdr-core` |
```
┌───────────────┐
│ ai-sdr-core │ the base pack · SDR methodology
└───────┬───────┘
┌─────────┴─────────┐
┌─────────▼──────┐ ┌────────▼─────────┐
│ reply-adapter │ │ agentic-runtime │
│ Reply.io │ │ durable work │
└────────────────┘ └──────────────────┘
```
`ai-sdr-core` has no dependencies of its own, and `reply-adapter` and `agentic-runtime` never depend
on each other — either can be absent. Guardrails and approval boundaries ship **inside
`ai-sdr-core`**, so no selective install can leave safe operation out.
> [!TIP]
>
> `reply-adapter` is the pack that connects to Reply.io — install it when you want your agent
> operating the platform. The other two carry the methodology and the runtime, and depend only on
> `ai-sdr-core`.
Every skill, with its pack, category, and maturity: [Skill catalog](/skills/catalog).
## Install
### `reply skills install` — recommended
The [Reply CLI](/cli/overview#skills) detects the assistants on your machine and installs all three
packs into each one, resolving dependencies itself:
```bash theme={null}
npm install -g reply-cli # needs Node.js 20 or newer
reply skills install
```
```
✓ detected Claude Code, Codex
✓ Claude Code · ai-sdr-core, reply-adapter, agentic-runtime installed
✓ Codex · ai-sdr-core, reply-adapter, agentic-runtime installed
Start a new session in each assistant so the skills load.
```
Install a subset — dependencies come along, so `adapter` pulls `core`:
```bash theme={null}
reply skills install core
reply skills install adapter runtime
reply skills install --agent codex # only this assistant
reply skills install --project # into this repository, not your home directory
reply skills install --dry-run # show the plan, change nothing
```
Full command surface and flags: [Reply CLI → Skills](/cli/overview#skills).
### Claude Code — plugin marketplace
```bash theme={null}
claude plugin marketplace add reply-team/reply-skills
claude plugin install reply-adapter@reply-skills
claude plugin install agentic-runtime@reply-skills
```
`ai-sdr-core` is resolved automatically as a dependency of either pack — Claude Code reports
`(+ 1 dependency: ai-sdr-core)`. Install it alone if you want the vendor-neutral expertise only:
```bash theme={null}
claude plugin install ai-sdr-core@reply-skills
```
Skills arrive namespaced per pack — `ai-sdr-core:campaign-launch`, `reply-adapter:reply-cli` — so they
never collide with skills you wrote yourself.
### Codex — plugin marketplace
```bash theme={null}
codex plugin marketplace add reply-team/reply-skills
# ai-sdr-core FIRST — Codex resolves no dependencies
codex plugin add ai-sdr-core@reply-skills
codex plugin add reply-adapter@reply-skills
codex plugin add agentic-runtime@reply-skills
```
> [!WARNING]
>
> **Install order matters on Codex.** The Codex plugin format has no dependency field, so nothing
> installs `ai-sdr-core` for you. Adding `reply-adapter` on its own gives you five skills whose
> guidance is missing. Install the core first, or install all three.
Skills are namespaced per pack here too. Re-running `codex plugin add` upgrades in place rather than
duplicating the entry.
### Any host — the skills ecosystem CLI
[`npx skills`](https://github.com/vercel-labs/skills) is the ecosystem package manager for Agent
Skills, with a directory entry at
[skills.sh/reply-team/reply-skills](https://www.skills.sh/reply-team/reply-skills). Use it to reach
hosts Reply does not package for individually.
```bash theme={null}
npx skills add reply-team/reply-skills # asks where to install
npx skills add reply-team/reply-skills --skill '*' --agent claude-code -y # no prompts
npx skills add reply-team/reply-skills --list # look, install nothing
```
> [!WARNING]
>
> **This channel has no pack model.** It installs individual skills by name — no packs, no
> namespacing, no dependency resolution. **Install all 18.** A `--skill` subset is your own
> responsibility: the CLI will install `reply-operations-mapping` or `durable-work` without
> `sdr-operations` and say nothing about it, leaving a skill whose declared dependency is absent.
Provenance is recorded in `skills-lock.json`, so `npx skills update` works later.
### Cursor, Windsurf, Gemini CLI, GitHub Copilot — directory copy
These hosts have no plugin mechanism, so a pack is installed by copying its skills directory. That
works because a pack is just a directory of skills.
```bash theme={null}
git clone https://github.com/reply-team/reply-skills /tmp/reply-skills
# ai-sdr-core is required by the others — copy it first
cp -r /tmp/reply-skills/plugins/ai-sdr-core/skills/* /
cp -r /tmp/reply-skills/plugins/reply-adapter/skills/* /
cp -r /tmp/reply-skills/plugins/agentic-runtime/skills/* /
```
`reply skills install` does this copying for you, to the same paths. Never copy `reply-adapter` or
`agentic-runtime` without `ai-sdr-core`, or their skills will reference guidance that is not there.
## Install channels compared
Each row states the version it was verified against. Rows marked *not verified* have instructions
that are a reasonable starting point, not a promise.
| Channel | Installs | Dependency handling | Layout on disk | Verified against |
| - | - | - | - | - |
| **`reply skills install`** | Packs | **Resolved by the installer** on every host | Whatever the channel it drives produces | reply CLI 0.4.0 — Claude Code and Codex; other hosts receive files, unconfirmed |
| Claude Code plugin marketplace | Packs | **Resolved by the host** — `reply-adapter` pulls `ai-sdr-core` | Namespaced per pack | Claude Code 2.1.220 |
| Codex plugin marketplace | Packs | **Manual** — install `ai-sdr-core` first | Namespaced per pack | codex-cli 0.146.0-alpha.3.1 |
| `npx skills` / [skills.sh](https://www.skills.sh/reply-team/reply-skills) | Individual skills | **None** — install all 18 yourself | Flat, no namespacing | skills CLI 1.5.21 |
| Cursor · Windsurf · Gemini CLI · GitHub Copilot | Skills, by copying | **Manual** — copy `ai-sdr-core` first | Flat, per host path | Not verified |
Only the first two channels resolve the `ai-sdr-core` dependency for you.
## Where the files land
`reply skills install` writes to your user directory by default, or to the current repository with
`--project`.
| Assistant | How it receives the packs | Project-scoped path | Paths verified |
| - | - | - | - |
| Claude Code | its own plugin CLI | `.claude/skills/` | Yes |
| Codex | its own plugin CLI (`--project` copies files instead) | `.agents/skills/` | Yes |
| Cursor | copied files | `.agents/skills/` | Not yet |
| Gemini CLI | copied files | `.agents/skills/` | Not yet |
| GitHub Copilot | copied files | `.agents/skills/` | Not yet |
| Windsurf | copied files | `.windsurf/skills/` | Not yet |
On Claude Code and Codex the packs go through the assistant's own plugin mechanism, so they keep
updating through it. Other `SKILL.md` hosts receive the skills as files.
> [!NOTE]
>
> **"Not yet" means the skills directory came from that assistant's documentation** and has not been
> confirmed by a verification run. The install works; what is unconfirmed is whether the assistant
> reads from where the files were put. Those hosts are marked `(paths not yet verified)` in the report
> and carry `"verified": false` in `--json` output.
## Verify the install
```bash theme={null}
reply skills list # what's installed where, and what has an update available
reply skills list --json # machine-readable, including per-host `verified`
```
On Claude Code you can also ask the host directly:
```bash theme={null}
claude plugin list
claude plugin details ai-sdr-core # its skills and their token cost
```
**Start a new session** in each assistant — newly installed skills are picked up at session start,
not mid-conversation.
## Connect an execution surface
**Installing skills is a separate step from connecting Reply.io.** `reply-adapter` is the pack that
calls the platform, so it needs at least one Reply.io execution surface configured:
| Surface | When to use it | Start |
| - | - | - |
| [Reply CLI](/cli/overview) | Your agent has a shell. `reply api` reaches every v3 endpoint. | `reply auth login` |
| [Reply MCP](/mcp/overview) | Your client speaks MCP and has no shell — desktop apps, hosted assistants. | [Connect](/mcp/connect) |
| [REST API v3](/api-reference/introduction) | You are driving the API directly. | [Get a key](/api-reference/authentication) |
If the CLI is installed, this confirms the adapter has something to drive:
```bash theme={null}
reply auth whoami
```
Agents driving the API directly should start at
[llms.txt](https://docs.reply.io/llms.txt) — see [Machine-readable](/agents/machine-readable).
## Run your first skill
Once installed, ask your agent in plain language — the host routes to a skill by matching its
description:
* *"Import this CSV as a new list and tell me about the duplicates"* → `audience-building`
* *"Plan an outbound campaign to book ten meetings with fintech founders"* → `campaign-planning`
* *"What sending limits should I respect on a brand-new domain?"* → `sending-guardrails`
* *"Show me the interested replies from this week"* → `inbox-triage`
* *"Which campaigns are underperforming, and what should I fix?"* → `performance-analysis`
* *"Turn this goal into a plan I can resume tomorrow"* → `durable-work`
## Safety model
Skills never let an agent start a sequence, send a message, or delete data without your explicit
confirmation in the conversation. Anything that sends content requires you to approve the **literal
text** first. Bulk operations show their plan and their counts before running.
Protective actions are the one exception: pausing a campaign that is burning your domain happens
first and tells you immediately, because waiting is the destructive choice.
The rules live in one skill — `approval-boundaries` — and ship inside `ai-sdr-core`, so no selective
install can omit them. Bound them mechanically as well, with
[scoped API keys](/api-reference/authentication): grant an agent only the scopes its work needs. See
[Agent safety rules](/agents/safety).
## Manage installed packs
```bash theme={null}
reply skills list # what's installed where
reply skills update # bring installed packs to the latest version
reply skills remove runtime # remove one pack
reply skills remove # remove all of them
```
Add `--dry-run` to any of them to see the plan without changing anything. Removing a pack that
another installed pack depends on is refused — remove both, or run `reply skills remove` with no pack.
Through Claude Code's own plugin mechanism:
```bash theme={null}
claude plugin update reply-adapter # restart to apply
claude plugin uninstall reply-adapter
claude plugin prune # drop dependencies nothing needs any more
```
## Troubleshooting
> [accordion] The agent doesn't seem to know the skills
>
> Skills load at session start. Start a **new** session in the assistant, then ask something that
> matches a skill description — hosts route on the `description` field, so a vague prompt may match
> nothing. Confirm the install first with `reply skills list`.
> [accordion] A skill references guidance that isn't there
>
> A pack was installed without `ai-sdr-core`. Only `reply skills install` and the Claude Code
> marketplace resolve that dependency; on Codex, `npx skills`, and directory copies it is your job.
> Install the core and start a new session.
> [accordion] `which codex` says Codex is missing on Windows
>
> The `codex` binary is not on `PATH` — it ships with the desktop app at
> `%LOCALAPPDATA%\OpenAI\Codex\bin\\codex.exe`. Call it by full path. Tooling that detects
> Codex with `which codex` will wrongly report it as absent.
> [accordion] Skills installed, but Reply operations fail
>
> `reply-adapter` needs a working Reply.io credential. Run `reply auth whoami`; if it fails, run
> `reply auth login`. For `401`/`403` on a specific call, check the key's scopes against
> [Authentication](/api-reference/authentication).
> [accordion] The install reported a host as unverified
>
> Expected for Cursor, Windsurf, Gemini CLI, and GitHub Copilot. The files were written to the path
> that host documents, but Reply has not confirmed the host reads them. Check the host's own skills
> directory and consult its documentation.
## Maturity and honest gaps
Each skill carries a maturity level — `draft`, `reviewed`, `validated`, or `production`. Some business
and protection content ships as **honest skeletons** marked `TODO(expert)`: the structure and safety
posture are final, the specific numbers await validation by domain experts. A visible gap is
deliberate; invented expertise would be worse. Per-skill maturity is in the
[Skill catalog](/skills/catalog).
## Links
* Repo: [github.com/reply-team/reply-skills](https://github.com/reply-team/reply-skills) (MIT)
* Live catalog, always current: [`INDEX.md`](https://github.com/reply-team/reply-skills/blob/main/INDEX.md)
* The contract every skill follows: [`docs/skill-contract.md`](https://github.com/reply-team/reply-skills/blob/main/docs/skill-contract.md)
* Pack architecture and invariants: [`docs/packs.md`](https://github.com/reply-team/reply-skills/blob/main/docs/packs.md)
* Execution layer: [Reply CLI](/cli/overview) · [Reply MCP](/mcp/overview) · [API v3](/api-reference/introduction)
* Next: [Skill catalog](/skills/catalog)
# Webhook event payloads
Source: https://docs.reply.io/webhook-event-payloads
See the exact JSON Reply sends for every webhook event, including the shared event envelope and the fields unique to each event type.
When a webhook subscription fires, Reply sends a JSON payload to your configured URL.
This page documents the payload for each supported event type. The examples match the structure of real webhook deliveries.
## Event envelope
Every webhook delivery includes the same top-level event envelope:
```json theme={null}
{
"event": {
"date": "2026-04-21T09:30:00.000Z",
"id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1",
"type": "email_replied",
"user_id": 1234,
"team_id": 100,
"subscription_id": 42
},
// event-specific fields follow, flat at the top level
}
```
| Field | Type | Notes |
| - | - | - |
| `event.date` | ISO-8601 UTC | Time the event occurred in Reply. |
| `event.id` | UUID | Unique event identifier. Use it for idempotency when processing events. |
| `event.type` | string | Event type. Matches the subscription's `eventType`. |
| `event.user_id` | int | ID of the Reply user associated with the subscription. |
| `event.team_id` | int | ID of the team associated with the event. |
| `event.subscription_id` | int | ID of the subscription that triggered the event. |
## Shared conventions
* Property names use `snake_case`, for example `event_type`, `sequence_fields`, and `reply_message_url`.
* Enum values are PascalCase strings, for example `"Personal"`, `"EmailDetected"`, and `"Hard"`.
* Timestamps use ISO-8601 UTC format with millisecond precision.
* Events associated with a contact include a `contact_fields` object. Use `contact_fields.id` as the stable contact identifier.
* If the subscription was created with `includeProspectCustomFields: true`, a `contact_custom_fields` object is also included.
* Events associated with a sequence include a `sequence_fields` object.
* If `SequenceId` is `0`, the event is not associated with a sequence and `sequence_fields` may be empty or omitted.
* Email-related events respect the subscription's `includeEmailUrl` and `includeEmailText` settings. Disabled fields are omitted from the payload.
## Reusable blocks
The following objects appear in multiple event payloads.
### `contact_fields`
```json theme={null}
{
"id": 12345,
"email": "prospect@example.com",
"first_name": "Test",
"last_name": "Prospect",
"full_name": "Test Prospect",
"title": "Test Title",
"company": "Test Company",
"linkedin_profile_url": "https://linkedin.com/in/test",
"city": "Test City",
"state": "Test State",
"country": "Test Country",
"time_zone_id": "America/Los_Angeles",
"phone": "+1234567890",
"domain": "example.com",
"company_size": "51-200 employees",
"industry": "Software",
"linkedin_sales_navigator": "https://www.linkedin.com/sales/people/test",
"linkedin_recruiter": "https://www.linkedin.com/recruiter/people/test"
}
```
### `contact_custom_fields`
Only included when the subscription was created with `payloadConfig.includeProspectCustomFields: true`.
Keys match the custom field names configured on the contact.
```json theme={null}
{
"Custom Field 1": "Custom Value 1"
}
```
### `sequence_fields`
```json theme={null}
{
"id": 200,
"name": "Test Sequence",
"step_number": 1
}
```
## Variant fields
Events tied to a sequence email or a sequence LinkedIn message identify the step's A/B variant with a top-level ID field:
| Channel | Field | Events |
| - | - | - |
| Email | `sent_email_variant_id` (int) | `email_sent`, `email_opened`, `email_link_clicked`, `email_bounced`, `email_replied`, `email_auto_reply`, `reply_categorized` |
| LinkedIn | `linkedin_message_variant_id` (int) | `linkedin_message_sent`, `linkedin_connection_request_sent`, `linkedin_connection_request_accepted`, `linkedin_message_replied`, `linkedin_reply_categorized` |
* The ID is the variant's `id` from `GET /v3/sequences/{id}/steps/{step_id}/variants`. It matches `variantId` on reporting rows (`POST /v3/reporting/emails`, `POST /v3/reporting/linkedin`) and `steps[].variants[].id` in `POST /v3/sequences/{id}/stats/emails` and `POST /v3/sequences/{id}/stats/linkedin`. It never changes, so join and aggregate on it.
* Customized and AI-personalized emails are attributed to the variant they were customized from.
* `linkedin_message_replied` and `linkedin_reply_categorized` carry the variant of the latest sequence message sent in the conversation before the reply.
* The field is omitted, never `null`, when there is no variant — for example manual one-off emails, direct emails and replies not tied to a sequence, and direct LinkedIn connection requests.
* `contact_replied` does not carry variant fields. Use the matching per-channel event.
## Event reference
### `email_replied`
**When it fires:** Once per recorded email reply — when Reply detects an incoming reply to a sequence email, or a direct reply that is not tied to a sequence.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "email_replied", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"email_account_id": 1,
"sent_email_id": 999,
"sent_email_variant_id": 5001,
"reply_date": "2026-04-21T09:30:00.000Z",
"reply_message_id": "test-reply-msg-id",
"email_from": "account@example.com",
"email_to": ["account@example.com"],
"email_cc": ["colleague@example.com"],
"reply_message_url": "https://example.com/test-email-blob",
"email_text": "…",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `email_account_id`
* The Reply email account that received the reply.
* `sent_email_id`
* The sequence email that was replied to. `null` for direct replies that are not tied to a sequence email.
* `sent_email_variant_id`
* The A/B variant of the email that was replied to. Omitted for direct replies. See [Variant fields](#variant-fields).
* `email_from`
* Present when the replying email account is known.
* `email_to`, `email_cc`, `email_bcc`
* Recipients of the reply, as arrays of email addresses read from the message headers. `email_to` normally holds the address of the Reply email account that received the reply, and `email_cc` holds anyone the contact copied in.
* A header carrying no address is omitted rather than sent empty. `email_bcc` is therefore absent in practice: a `Bcc` header does not survive delivery, so an incoming message has none.
* Unlike `reply_message_url` and `email_text`, these are not controlled by `includeEmailUrl` or `includeEmailText` — they are present whenever the stored reply message is readable.
* `reply_message_url`
* Included when `includeEmailUrl: true`.
* `email_text`
* Included when `includeEmailText: true`.
* `sequence_fields`
* Omitted for direct replies that have no sequence context.
* `contact_custom_fields`
* Included when `includeProspectCustomFields: true`.
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `reply_categorized`
**When it fires:** An email reply is categorized automatically by Reply or manually by a user.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "reply_categorized", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"sent_email_id": 999,
"sent_email_variant_id": 5001,
"reply_date": "2026-04-21T09:30:00.000Z",
"reply_message_id": "test-reply-msg-id",
"reply_subject": "Re: Test Subject",
"reply_inbox_category_name": "Interested",
"reply_message_url": "https://example.com/test-email-blob",
"email_text": "…",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `reply_inbox_category_name`
* Human-readable category name.
* Built-in values include:
* `"No categories"`
* `"Interested"`
* `"Not interested"`
* `"Do not contact"`
* `"Not now"`
* `"Forwarded"`
* `"Meeting intent"`
* Teams can create custom categories. Treat this field as a free-form string.
* `sent_email_variant_id`
* The A/B variant of the email that was replied to. See [Variant fields](#variant-fields).
* `reply_message_id`
* May be `null` for older replies where the original message ID was not captured.
* `reply_date`
* May be `null` for older replies where the original timestamp is unavailable.
* `reply_subject`
* Subject line of the contact's reply email.
* May be `null` when the reply carries no subject.
* `reply_message_url`
* Included when `includeEmailUrl: true` and a stored reply is available.
* `email_text`
* Included when `includeEmailText: true` and the reply body can be extracted.
* `contact_custom_fields`
* Included when `includeProspectCustomFields: true`.
* `sequence_fields` includes `id`, `name`, and `step_number`. Omitted if the reply is not associated with a sequence.
### `email_sent`
**When:** Reply sends an email from a sequence step.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "email_sent", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"email_account_id": 1,
"sent_email_id": 999,
"sent_email_message_id": "test-message-id",
"sent_email_date": "2026-04-21T09:30:00.000Z",
"sent_message_url": "https://example.com/test-email-blob",
"email_text": "…",
"email_from": "account@example.com",
"sent_email_variant": "A",
"sent_email_variant_id": 5001,
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `sent_email_variant` identifies the A/B variant that was sent. Omitted when the step has only one variant.
* `sent_email_variant_id` is the ID of that variant. Omitted for manual one-off emails. See [Variant fields](#variant-fields).
* `sent_message_url` is included when `includeEmailUrl` is enabled and the message blob is available.
* `email_text` is included when `includeEmailText` is enabled and the message body can be parsed.
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `email_opened`
**When:** A recipient opens a tracked email.
Opens from IP addresses in the user's exclusion list are ignored.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "email_opened", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"email_account_id": 1,
"sent_email_id": 999,
"sent_email_variant_id": 5001,
"sent_email_message_id": "test-message-id",
"email_open_date": "2026-04-21T09:30:00.000Z",
"opens_count": 1,
"email_from": "account@example.com",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `opens_count` is the total number of opens for the email. It increases each time the email is opened.
* `sent_email_variant_id` identifies the A/B variant of the opened email. See [Variant fields](#variant-fields).
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `email_link_clicked`
**When:** A recipient clicks a tracked link in an email.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "email_link_clicked", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"email_link_url": "https://example.com/test-link",
"sent_email_id": 999,
"sent_email_variant_id": 5001,
"email_from": "account@example.com",
"contact_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `sent_email_id` is the email whose link was clicked. Omitted when the email is not known.
* `sent_email_variant_id` identifies the A/B variant of that email. See [Variant fields](#variant-fields).
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `email_bounced`
**When:** A sent email bounces or is rejected by the recipient's mail server.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "email_bounced", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"email_account_id": 1,
"sent_email_id": 999,
"sent_email_variant_id": 5001,
"bounce_date": "2026-04-21T09:30:00.000Z",
"bounce_type": "Hard",
"bounce_message_id": "test-bounce-id",
"sent_message_url": "https://example.com/test-email-blob",
"email_text": "…",
"email_from": "account@example.com",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `bounce_type` can be:
* `Unknown`
* `Soft`
* `Hard`
* `GmailApiLimitWarning`
* `Office365LimitWarning`
* `MailboxFull`
* `AuthenticationFailure`
* `SpamRejection`
* `PolicyViolation`
* `sent_email_variant_id` identifies the A/B variant of the bounced email. See [Variant fields](#variant-fields).
* `sent_message_url` is included when `includeEmailUrl` is enabled and the message blob is available.
* `email_text` is included when `includeEmailText` is enabled and the message body can be parsed.
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `email_auto_reply`
**When:** Reply identifies an incoming message as an auto-reply or out-of-office message.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "email_auto_reply", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"email_account_id": 1,
"sent_email_id": 999,
"sent_email_variant_id": 5001,
"reply_date": "2026-04-21T09:30:00.000Z",
"reply_message_id": "test-reply-id",
"reply_subject": "Out of Office: Test Subject",
"reply_type": "AutoReply",
"reply_message_url": "https://example.com/test-email-blob",
"email_text": "…",
"email_from": "account@example.com",
"user_name": "Test User",
"user_email": "user@example.com",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `reply_type` is:
* `AutoReply` for automatic responder messages
* `OutOfOffice` for out-of-office messages
* `sent_email_variant_id` identifies the A/B variant of the email that triggered the auto-reply. See [Variant fields](#variant-fields).
* `email_account_id` may be `null`.
* `email_from` is included only when the email account is known.
* `reply_message_url` is included when `includeEmailUrl` is enabled.
* `email_text` is included when `includeEmailText` is enabled and the message body can be parsed.
* `user_name` and `user_email` identify the Reply user who owns the sequence when the event is generated.
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `email_account_connection_lost`
**When:** A connected mailbox can no longer authenticate, such as after an OAuth revocation or password change.
This is an account-level event and does not include contact or sequence information.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "email_account_connection_lost", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"email_account_id": 1,
"email_account_address": "account@example.com"
}
```
### `email_account_error`
**When:** A connected mailbox reports an IMAP or SMTP error, such as an authentication failure, send failure, health check failure, reputation issue, or sending limit.
The event is generated each time the underlying error changes to a non-empty value. Clearing the error does not generate an event.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "email_account_error", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"email_account_id": 1,
"email_account_error": "Sending: SMTP authentication failed",
"email_account_address": "account@example.com"
}
```
### Field notes
* `email_account_error` is a free-form error message.
* Error messages always begin with either:
* `Receiving:` for IMAP-related errors
* `Sending:` for SMTP-related errors
* `email_account_address` may be omitted if the email account can no longer be loaded.
### `contact_finished`
**When:** A contact's participation in a sequence ends.
This can happen when the contact completes the sequence, reaches a terminal status, or is manually finished.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "contact_finished", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"finish_reason": "Replied",
"finished_date": "2026-04-21T09:30:00.000Z",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence" }
}
```
### Field notes
`finish_reason` can be one of:
| Value | Description |
| :- | :- |
| `Replied` | The contact replied to a sequence email. |
| `Bounced` | An email bounced and the contact was removed. |
| `Manual` | A user manually finished the contact. |
| `FinishedAfterXdays` | The contact reached the sequence's maximum duration. |
| `None` | No specific reason was recorded. |
| `Called` | The contact was finished after a phone call. |
| `OptOut` | The contact opted out. |
| `MeetingBooked` | A meeting was booked with the contact. |
| `ForbiddenStep` | The next step was blocked by content guardrails. |
Additional fields:
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id` and `name`. The whole sequence has ended, so this event is not tied to a single step and `step_number` is not included.
### `contact_opted_out`
**When:** A contact opts out of future outreach.
This event is generated when a contact:
* Clicks an unsubscribe link
* Is manually opted out by a user
* Is marked as **Do Not Contact**
All three scenarios generate the same event and payload. The event does not indicate which action caused the opt-out.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "contact_opted_out", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"opt_out_date": "2026-04-21T09:30:00.000Z",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field otes
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `contact_called`
**When:** A call with a contact reaches a final state, such as answered, missed, busy, timed out, or logged manually.
The event is generated after call details have been collected and are ready to deliver.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "contact_called", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"from_number": "+1234567890",
"duration": 60,
"disposition": "Answered",
"resolution": "Positive",
"notes": "Spoke with prospect, scheduled a follow-up.",
"recording_url": "https://example.com/test-call-recording",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `from_number` is the phone number used to place the call.
* `duration` is the call length in seconds. It is `0` for manually logged calls and calls that never connected.
* `disposition` can be:
* `Answered`
* `LoggedManually`
* `NoAnswer`
* `Busy`
* `Fail`
* `resolution` can be one of Reply's built-in values (`Positive`, `ToCall`, `Negative`) or a custom resolution defined by the team. Treat this field as a free-form string.
* `notes` contains any notes entered by the user. It is `null` when no notes were saved.
* `recording_url` contains a recording URL when a recording is available. It is `null` when the call was not recorded.
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number`. `step_number` is `0` for calls not tied to a sequence step.
### `linkedin_connection_request_sent`
**When:** Reply sends a LinkedIn connection request as part of a sequence step.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "linkedin_connection_request_sent", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"sender_linkedin_account_id": 50,
"initial_message": "Test connection request",
"linkedin_message_variant_id": 7310,
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence" }
}
```
### Field notes
* `sender_linkedin_account_id` is the Reply LinkedIn account ID. It is not a LinkedIn public identifier.
* `initial_message` contains the connection request note that was sent. It may be `null` if no note was included.
* `linkedin_message_variant_id` identifies the A/B variant of the connection step. Omitted for connection requests sent outside a sequence. See [Variant fields](#variant-fields).
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id` and `name`. `step_number` is not included for this event.
### `linkedin_connection_request_accepted`
**When:** A LinkedIn connection request previously sent through Reply is accepted.
Only connection requests sent through Reply generate this event.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "linkedin_connection_request_accepted", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"sender_linkedin_account_id": 50,
"linkedin_message_variant_id": 7310,
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `linkedin_message_variant_id` identifies the A/B variant of the connection request that was accepted. Omitted when that request had no variant. See [Variant fields](#variant-fields).
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `linkedin_message_sent`
**When:** Reply sends a LinkedIn message or InMail.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "linkedin_message_sent", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"sender_linkedin_account_id": 50,
"initial_message": "Test message",
"is_inmail": false,
"is_voice_attached": false,
"linkedin_message_id": "test-msg-id",
"linkedin_message_variant_id": 7310,
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `linkedin_message_id` is a Reply-generated message identifier. It is not a LinkedIn message ID.
* `is_inmail` is `true` for InMail messages and `false` for regular LinkedIn messages.
* `is_voice_attached` is `true` when a voice attachment was included.
* `linkedin_message_variant_id` identifies the A/B variant of the message or InMail that was sent. See [Variant fields](#variant-fields).
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number`.
### `linkedin_message_replied`
**When:** A contact replies to a LinkedIn conversation associated with a sequence contact.
Only replies linked to known contacts in Reply generate this event.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "linkedin_message_replied", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"sender_linkedin_account_id": 50,
"linkedin_message_id": "01234567-89ab-cdef-0123-456789abcdef",
"linkedin_message": "Test reply",
"linkedin_message_variant_id": 7310,
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `linkedin_message_id` is a Reply-generated identifier. It is not a LinkedIn message ID.
* `linkedin_message` contains the reply text.
* `linkedin_message_variant_id` identifies the A/B variant of the latest sequence message sent in the conversation before this reply. Omitted when that message has no variant. See [Variant fields](#variant-fields).
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `sequence_fields.name` and `sequence_fields.step_number` are always included.
* `sequence_fields.id` is included only when the contact is currently associated with a sequence.
### `linkedin_reply_categorized`
**When:** Reply assigns a category to a LinkedIn conversation.
A separate event is generated for each affected conversation.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "linkedin_reply_categorized", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"linkedin_thread_id": 1,
"reply_inbox_category_name": "Interested",
"last_reply_date": "2026-04-21T09:30:00.000Z",
"inmail_subject": "Test InMail Subject",
"linkedin_message": "Test reply",
"linkedin_message_variant_id": 7310,
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `reply_inbox_category_name` can be one of:
* `No categories`
* `Interested`
* `Not interested`
* `Do not contact`
* `Not now`
* `Forwarded`
* `Meeting intent`
* LinkedIn categories do not support custom category names.
* `last_reply_date` is included when available.
* `linkedin_message_variant_id` identifies the A/B variant of the latest sequence message sent in the conversation before the categorized reply. Omitted when that message has no variant. See [Variant fields](#variant-fields).
* `inmail_subject` is the subject line of the InMail thread. It is included only for conversations started with an InMail; regular LinkedIn conversations have no subject and the field is omitted. When more than one InMail was sent in the thread, the earliest non-empty subject is used.
* `contact_custom_fields` is included when `includeProspectCustomFields` is enabled.
* `linkedin_message` contains the raw reply text from the contact. It is included only when `includeLinkedInMessageText` is enabled.
* `sequence_fields` includes `id`, `name`, and `step_number` when the conversation is associated with a sequence; it is empty when it is not.
### `autopilot_stopped`
**When:** An evergreen sequence's autopilot is disabled.
This event is generated only for the reasons listed in `autopilot_error_message`.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "autopilot_stopped", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"autopilot_error_message": "the active contacts limit has been reached",
"user_name": "Test User",
"user_email": "user@example.com",
"sequence_owner_name": "Test Owner",
"sequence_owner_email": "owner@example.com",
"sequence_fields": { "id": 200, "name": "Test Sequence" }
}
```
### Field notes
`autopilot_error_message` is one of:
* `the sequence has been deactivated`
* `the active contacts limit has been reached`
* `there are no more contacts/companies matching the filter criteria`
Additional fields:
* `user_name` and `user_email` identify the user who triggered the deactivation.
* `sequence_owner_name` and `sequence_owner_email` identify the sequence owner.
* Owner fields may be omitted if the corresponding user cannot be resolved.
**Team accounts**
If the user who triggered the deactivation is not the sequence owner, Reply generates two events:
* One for the acting user
* One for the sequence owner
Both events contain the same sequence information and error message.
### `linkedin_account_alerts`
**When:** Reply detects a LinkedIn account issue that requires attention.
Examples include a disconnected Sales Navigator account, exhausted InMail credits, or a connection request limit.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "linkedin_account_alerts", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"linkedin_id": 50,
"linkedin_name": "Test LinkedIn Account",
"linkedin_account_alert": "Sales Navigator is disconnected. Please reconnect your LinkedIn account to continue sending InMail steps.",
"team_name": "Test Workspace",
"linkedin_owner_name": "Test User",
"linkedin_owner_email": "owner@example.com"
}
```
### Field notes
* `linkedin_id` and `linkedin_name` identify the LinkedIn account associated with the alert.
* `linkedin_account_alert` contains a human-readable description of the issue.
* `team_name` may be omitted if the workspace has no name.
* `linkedin_owner_name` and `linkedin_owner_email` may be omitted if the account owner cannot be resolved.
### Alert types
| Alert | Description | Re-fire interval |
| :- | :- | :- |
| `SalesNavigatorDisconnected` | Sales Navigator is disconnected. | Up to once every 12 hours |
| `InMailCreditsExhausted` | No InMail credits remain. | Up to once every 24 hours |
| `ConnectionRequestWeeklyLimitReached` | Weekly LinkedIn connection limit reached. | Up to once every 24 hours |
### `contact_replied`
**When it fires:** Each time a sequence contact is recorded as **replied** — Reply detects a reply to a sequence email (`reason: "EmailDetected"`), a sequence LinkedIn message (`reason: "LinkedInDetected"`), or a sequence SMS (`reason: "SmsDetected"`), or a user or the API marks the contact as replied (`reason: "StatusSetManually"`).
This is a channel-agnostic **status** signal: subscribe to it once to learn whenever a contact enters the replied state, regardless of channel, instead of combining `email_replied`, `linkedin_message_replied`, and manual actions yourself. It carries who replied, which sequence/step, when, and why — not the message content. For channel-specific detail (message body, mailbox, sender account) subscribe to the matching per-channel webhook and correlate by `reply_message_id`.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "contact_replied", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"reply_date": "2026-04-21T09:30:00.000Z",
"reply_message_id": "test-reply-msg-id",
"reason": "EmailDetected",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `reason`
* `"EmailDetected"` when Reply detects a reply to a sequence email.
* `"LinkedInDetected"` when Reply detects a reply to a sequence LinkedIn message.
* `"SmsDetected"` when Reply detects a reply to a sequence SMS.
* `"StatusSetManually"` when a user or the API marks the contact as replied.
* `reply_message_id`
* Correlation key to the matching per-channel webhook (`email_replied` / `linkedin_message_replied`): email reply message id, LinkedIn message id, or SMS provider message id. `null` for manually marked replies, which carry no stored message.
* `contact_fields`
* The contact who replied. See the shared [`contact_fields`](#contact_fields) block above for the full field list.
* `sequence_fields`
* Always present; `contact_replied` fires only for contacts in a sequence.
* `contact_custom_fields`
* Included when `includeProspectCustomFields: true`.
* No A/B variant fields. For the variant, use `email_replied` or `linkedin_message_replied`.
### `linkedin_comment_posted`
**When it fires:** Reply posts an AI-generated comment on a contact's most recent LinkedIn post as part of a "Comment on a recent post" sequence step.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "linkedin_comment_posted", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"sender_linkedin_account_id": 50,
"post_url": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890",
"comment_text": "Great point about automation!",
"detected_topic": "ai tools",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `sender_linkedin_account_id`
* ID of the LinkedIn account that posted the comment.
* `post_url`
* URL of the LinkedIn post the comment was posted on.
* `comment_text`
* The text of the posted comment.
* `detected_topic`
* The post's main topic as detected by the AI — a short lowercase phrase, for example `"product launch"`.
* `sequence_fields`
* Always present; the comment step only runs for contacts in a sequence.
* `contact_custom_fields`
* Included when `includeProspectCustomFields: true`.
### `linkedin_comment_skipped`
**When it fires:** A "Comment on a recent post" sequence step skips a contact instead of posting a comment. The step finishes and the contact continues through the sequence; `skip_reason` explains why no comment was posted.
```json theme={null}
{
"event": { "date": "2026-04-21T09:30:00.000Z", "id": "4c1b9e74-5ac3-4b0f-9a60-2a37a9b4a2d1", "type": "linkedin_comment_skipped", "user_id": 1234, "team_id": 100, "subscription_id": 42 },
"sender_linkedin_account_id": 50,
"post_url": "https://www.linkedin.com/feed/update/urn:li:activity:1234567890",
"skip_reason": "AiSkip",
"detected_topic": "politics",
"contact_fields": { "…": "see above" },
"contact_custom_fields": { "…": "see above" },
"sequence_fields": { "id": 200, "name": "Test Sequence", "step_number": 1 }
}
```
### Field notes
* `skip_reason`
* `"NoRecentPosts"` — the contact's latest visible post is older than the step's `skipIfNoPostsInDays` window.
* `"PostsUnavailable"` — no posts could be read for the profile. The person may never have posted, or their posts may not be visible to the LinkedIn account used for the lookup.
* `"ReshareWithoutText"` — the post is a reshare that adds no commentary of its own.
* `"NoPostContent"` — the post has no text and no images, so there is nothing to react to.
* `"CommentingRestricted"` — commenting is not permitted on the post.
* `"AiSkip"` — the AI declined to comment, typically because the post matches one of the step's skip topics.
* `post_url`
* URL of the post the step evaluated. `null` for `"NoRecentPosts"` and `"PostsUnavailable"`, where no post was available.
* `detected_topic`
* The post's main topic as detected by the AI. Populated for `"AiSkip"` (may be empty when no topic was determined); `null` for other reasons.
* `sequence_fields`
* Always present; the comment step only runs for contacts in a sequence.
* `contact_custom_fields`
* Included when `includeProspectCustomFields: true`.
***
## Test webhook deliveries
Once a webhook subscription is configured, you can send a test event to your endpoint:
```text theme={null}
POST /v3/webhooks/{id}/test
```
The test payload matches the event schemas shown on this page and uses predictable placeholder values.
# Webhook events
Source: https://docs.reply.io/webhook-events
Every webhook event the Reply API supports, grouped by category, with what triggers each one and a link to its payload example.
This page lists all webhook event types supported by the Reply API. Each event links to its payload schema on the [Webhook event payloads](/webhook-event-payloads) page.
> [!NOTE]
>
> To create or manage webhook subscriptions, see the [Webhooks API](/api-reference/webhooks/list-webhook-subscriptions). To retrieve supported event types programmatically, use the [List supported event types](/api-reference/webhooks/list-supported-event-types) endpoint.
When [creating](/api-reference/webhooks/create-a-webhook-subscription) or [updating](/api-reference/webhooks/update-a-webhook-subscription) a subscription, pass the event name as the `eventType` value.
## Email engagement
| Event | When it fires | Payload |
| - | - | - |
| `email_sent` | Reply sends an email from a sequence step. | [View](/webhook-event-payloads#email_sent) |
| `email_opened` | A recipient opens a tracked email. | [View](/webhook-event-payloads#email_opened) |
| `email_link_clicked` | A recipient clicks a tracked link in an email. | [View](/webhook-event-payloads#email_link_clicked) |
| `email_replied` | Reply detects an incoming reply to a sequence email, or a direct email reply not tied to a sequence. Fires once per detected reply. | [View](/webhook-event-payloads#email_replied) |
| `reply_categorized` | An email reply is assigned a category automatically or by a user. | [View](/webhook-event-payloads#reply_categorized) |
| `email_bounced` | A sent email bounces or is rejected by the recipient's mail server. | [View](/webhook-event-payloads#email_bounced) |
| `email_auto_reply` | An incoming message is identified as an auto-reply or out-of-office message. | [View](/webhook-event-payloads#email_auto_reply) |
## Email account health
| Event | When it fires | Payload |
| - | - | - |
| `email_account_connection_lost` | A connected mailbox can no longer authenticate, such as after an OAuth revocation or password change. | [View](/webhook-event-payloads#email_account_connection_lost) |
| `email_account_error` | A mailbox reports an IMAP or SMTP error, such as an authentication failure, send failure, or rate limit. | [View](/webhook-event-payloads#email_account_error) |
## LinkedIn
| Event | When it fires | Payload |
| - | - | - |
| `linkedin_connection_request_sent` | Reply sends a LinkedIn connection request on behalf of a user. | [View](/webhook-event-payloads#linkedin_connection_request_sent) |
| `linkedin_connection_request_accepted` | A previously sent LinkedIn connection request is accepted. | [View](/webhook-event-payloads#linkedin_connection_request_accepted) |
| `linkedin_message_sent` | Reply sends a LinkedIn message or InMail. | [View](/webhook-event-payloads#linkedin_message_sent) |
| `linkedin_message_replied` | A contact replies in a LinkedIn conversation. | [View](/webhook-event-payloads#linkedin_message_replied) |
| `linkedin_reply_categorized` | A LinkedIn conversation is assigned a category. | [View](/webhook-event-payloads#linkedin_reply_categorized) |
| `linkedin_account_alerts` | A LinkedIn account requires attention, such as a disconnected Sales Navigator account, usage limits, or low InMail credits. | [View](/webhook-event-payloads#linkedin_account_alerts) |
| `linkedin_comment_posted` | Reply posts an AI-generated comment on a contact's most recent LinkedIn post. | [View](/webhook-event-payloads#linkedin_comment_posted) |
| `linkedin_comment_skipped` | A "Comment on a recent post" step skips a contact instead of posting a comment; the payload carries the reason. | [View](/webhook-event-payloads#linkedin_comment_skipped) |
## Calls
| Event | When it fires | Payload |
| - | - | - |
| `contact_called` | A call with a contact reaches a final status, such as connected, missed, voicemail, or logged. | [View](/webhook-event-payloads#contact_called) |
## Contact lifecycle
| Event | When it fires | Payload |
| - | - | - |
| `contact_replied` | A contact enters the replied state — a reply is detected on any channel (email, LinkedIn, or SMS), or the contact is manually marked as replied. Channel-agnostic status signal. | [View](/webhook-event-payloads#contact_replied) |
| `contact_finished` | A contact completes or exits a sequence. | [View](/webhook-event-payloads#contact_finished) |
| `contact_opted_out` | A contact opts out through an unsubscribe link, manual action, or Do Not Contact setting. | [View](/webhook-event-payloads#contact_opted_out) |
## Sequence automation
| Event | When it fires | Payload |
| - | - | - |
| `autopilot_stopped` | An evergreen sequence's autopilot is disabled. | [View](/webhook-event-payloads#autopilot_stopped) |