Help Scout

This connector uses the Help Scout Mailbox API v2 (developer.helpscout.com/mailbox-api). The Mailbox API is OAuth2-only — there are no Personal Access Tokens (those belong to the separate Docs API).

Setup (one-off):

1. Sign in to Help Scout. Click your avatar (top-right) → Your Profile → My Apps → Create App.
2. Pick any App Name (e.g. "AnythingMCP") and a Redirection URL (placeholder is fine for client_credentials — e.g. https://anythingmcp.com/oauth/callback). Copy the generated App ID and App Secret.
3. Set the two env vars below to those values.

Token lifecycle: the engine performs the OAuth2 client_credentials grant against https://api.helpscout.net/v2/oauth2/token and caches the access token. Help Scout tokens expire after 48h; the engine refreshes proactively 5 min before expiry — no manual rotation needed.

Authentication: every API call sends Authorization: Bearer <auto-issued access_token>.

Conversations are central: Help Scout calls tickets 'conversations'. They live in mailboxes. Each has customer (the requester), assignee, status (active/pending/closed/spam), threads (replies/notes).

Thread types: customer (inbound from customer), reply (outbound public), note (internal), forward (forwarded by agent), phone (logged call), chat (live-chat).

Status values: active, pending (snoozed), closed, spam, open (legacy). Use 'closed' to resolve.

HAL+JSON: responses follow the HAL spec — _embedded contains nested collections, _links for navigation. Pagination via ?page=N&size=M (max 50).

Custom fields: each mailbox has its own custom fields. Set them via customFields array in conversation create/update.

Rate limits: 400 req/min per app. On 429 back off.

Out of scope here: Docs (separate Help Scout Docs API, uses API key + HTTP Basic), Beacon, Reports analytics endpoints, webhooks management.