Obtain an OAuth 2.0 access token via POST to https://api.helpscout.net/v2/oauth2/token using client_credentials grant with your App ID and App Secret
POST to /v2/conversations with mailboxId, subject, customer (id or email), type (email or chat), and an initial thread body to create the conversation
GET /v2/mailboxes/{mailboxId}/fields to retrieve the list of custom field definitions and their IDs for the target inbox
PATCH /v2/conversations/{conversationId}/fields with the full array of fieldId/value pairs to set custom field values — the entire fields array must be sent; omitting an existing field removes it
POST /v2/conversations/{conversationId}/tags with tags array to attach one or more tags by name
GET /v2/conversations/{conversationId}/threads to retrieve all threads (replies, notes, phone logs) in the conversation with pagination via page parameter
Known gotchas
The PATCH custom fields endpoint requires sending the complete fields array for the conversation — a partial update omitting existing fields will silently delete those field values, not preserve them
OAuth tokens expire after 2 hours; build token refresh logic using the refresh_token grant before making API calls, or catch 401 responses and re-authenticate
Free-text custom fields searched via the API must use fieldId:value format in the query string; the search index for custom fields may lag real-time updates by a few minutes
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