Help Scout API Guide: OAuth, Rate Limits, Webhooks and MCP

The Help Scout API you want is the Inbox API 2.0, and it starts on the Standard plan. Free has no API access at all. Each account gets 200 requests a minute on Standard, 400 on Plus and 800 on Pro, shared by every user, and each write counts as two.^[1] Reporting endpoints need Plus or Pro. Around that core sit webhooks, a Chat API, a separate Docs API, sidebar apps, Beacon's JavaScript API and a read-only MCP connector for AI agents. Our verdict: the platform is well documented and stable. Choose the plan before the code, because two of the most useful pieces, the reporting endpoints and the MCP report tools, are missing on Standard.

Which plan opens which part of the platform

Before writing a line of code, check the plan your account is on. The gates below come from Help Scout's pricing matrix and developer pages, and they decide whether a project is possible at all, not only how fast it runs. Standard costs $25 per user per month billed annually or $30 per user per month billed monthly. Every person with a login is a billable user, so totals grow with headcount; our Help Scout pricing guide has the full arithmetic.

The table hides one trap. Reporting is the piece most teams want to pipe into a BI tool, and on Standard it is simply absent from both the API and the MCP connector. If dashboards outside Help Scout are the goal, Plus is the real entry point. Light users, which exist only on Plus and Pro, cannot use the API, apps or MCP, so every integration runs under a full user.

Step 1: get an OAuth token that keeps working

The Inbox API lives at api.helpscout.net/v2, accepts HTTPS only and authenticates with OAuth 2.0. You start by creating an OAuth2 application under Your Profile, then My apps. Two flows exist. Client Credentials is meant for internal integrations, while Authorization Code is meant for integrations that other Help Scout accounts will install, and it needs a redirection URL.^[2] Client Credentials must belong to an active, invited user, or the API answers 401. Because every login is billed, a dedicated integration user is a paid seat.

Access tokens last two days, signalled by an expires_in of 172800 seconds, and an expired token returns 401. Only the Authorization Code flow hands back a refresh token; a Client Credentials job simply requests a new token. Store tokens in a variable-length field. Help Scout warns their length changes over time. Two 403 errors catch new projects. The calling user needs the Access API permission, set by an admin under user permissions. And a 403 Payment missing appears when billing details are missing or expired, even with a valid token.

Step 2: make calls that stay under the rate limit

Responses come back as HAL+JSON with embedded resources and page links, except Reports endpoints, which return plain JSON. Lists page at 50 items, while List Conversations pages at 25. Dates go both ways in ISO 8601, in UTC. For updates, PATCH applies a JSON Patch, while PUT overwrites the whole entity and treats unset fields as null. That difference deletes data quietly. Use PATCH unless you mean it.

The rate limit is per account, not per user, so a nightly sync job and a sidebar app draw from the same bucket. Writes (POST, PUT, PATCH, DELETE) and Search Conversations v3 calls each count as two requests. By our arithmetic, that caps pure writes at 100 a minute on Standard, 200 on Plus and 400 on Pro. Read the X-RateLimit-Remaining-Minute header as you go, and when a 429 arrives, wait the seconds in X-RateLimit-Retry-After. A 504 means an internal timeout and is safe to retry after a short delay. Rate-limit add-ons exist, but Help Scout publishes no price for them.

The newer v3 endpoints

Help Scout promises no breaking changes to Inbox API 2.0; a breaking change would ship as a new endpoint with a version prefix. That is how the v3 endpoints arrived. List Conversations v3 (September 2026) uses cursor pagination and typed filters, always sorts newest first and rejects the old query parameter with a 400. Search Conversations v3 (October 2026) takes one query of up to 500 characters and, unlike the list endpoint, has no default status, so it matches every status unless you say otherwise. List Customers v3 returns customers across all Inboxes.

A few hard limits belong in your error handling. A customer with more than 5,000 conversations is locked for updates and returns 423. The GDPR delete endpoint works only for customers with 100 or fewer conversations. A conversation created through the API stays under 100 threads, and attachments must be Base64 and under 10 MB. Ignore old tutorials built on Mailbox API 1.0, which was deprecated on November 20, 2019. The developer llms.txt still quotes its 200-a-minute limit with 12 writes per 5 seconds; that figure is legacy.

Step 3: let webhooks push changes to you

Polling burns the shared limit, so most integrations should listen instead. Webhooks are set up in Settings, under Apps, then the Webhooks app, on Standard and above, and an account can hold several. Events cover conversations (created, assigned, status, moved, merged, tags, custom fields, replies and notes), customers, satisfaction ratings, tags, organizations, Message survey responses, user status changes and Beacon chats. A convo.ai-answers.created event fires when Scout (formerly AI Answers), billed per resolution on Standard, Plus and Pro, creates a conversation. Since July 2025 a webhook can be filtered by Inbox, but customer.created always fires account-wide.

Each request carries an X-HelpScout-Event header and an X-HelpScout-Signature header. Verify it by computing an HMAC-SHA1 of the raw body with your secret key and comparing the base64 result.^[3] Any 2xx counts as success. A 410 removes the webhook. Anything else is a failure, retried up to 10 times with growing delays and then discarded; after ten discarded events the webhook is deactivated, so a long outage on your side silently ends the feed. Set payloadVersion to V3 (available since May 20, 2026), which marks AI agents as system users; V2 is still the default but deprecated.

Chat, Docs, sidebar apps and Beacon

Chat API and Docs API

The Chat API works on live Beacon chats while they are open: get a chat and its events, accept, add a message or note, assign, unassign, update tags and end. A chat becomes a conversation only when it ends, so the Inbox API has nothing to address before that. Messages sent through it show the name of the user who created the token, so a bot answering chats should run under a user whose name you are happy for visitors to see.

The Docs API is a separate system at docsapi.helpscout.net, version 1, JSON only. Each user has a personal API key under Your Profile, sent through HTTP Basic auth, and it appears only if an admin grants the Docs permission. Limits run per account per 10 minutes: 2,000 requests with one Docs site, 3,000 with two, 4,000 with three or more, and clicks in the Docs admin count too. It is the only way to configure Restricted Docs on Plus and Pro, which signs visitors in with a JWT signed HS512 using the site's shared secret.

Sidebar apps and Beacon

Custom sidebar apps run in an iframe on any paid plan, built with the JavaScript SDK (@helpscout/javascript-sdk) and the React UI Kit (@helpscout/ui-kit). Each callback carries an X-HelpScout-Signature query parameter to check with an HMAC of your app secret. On the customer side, Beacon's JavaScript API covers init, identify, prefill, suggest and navigate, and Secure Mode signs the visitor's email with HMAC-SHA256 on your server, never in the app. Android and iOS SDKs bring Beacon into mobile apps; our Beacon setup guide walks through the widget itself.

Plug an AI agent in through the MCP server

The Help Scout MCP connector lets Claude, ChatGPT, Cursor or an in-house agent read your account. Add the remote endpoint mcp.helpscout.net/mcp as a custom connector; Help Scout is not yet in Claude's connector directory. It works on Standard, Plus and Pro, any plan with API access, while the report tools need Plus or Pro.^[4] It reaches conversations, customers, Inboxes, saved replies, users and teams, workflows (view only), reports and Docs, though Docs tools need a separate Docs API key.

New connections are read-only. The agent cannot create, send, edit or delete anything, and write actions are on the roadmap with no date. Each person connects with their own OAuth credentials and sees only what they may see. There is no account-wide off switch: an admin blocks someone by removing the Access API permission or making them a light user. After a disconnect, access tokens stay valid up to 2 hours and refresh tokens up to 30 days, unless you deactivate the user.

Two last rules shape every build. Help Scout's Terms limit API use to internal business purposes tied to your subscription. And the only official library is the PHP client; the Node.js, .NET, Ruby and Python wrappers and the hscli CLI are community projects Help Scout does not support. Our AI playbook covers Scout and the agent-side features.

The bottom line

Help Scout's developer platform is stable, documented and sensibly split: OAuth Inbox API, signed webhooks, separate Chat and Docs APIs, and a read-only MCP door for AI tools. The constraints are plan gates, not code. Standard gives you 200 requests a minute and no reporting endpoints, so analytics projects belong on Plus. Budget writes at two requests each, prefer webhooks to polling, and watch the webhook deactivation rule.