Help Scout Mailbox API
Agent-ready OpenAPI document · curated by JenticCRMCustomer Supportoauth232 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For Agents
Read and write Help Scout conversations, customers, threads, tags, and webhooks across shared inboxes through an OAuth 2.0 REST API.
Use for: I need to reply to a Help Scout conversation from an external app, I want to create a new support conversation from a contact form, List all open conversations assigned to a specific user, Find all customers with a given email domain
Not supported: 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.
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.
Install Jentic One Beta
Connect the Help Scout Mailbox API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Help Scout Mailbox API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhelpscout.com%2Fhelpscout" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhelpscout.com%2Fhelpscout" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Help Scout Mailbox API.
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
Patterns agents use Help Scout Mailbox API for, with concrete tasks.
★ 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.
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.
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.
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.
Search Jentic for 'tag a help scout conversation', load PUT /conversations/{conversationId}/tags, and execute with the predicted tags.
Key Endpoints
32 endpoints — jentic publishes the only available openapi specification for help scout mailbox api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Help Scout Mailbox API through Jentic.
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.
GET STARTED