A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Help Scout API is how an app or AI agent works with a Help Scout account: listing and reading conversations, replying to a customer or adding an internal note, creating and updating customer records, and pulling support reports. Access is granted through an OAuth token, and because Help Scout grants access at the account level rather than per area, a token can reach everything its associated user can. Help Scout can also push events to a webhook URL when something happens, like a conversation being created or a reply being added.
How an app or AI agent connects to Help Scout determines what it can reach. There is one main route, the Mailbox API, governed by the OAuth token behind it, and a webhook channel for receiving events.
The Mailbox API answers at https://api.helpscout.net/v2 as JSON over HTTPS. It is version 2, continuously updated, and reached with an OAuth bearer token in the Authorization header.
Webhooks deliver the chosen events to a receiver URL, and each delivery is signed with an HMAC signature using the webhook secret so the receiver can confirm it came from Help Scout.
The authorization code flow sends a user through Help Scout's approval screen, then returns an access token and a refresh token. It suits an integration that other Help Scout accounts install, acting on behalf of the user who approved it.
The client credentials flow exchanges an application ID and secret for an access token with no user screen, acting as the user the app is tied to. It suits an internal integration on a single account. The token expires after 2 days and is fetched again with the same credentials.
The Help Scout Mailbox API is split into areas an agent can act on, such as conversations, threads, customers, inboxes, users, and reports. Each area has its own methods, and because access is granted at the account level, a token reaches every area its associated user can.
List, read, create, update, and delete conversations, and set their tags.
List a conversation's threads and add a reply to the customer, an internal note, a chat, or a phone record.
List, read, create, and update the people who contact support.
List and read the shared inboxes, their custom fields, and their folders.
List and read the people on the support team, including the authenticated user.
List the tags used across all inboxes.
List the automated workflows and run a manual workflow on chosen conversations.
Pull the conversations overall report and the happiness ratings report.
List the registered webhooks and create a new one for chosen events.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ConversationsList, read, create, update, and delete conversations, and set their tags.6 | ||||||
| GET | /v2/conversations | List conversations, with optional filtering by inbox, status, tag, assignee, or modification date. | read | — | Current | |
Help Scout has no per-endpoint scopes; the OAuth token reaches every conversation its associated user can see. List Conversations paginates at 25 per page rather than the usual 50. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/conversations/{id} | Get a single conversation by its ID. | read | — | Current | |
Help Scout has no per-endpoint scopes; access follows the token's associated user. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/conversations | Create a conversation, optionally with an initial thread. | write | — | Current | |
Counts as 2 requests against the per-minute rate limit, as all writes do. Returns 201 with a Resource-Id header for the new conversation. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook event convo-createdRate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
| PATCH | /v2/conversations/{id} | Update a conversation's status, assignee, subject, inbox, or custom fields, using a JSON Patch operation. | write | — | Current | |
Takes a JSON Patch body, such as a replace operation on /status or /assignTo. Counts as 2 requests against the per-minute rate limit. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/conversations/{id} | Delete a conversation. | write | — | Current | |
Removes the conversation and its threads. Counts as 2 requests against the per-minute rate limit. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook event convo-deletedRate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
| PUT | /v2/conversations/{id}/tags | Set the tags on a conversation, replacing whatever was there before. | write | — | Current | |
The payload is the complete tag list; any tag not in it is removed, and new tag names are created automatically. Returns 204 No Content. Counts as 2 requests against the rate limit. Acts onconversation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
ThreadsList a conversation's threads and add a reply to the customer, an internal note, a chat, or a phone record.5 | ||||||
| GET | /v2/conversations/{id}/threads | List a conversation's threads, newest first. | read | — | Current | |
Returns 404 if the conversation has been merged into another. Help Scout has no per-endpoint scopes. Acts onthread Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/conversations/{id}/reply | Add a reply thread to a conversation, which sends an email to the customer. | write | — | Current | |
Setting draft true creates an unpublished reply instead of sending. Counts as 2 requests against the rate limit. Returns 201 with a Resource-Id header. Acts onthread Permission (capability)None required VersionAvailable since the API’s base version Webhook event convo-agent-reply-createdRate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
| POST | /v2/conversations/{id}/notes | Add an internal note thread to a conversation, visible to the team but not the customer. | write | — | Current | |
A note is internal and is not emailed to the customer. Counts as 2 requests against the rate limit. Returns 201 with a Resource-Id header. Acts onthread Permission (capability)None required VersionAvailable since the API’s base version Webhook event convo-note-createdRate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
| POST | /v2/conversations/{id}/chats | Add a chat thread to a conversation, recording a chat exchange. | write | — | Current | |
A conversation is capped at 100 threads. Counts as 2 requests against the rate limit. Returns 201 with a Resource-Id header. Acts onthread Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
| POST | /v2/conversations/{id}/phones | Add a phone thread to a conversation, recording a phone call. | write | — | Current | |
A conversation is capped at 100 threads. Counts as 2 requests against the rate limit. Returns 201 with a Resource-Id header. Acts onthread Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
CustomersList, read, create, and update the people who contact support.4 | ||||||
| GET | /v2/customers | List customers, with optional filtering by inbox, name, or modification date. | read | — | Current | |
Returns customer profiles, including email addresses and other contact details. Help Scout has no per-endpoint scopes. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/customers/{id} | Get a single customer by ID. | read | — | Current | |
Returns the full customer profile, including contact details. Help Scout has no per-endpoint scopes. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/customers | Create a customer record. | write | — | Current | |
Counts as 2 requests against the rate limit. Returns 201 with a Resource-Id header for the new customer. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook event customer-createdRate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
| PUT | /v2/customers/{id} | Overwrite a customer record with new data. | write | — | Current | |
PUT replaces the whole record; a PATCH on the same path updates only the fields supplied. A customer with 5000 or more conversations cannot be modified and returns 423 Locked. Counts as 2 requests against the rate limit. Acts oncustomer Permission (capability)None required VersionAvailable since the API’s base version Webhook event customer-updatedRate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
InboxesList and read the shared inboxes, their custom fields, and their folders.4 | ||||||
| GET | /v2/mailboxes | List the inboxes in the account. | read | — | Current | |
The internal path keeps the original mailboxes name, while the product calls these inboxes. Help Scout has no per-endpoint scopes. Acts oninbox Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/mailboxes/{id} | Get a single inbox by ID. | read | — | Current | |
Help Scout has no per-endpoint scopes. Acts oninbox Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/mailboxes/{id}/fields | List the custom fields configured on an inbox. | read | — | Current | |
Custom field definitions are needed to set custom field values on a conversation. Help Scout has no per-endpoint scopes. Acts oninbox Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/mailboxes/{id}/folders | List the folders in an inbox. | read | — | Current | |
Help Scout has no per-endpoint scopes. Acts oninbox Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList and read the people on the support team, including the authenticated user.3 | ||||||
| GET | /v2/users | List the users on the account, with optional filtering by email or inbox. | read | — | Current | |
Returns team member details including email and role, and includes users who have not yet accepted their invitation. Help Scout has no per-endpoint scopes. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/{id} | Get a single user by ID. | read | — | Current | |
Help Scout has no per-endpoint scopes. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/users/me | Get the profile of the authenticated user behind the token. | read | — | Current | |
Identifies which user the token acts as, which determines what the token can reach. Help Scout has no per-endpoint scopes. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList the tags used across all inboxes.1 | ||||||
| GET | /v2/tags | List the tags used across all inboxes, in alphabetical order. | read | — | Current | |
Each tag includes its name, slug, and ticket count. Help Scout has no per-endpoint scopes. Acts ontag Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkflowsList the automated workflows and run a manual workflow on chosen conversations.2 | ||||||
| GET | /v2/workflows | List the workflows, with optional filtering by inbox and by manual or automatic type. | read | — | Current | |
Help Scout has no per-endpoint scopes. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/workflows/{id}/run | Run a manual workflow against a set of conversations. | write | — | Current | |
Applies the workflow's actions to the conversation IDs supplied. Only manual workflows can be run this way. Counts as 2 requests against the rate limit. Acts onworkflow Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
ReportsPull the conversations overall report and the happiness ratings report.2 | ||||||
| GET | /v2/reports/conversations | Get the overall conversations report, with totals over a time range. | read | — | Current | |
Reporting endpoints are available only to Plus and Pro plans. A start and end time range is required, and a second range can be supplied for comparison. Acts onreport Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/reports/happiness/ratings | Get the happiness report's customer satisfaction ratings over a time range. | read | — | Current | |
Reporting endpoints are available only to Plus and Pro plans. Acts onreport Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList the registered webhooks and create a new one for chosen events.2 | ||||||
| GET | /v2/webhooks | List the registered webhooks. | read | — | Current | |
Help Scout has no per-endpoint scopes. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/webhooks | Create a webhook that streams chosen account events to an external URL. | write | — | Current | |
Takes a target URL, an events array, and a secret of up to 40 characters used to sign each delivery. A mailboxIds array can restrict it to chosen inboxes. Counts as 2 requests against the rate limit. Returns 201 with a Resource-Id header. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitCounts as 2 against the per-minute account limit SourceOfficial documentation ↗ | ||||||
Help Scout can notify an app or AI agent when something happens in an account, instead of the app repeatedly asking. Help Scout posts the event payload to a webhook URL that has been registered for the chosen events, signed so the receiver can confirm it came from Help Scout.
| Event | What it signals | Triggered by |
|---|---|---|
convo.created | Fires when a conversation is created, by a customer or by a user. | /v2/conversations |
convo.agent.reply.created | Fires when a user adds a reply to a conversation. | /v2/conversations/{id}/reply |
convo.customer.reply.created | Fires when a customer adds a reply to a conversation. | In-app only |
convo.note.created | Fires when an internal note is added to a conversation. | /v2/conversations/{id}/notes |
convo.assigned | Fires when a conversation is assigned to a user. | In-app only |
convo.status | Fires when a conversation's status changes, such as to active, pending, or closed. | In-app only |
convo.tags | Fires when a conversation's tags change. | In-app only |
convo.deleted | Fires when a conversation is deleted. | /v2/conversations/{id} |
customer.created | Fires when a customer record is created. | /v2/customers |
customer.updated | Fires when a customer record is updated. | /v2/customers/{id} |
satisfaction.ratings | Fires when a customer leaves a satisfaction rating on a conversation. | In-app only |
Help Scout limits how fast an app or AI agent can call, through a per-minute request quota shared across the whole account, where write requests count double.
Help Scout sets one rate limit of 400 requests per minute, shared across the whole account, so every user and integration on the account draws from the same per-minute pool. Write requests, meaning POST, PUT, PATCH, and DELETE, count as 2 against the limit, so an account can make up to 400 reads or 200 writes a minute, or a mix. Each response reports the state in the X-RateLimit-Limit-Minute and X-RateLimit-Remaining-Minute headers, and going over returns 429 Too Many Requests with an X-RateLimit-Retry-After header giving the seconds to wait.
List endpoints use page-based pagination through the page query parameter, returning 50 items per page by default, except List Conversations which returns 25. Each response carries a _page object with size, totalElements, totalPages, and number, and a _links object with self, next, previous, first, and last URLs where they apply, so the next link should be followed rather than the URL built by hand.
Requests and responses are JSON, in the HAL+JSON shape with embedded resources under _embedded and navigation under _links. A single attachment is capped at 10MB, and a conversation can hold at most 100 threads.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request does not meet all requirements, such as a malformed JSON Patch body or a field that fails validation. The body holds a logRef identifier and an _embedded.errors array naming the field at fault. | Read the errors array, correct the named field, and resend. |
| 401 | Not Authorized | The OAuth token is missing or not valid, often because it has expired. Access tokens expire after 2 days. | Fetch a fresh token, with the refresh token on the authorization code flow or the app credentials on the client credentials flow, then retry. |
| 403 | Access Denied | The token is valid but the associated user is denied access to this resource. | Confirm the user behind the token has access to the inbox or resource, then retry. |
| 404 | Not Found | The resource does not exist or was deleted. A conversation that has been merged into another also returns 404 on its thread endpoints. | Confirm the ID is correct and the conversation has not been merged or deleted. |
| 412 | Precondition Failed | The request was well formed and valid, but another condition was not met, such as a conversation already holding the maximum of 100 threads or being locked by company policy. | Resolve the condition, for example by acting on a different conversation, then retry. |
| 423 | Locked | The resource cannot be modified because a limit has been reached, such as updating a customer that has 5000 or more conversations. | Avoid modifying the locked resource; the limit cannot be raised through the API. |
| 429 | Too Many Requests | The per-minute account rate limit was reached. A Retry-After value reports how many seconds to wait. | Wait the number of seconds in the X-RateLimit-Retry-After header, then retry. |
| 500 | Internal Server Error | Something went wrong on the Help Scout side. | Retry after a short pause, and quote the logRef from the response if contacting support. |
Help Scout runs a single, continuously updated version 2 of the Mailbox API, and ships dated changes through its changelog rather than minting new version numbers. New behavior arrives additively, and breaking changes are called out by date.
Version 2 is the single live version of the Mailbox API, reached at https://api.helpscout.net/v2 with OAuth 2.0. It is updated continuously, with no dated version header to pin, and changes ship additively through the changelog. Recent additions include user status endpoints, an Organizations API, cursor-based List Customers v3, and routing configuration, while the occasional breaking change is announced by date.
A dated breaking change required conversation owner IDs to be positive integers greater than 1, rejecting values that earlier versions had accepted. It was released on Monday 24 March 2025.
Snooze operations were added so a conversation can be deferred to a later time through the API, with the next snooze surfaced on the conversation's nextEvent property. It was released on Friday 31 May 2024.
An integration tracks the single live version 2 and watches the changelog for the rare dated breaking change.
Help Scout Mailbox API changelog ↗Bollard AI sits between a team's AI agents and Help Scout. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.