> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Help Scout

> Read Help Scout mailboxes, conversations, and customers, and reply to or create support conversations

## At a glance

* **Availability**: Experimental ([how to enable](/cloud/integrations)).
* **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/](https://developer.helpscout.com/mailbox-api/overview/authentication/)

## Credentials

Set these per environment. See [Connect an integration](/cloud/integrations).

With a managed OAuth app, Connect works without these variables; set them to use your own OAuth app instead.

| Variable                  | Required | Description                                                                                                              |
| ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `HELPSCOUT_CLIENT_ID`     | Yes      | Help Scout OAuth App ID (from My Apps) [Docs](https://developer.helpscout.com/mailbox-api/overview/authentication/).     |
| `HELPSCOUT_CLIENT_SECRET` | Yes      | Help Scout OAuth App Secret (from My Apps) [Docs](https://developer.helpscout.com/mailbox-api/overview/authentication/). |

## Setup

1. **Create a Help Scout account**: Sign up at [https://www.helpscout.com/](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/](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.

* 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: [https://developer.helpscout.com/mailbox-api/](https://developer.helpscout.com/mailbox-api/)

## 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.