canonical: https://jentic.com/apis/helpscout.com/helpscout # Help Scout Mailbox API Jentic publishes the only available OpenAPI specification for Help Scout Mailbox API, keeping it validated and agent-ready. The Help Scout Mailbox API exposes shared inboxes, customer profiles, conversations, and the threads and notes inside each conversation, alongside tags, teams, users, webhooks, workflows, and reporting. It is the integration surface for replicating Help Scout data into a CRM, automating support workflows, or letting an external tool reply to customers from Help Scout. The API is HTTPS-only with OAuth 2.0 authentication and CORS support. ## For AI agents Read and write Help Scout conversations, customers, threads, tags, and webhooks across shared inboxes through an OAuth 2.0 REST API. ## Scope Does not handle live chat widgets, knowledge base article editing, or marketing email - use for shared-inbox support conversations, customers, tags, webhooks, and workflows only. ## Capabilities - List and search conversations across mailboxes with filters for status, assignee, and tags - Create and reply to conversations on behalf of a Help Scout user - Add internal notes to a conversation without notifying the customer - Create, update, and merge customer records - Tag conversations to drive workflow routing - Subscribe to webhooks for new conversations, replies, and tag changes - Trigger Help Scout workflows in response to external events ## Use cases ### External Forms to Help Scout Conversations Public contact forms or in-app feedback widgets can POST a new conversation directly into Help Scout so the support team picks it up in their existing inbox. The conversation includes the customer email, subject, and an initial customer thread, and Help Scout assigns it to the configured mailbox. This avoids forwarding from a generic inbox and keeps the support team in their primary tool. Example prompt: POST /conversations with mailboxId, customer email, subject, and an initial customer thread. ### AI-Assisted Replies in Customer Support An AI-assisted support tool can pull the latest customer thread from a conversation, draft a reply, and post it back via /conversations/{conversationId}/reply once a human has approved it. Internal notes can be used to record the AI suggestion before it is sent, keeping a clear audit trail. This adds drafting throughput without giving the AI direct send authority. Example prompt: GET /conversations/{conversationId}/threads, draft a reply, POST /conversations/{conversationId}/notes for the AI suggestion, then POST /conversations/{conversationId}/reply once approved. ### Replicating Conversations into a CRM Sales and customer success teams that live in a CRM can replicate Help Scout conversations into the CRM by listing conversations on a schedule and resolving each customer to a CRM contact. Tag changes and new threads can be picked up via webhooks to keep the CRM current. This stitches support history into the contact timeline without duplicating data entry. Example prompt: GET /conversations with status=active, GET /customers/{customerId} for each, and write the rolled-up record into the CRM. ### AI Agent Triaging Inbound Mail An AI agent can subscribe to Help Scout new-conversation webhooks via Jentic, pull the conversation and customer, classify the intent, and apply tags or move the conversation to the right mailbox. Jentic stores the OAuth credentials and only exposes the operations the agent needs, so triage logic stays narrow and auditable. This is a high-leverage pattern for support teams handling many low-effort tickets. Example prompt: Search Jentic for 'tag a help scout conversation', load PUT /conversations/{conversationId}/tags, and execute with the predicted tags. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /conversations | List conversations with filters | | POST | /conversations | Create a conversation | | PATCH | /conversations/{conversationId} | Update a conversation | | POST | /conversations/{conversationId}/reply | Reply to a conversation | | POST | /conversations/{conversationId}/notes | Add an internal note to a conversation | | PUT | /conversations/{conversationId}/tags | Update conversation tags | | GET | /customers | List customers | | POST | /customers | Create a customer | ## Key resources - **Conversations** — Read, create, update, and reply to support conversations - **Threads** — Customer messages, replies, and internal notes inside a conversation - **Customers** — Customer profiles and contact details - **Tags** — Tag conversations to drive workflow - **Mailboxes** — Shared inboxes that hold conversations - **Users and Teams** — Help Scout users and assigned teams - **Webhooks** — Subscribe to conversation, customer, and tag events - **Workflows** — Run or list automation workflows ## Why Jentic - **Setup:** Wiring the Help Scout Mailbox API by hand means running its OAuth2 authorization-code flow, refreshing the bearer access token before it expires, and adding the Authorization header on every call. Through Jentic you install once, import the Help Scout Mailbox API from the API Directory, store the OAuth client credentials once, and your agent calls it. - **Permission scoping:** Help Scout puts the conversation id in the URL path (/conversations/{conversationId}/...), so a rule can pin your agent to acting on one conversation. You choose the operations it may call, so replying, adding notes, or changing tags is only included if you add it, while listing conversations and customers stays separate. - **Credential handling:** Your Help Scout OAuth client credentials and refreshed access token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'reply to a Help Scout conversation' or 'create a customer', and Jentic returns the matching Help Scout operation with its input schema including the conversation and thread shapes, so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Zendesk Support API** — Larger help-desk platform with broader ticketing features - **Freshdesk API** — Help-desk and ticketing with extensive automation - **Intercom API** — Conversational customer messaging across web and mobile ## FAQ ### Why is there no official OpenAPI spec for Help Scout Mailbox API? Help Scout publishes developer documentation but no fully validated OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Help Scout Mailbox API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Help Scout Mailbox API use? Help Scout uses OAuth 2.0 with bearer access tokens. Apps obtain tokens via the client credentials or authorization code flow, then send Authorization: Bearer {token} on each call. Tokens are short-lived; refresh them before expiry. Jentic stores client credentials in its vault and refreshes tokens automatically. ### Can I reply to a conversation through the Help Scout API? Yes. POST /conversations/{conversationId}/reply creates a customer-visible reply on behalf of a Help Scout user. POST /conversations/{conversationId}/notes adds an internal note that customers do not see - useful for AI suggestions or handover comments. ### What are the rate limits for the Help Scout Mailbox API? Help Scout enforces per-app rate limits documented in their developer portal - typically a per-minute ceiling per access token. Respect 429 responses and the Retry-After header. For bulk reads, paginate with the Link header rather than tightening loops. ### How do I tag a conversation through Jentic? Search Jentic for 'tag a help scout conversation', load the PUT /conversations/{conversationId}/tags schema, and execute with the conversation ID and the desired tags. Jentic supplies a fresh access token from the vault. ### Can the API subscribe to new-conversation events? Yes. Help Scout supports webhooks for events such as conversation creation, replies, and tag updates. Register a webhook URL via the webhooks resource and verify incoming payloads with the signing secret to filter spoofed callbacks. ### Can I limit what my agent is allowed to do with the Help Scout Mailbox API? Yes. Because you run Jentic One yourself, your own rules decide which Help Scout operations the agent may call, so replying via POST /conversations/{conversationId}/reply, adding internal notes, or changing tags is only available if you include it, while listing conversations and customers stays separate. Since Help Scout puts the conversation id in the URL path, a rule can pin the agent to acting on a single conversation rather than the whole mailbox. Your OAuth client credentials are held by your own instance and injected only at execution time, so the agent never handles the secrets directly.