At a glance
- Availability: Experimental (how to enable).
- Auth: OAuth 2.0.
- Connection: A user authorizes the connection in the provider’s consent screen.
- Docs: https://developer.helpscout.com/mailbox-api/overview/authentication/
Credentials
Set these per environment. See Connect an integration. With a managed OAuth app, Connect works without these variables; set them to use your own OAuth app instead.Setup
- 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.
- 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).
- Copy the app credentials: Copy the App ID into HELPSCOUT_CLIENT_ID and the App Secret into HELPSCOUT_CLIENT_SECRET.
- 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.
- 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.
Tools
| Tool | Access | Description |
|---|---|---|
| List Mailboxes | Read | List Help Scout mailboxes (inboxes) so agents can find a mailbox ID before reading conversations |
| List Conversations | Read | List Help Scout conversations, optionally filtered by mailbox, status, tag, or assignee |
| Get Conversation | Read | Get a Help Scout conversation by ID, including its message threads |
| List Customers | Read | List Help Scout customers, optionally filtered by mailbox, name, or a search query |
| List Users | Read | List Help Scout users (team members) so agents can find user IDs for assignment and reply attribution |
| Add Note | Write | Add an internal note to a conversation - visible to the team only, never emailed to the customer |
| Update Tags | Write | Replace the tag list of a conversation, e.g. to label it during triage. Send the full list: tags omitted from the payload are removed. |
| Reply to Conversation | Write | Send a reply on an existing Help Scout conversation, optionally changing its status |
| Create Conversation | Write | Create a new Help Scout conversation in a mailbox with an initial thread |
Example prompts
- List active Help Scout conversations, group them by topic, and suggest which need attention first.
- Read the latest open Help Scout conversations and draft suggested replies for each.
- Find a Help Scout customer by email and summarize their recent conversations.