Obtain an OAuth 2.0 access token via the client credentials flow: POST to https://api.helpscout.net/v2/oauth2/token with your App ID as client_id, App Secret as client_secret, and grant_type=client_credentials.
Pass the token as 'Bearer YOUR_TOKEN' in the Authorization header on all subsequent requests.
Fetch happiness (CSAT) report data from GET /v2/reports/happiness, supplying 'start' and 'end' date-time query params (ISO 8601) and optionally 'mailbox' to scope to a specific inbox.
The response includes aggregate happiness scores and rating counts — parse 'happinessScore', 'totalRatings', and the breakdown by rating type.
For per-conversation rating detail, call GET /v2/reports/happiness/ratings to retrieve individual rating records including 'rating', 'ratingCustomer' name, 'conversationId', and timestamps.
Paginate through individual ratings using 'page' and 'rows' query params and iterate until the response 'page' count is exhausted.
Known gotchas
Help Scout OAuth tokens expire — cache the token and refresh using the client credentials flow before it expires rather than re-authenticating on every request.
The happiness report endpoint aggregates data with a reporting lag of up to a few hours; very recent ratings may not appear immediately.
Filtering by 'mailbox' requires the numeric mailbox ID, not the inbox name — fetch mailbox IDs from GET /v2/mailboxes before constructing report queries.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp