Help Scout
Search, read, reply to, assign, tag and resolve Help Scout conversations; read and write customers, and read mailboxes, users and tags.
Connect a Help Scout account with an OAuth app to work its mailboxes end to end: search conversations with Help Scout's own query syntax, read a thread with every message's visibility spelled out, send a public reply the customer receives by email, leave an internal note only teammates see, reassign, move between mailboxes, close or reopen, and set tags. Also reads and writes customer records, including the background note agents keep. Replying and noting are separate tools because Help Scout's endpoints are - there is no flag to set wrong.
Connect
| Credential field | Required | Where it comes from |
|---|---|---|
App ID (APP_ID) | Yes | From Manage → Apps → My Apps in Help Scout - your app's identifier. |
App Secret (APP_SECRET) | Yes | The secret generated with the app. Help Scout shows it once, at creation. |
Tools
| Tool | Access | What it does |
|---|---|---|
Who am I (yekar.help-scout.me) | Read | The Help Scout identity this connection acts as. Because the connection authenticates with a client_credentials grant, EVERY action is attributed to the APP rather than to the person who triggered the automation - replies and notes are authored under it, and the app owner's access is the permission ceiling. Call this first to verify a connection. |
List mailboxes (yekar.help-scout.list-mailboxes) | Read | The account's mailboxes, with the ids everything else keys off: Create conversation requires a mailboxId, and List conversations filters by one. Start here when you do not already know which mailbox to work in. total is Help Scout's own count of all mailboxes, not this page. |
List users (yekar.help-scout.list-users) | Read | The account's teammates, with the ids Update conversation takes as assigneeUserId. Note Help Scout returns TEAMS through this same endpoint, distinguished by type - a team is assignable exactly like a person, so check type before describing an assignee as an individual. total is Help Scout's own count, not this page. |
List tags (yekar.help-scout.list-tags) | Read | The tags defined on the account, with Help Scout's own count of the conversations carrying each. Read this before Set conversation tags: that tool sends tag NAMES, and a name Help Scout does not recognise CREATES a new tag rather than failing, so a typo quietly adds a near-duplicate to the account's taxonomy. |
List conversations (yekar.help-scout.list-conversations) | Read | A page of conversations, filterable by mailbox, status, assignee, tag, last change, or Help Scout's own search syntax - subject, preview, status, assignee, customer, tags and dates (no message bodies; use Get conversation for the thread). total is Help Scout's own count of every match rather than this page's length, so it is safe to report as a figure. One default worth knowing: with no status Help Scout returns only ACTIVE conversations, so a closed one you expect to see needs status: "closed" or "all". |
Get conversation (yekar.help-scout.get-conversation) | Read | One conversation in full - status, mailbox, assignee, customer, tags, dates and up to the first 100 threads. EVERY thread carries an explicit visibility: "public" means the customer wrote or received those words, "internal" means it is an agent-only note that must never be repeated back to them, and "event" means it is a state change (status, assignment, tags) rather than prose. Help Scout's own thread count rides the result, so a long conversation reports what was left out instead of looking complete. Note the two identifiers: id is the API's and number is what agents and customers quote. |
List conversation threads (yekar.help-scout.list-conversation-threads) | Read | Page through a conversation's threads - use this instead of Get conversation when a thread is long enough to be worth reading in pieces. EVERY thread carries an explicit visibility: "public" means the customer wrote or received it, "internal" means an agent-only note that must never be quoted back to them, and "event" means a state change carrying no prose. total is Help Scout's own count of all threads on the conversation. |
Create conversation (yekar.help-scout.create-conversation) | Write | Open a new conversation in a mailbox. threadType is a REQUIRED argument with no default, and it is the whole decision: "customer" LOGS the message as though the customer had written in (nothing is sent - this is how you record a phone call or an issue raised elsewhere), while "reply" EMAILS them the opening message. Identify the person with customerId when they already exist: an unrecognised customerEmail creates a new customer, which is how duplicates accumulate. Help Scout answers with no body, so this returns the new conversation id from its Resource-ID header. |
Reply to conversation (yekar.help-scout.reply-to-conversation) | Write | Send a PUBLIC reply on a conversation - the customer receives it by email. This tool is customer-facing by construction: Help Scout's reply endpoint has no private mode, so there is no flag here that could be set wrong. For an agent-only comment use Add conversation note instead. A sent reply cannot be recalled, and re-running this sends a second one, so do not retry it blindly. Help Scout answers a reply with no body, so this returns the new thread's id rather than the conversation - read it back with Get conversation if you need the updated state. |
Add conversation note (yekar.help-scout.add-conversation-note) | Write | Add an INTERNAL note to a conversation - visible to teammates in Help Scout and never sent to the customer. This tool is internal by construction: Help Scout's note endpoint has no public mode, so use Reply to conversation when you actually want the customer to receive something. Help Scout answers with no body, so this returns the new thread's id rather than the conversation. |
Update conversation (yekar.help-scout.update-conversation) | Write | Change a conversation's status, assignee, subject or mailbox. Help Scout's API applies ONE change per request, so this issues one request per field you set and they are NOT atomic: if a later one fails, the earlier ones stand, and the error names exactly which had already been applied. The result lists the changes that reached Help Scout. This does not notify the customer - use Reply to conversation for that. |
Set conversation tags (yekar.help-scout.set-conversation-tags) | Write | Set a conversation's tags. This REPLACES the whole list rather than adding to it - that is Help Scout's own behaviour, so read the conversation's current tags first and send them back along with your additions, or they are removed. Tags are sent by NAME, and a name Help Scout does not recognise creates a new tag on the account rather than failing, so resolve against List tags before inventing one. |
List customers (yekar.help-scout.list-customers) | Read | Find customers by email, name or Help Scout's search syntax. Note the data model: a Help Scout customer holds MANY email addresses, so searching by one address returns the whole person and their other addresses come back in emails - the first is the primary. total is Help Scout's own count of every match rather than this page's length. |
Get customer (yekar.help-scout.get-customer) | Read | One customer in full - name, every email address and phone number on the record, job title, organization, location and the background note agents keep on them. That background note is often the context a good reply depends on. Use List customers to find someone by email. |
Create customer (yekar.help-scout.create-customer) | Write | Create a customer record. Search with List customers first: this does not deduplicate, and Help Scout keeps many addresses per person, so a second record for the same human splits their history across two profiles. background is an internal note agents see and the customer never does. Help Scout answers with no body, so this returns the new id from its Resource-ID header. |
Update customer (yekar.help-scout.update-customer) | Write | Update a customer's profile fields - name, job title, organization, location, and the internal background note agents see. Only the fields you set are sent, so an untouched field is never blanked. Email addresses and phone numbers are separate sub-resources in Help Scout and are NOT changed here; this tool deliberately does not touch them rather than appearing to and silently doing nothing. Help Scout answers with no body, so this reports which fields were sent. |
Notes
- In Help Scout go to Manage → Apps → My Apps → Create App, name it (e.g. "Yekar.AI"), and create it. Copy the App ID and App Secret; the secret is shown once.
- Paste both here. Help Scout's Mailbox API has no API-key auth - a bearer minted from these two values is the only way in, and this integration mints one per call and never stores it.
- EVERY action is attributed to the app, not to the person who triggered the automation: replies and notes are authored under it, and the app's access is the permission ceiling. Bind automations using this integration as a service connection.
- Call Who am I to confirm the connection, then List mailboxes - a mailbox id is required to create a conversation and is the usual filter for listing them.
- Replying and noting are different tools with different audiences: Reply to conversation EMAILS the customer and cannot be recalled, while Add conversation note is internal by construction and never reaches them.
- Two behaviours worth knowing before you write: Set conversation tags REPLACES the whole tag list (send the full set you want), and Update conversation applies one change per request, so a multi-field update is not atomic.