Skip to main content

​
At a glance

  • Availability: Experimental (how to enable).
  • Authentication: OAuth 2.0.
  • Connection: A user authorizes the connection in the provider’s consent screen.
  • Provider documentation: Authentication reference.

​
Credentials

Set these per environment. See Connect an integration. These variables are required only when you supply your own OAuth app. If a managed app is available, you can connect without setting them. Provider permissions and consent still apply.

​
Setup

  1. Create a Help Scout account: Sign up at https://www.helpscout.com/ - a free trial works for development. Create at least one Inbox (mailbox) so the API has data to return.
  2. Create an OAuth app: In Help Scout, go to Your Profile > My Apps (sign in at https://secure.helpscout.net/) and choose Create My App. Set the Redirection URL to your app’s callback URL (the /oauth/callback/help-scout path on your deployment).
  3. Copy the app credentials: Copy the App ID into HELPSCOUT_CLIENT_ID and the App Secret into HELPSCOUT_CLIENT_SECRET.
  4. Connect and authorize: Complete the OAuth flow with a Help Scout user who has access to the mailboxes you want agents to read. Access is granted at the app level - the Mailbox API does not use granular scopes.

​
Provider notes

  • Access tokens expire after 2 days (172,800 seconds); the refresh token returned by the Authorization Code flow is used to obtain new ones automatically.
  • The Mailbox API has no scope system - the connected user’s permissions determine which mailboxes and conversations are visible.
  • List endpoints return HAL+JSON with results under _embedded and page-based pagination via the page query parameter.
  • Replies sent via the API are delivered to the customer as real emails - use the draft flag while testing.
Provider API reference.

​
Tools

​
Verify the connection

Call a read tool such as help-scout__list_mailboxes with arguments for your account. Confirm that the result comes from the intended account or workspace before enabling write tools.