Authenticate with a Bearer token obtained via the OAuth 2.0 client credentials flow from /v2/oauth2/token.
List all mailboxes your app has access to with GET /v2/mailboxes — note each mailbox 'id' and 'slug' for subsequent operations.
Retrieve the folders within a specific mailbox with GET /v2/mailboxes/{mailboxId}/folders — folders include system defaults (Mine, Unassigned, Open, etc.) and custom folders.
Create a custom folder within a mailbox with POST /v2/mailboxes/{mailboxId}/folders, supplying a 'name' for the folder.
List conversations in a specific folder by calling GET /v2/conversations with 'mailbox' and 'folder' query params set to the relevant IDs.
Move a conversation to a different folder with PATCH /v2/conversations/{conversationId} using a JSON Patch operation to update the 'folderId' field.
Known gotchas
Folders in Help Scout are mailbox-scoped — a folder created in one mailbox is not visible in another; specify the correct mailboxId in every folder operation.
System default folders (Mine, Unassigned, etc.) cannot be deleted or renamed via the API — only custom folders support create and delete operations.
The conversations list endpoint paginates with 'page' and 'pageSize' params; the default page size is relatively small — set 'pageSize' to the maximum to reduce the number of round trips.
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