Manage conversations, mailboxes (inboxes), and customers in Help Scout via the Help Scout Mailbox API 2.0.

Help Scout

Manage conversations, mailboxes (inboxes), and customers in Help Scout via the Help Scout Mailbox API 2.0 (https://api.helpscout.net/v2).

This is a standard-library-only InTouch Python tool — no requests, no third-party packages. Response bodies are capped at ~5 MB.

What it does

Branches on an operation input and calls the corresponding Mailbox API 2.0 endpoint, returning the raw JSON payload plus the HTTP status code.

operation	Method & endpoint	Notes
`list_inboxes`	`GET /v2/mailboxes`	Lists the inboxes (mailboxes) you can access.
`list_conversations`	`GET /v2/conversations`	Optional `mailboxId` and `status` filters.
`get_conversation`	`GET /v2/conversations/{conversationId}`	Requires `conversationId`.
`create_conversation`	`POST /v2/conversations`	Requires `subject`, `text`, `customerEmail`, `mailboxId`.
`list_customers`	`GET /v2/customers`	Lists customers.
`get_customer`	`GET /v2/customers/{customerId}`	Requires `customerId`.

apiKey setup (OAuth2 client credentials)

Help Scout's Mailbox API uses OAuth 2.0 — there is no simple single-key auth. This tool uses the client_credentials flow, which is designed for internal integrations and needs no user redirect.

In Help Scout, go to Your Profile → My Apps → Create My App.
Choose an OAuth2 app and copy the Application ID (this is your client_id) and Application Secret (your client_secret).
Pass both to the tool in the single apiKey input, joined with a colon:

apiKey = client_id:client_secret

The tool POSTs these to https://api.helpscout.net/v2/oauth2/token with grant_type=client_credentials, receives a short-lived bearer token (valid ~2 days), and sends it as Authorization: Bearer {token} on each request. The token is fetched fresh on every run, so there is nothing to refresh manually.

Inputs

name	required	description
`apiKey`	yes	`client_id:client_secret` OAuth2 credentials.
`operation`	yes	One of the operations above.
`conversationId`	for `get_conversation`	Conversation id.
`customerId`	for `get_customer`	Customer id.
`mailboxId`	for `create_conversation`; optional filter for `list_conversations`	Inbox (mailbox) id (numeric).
`status`	optional	`list_conversations` filter: `active`, `open`, `closed`, `pending`, `spam`, or `all`.
`subject`	for `create_conversation`	Conversation subject.
`text`	for `create_conversation`	First message body.
`customerEmail`	for `create_conversation`	Email of the customer the conversation is with.
`conversationType`	optional	`email` (default), `chat`, or `phone`.

Outputs

result — the API response body as a JSON string (for create_conversation, which returns 201 with an empty body, this is a small object with the created resource location / resourceId).
status — the HTTP status code as a string.

Examples

List inboxes:

apiKey:    abc123:secretXYZ
operation: list_inboxes

List open conversations in a specific inbox:

apiKey:    abc123:secretXYZ
operation: list_conversations
mailboxId: 12
status:    open

Get a single conversation:

apiKey:         abc123:secretXYZ
operation:      get_conversation
conversationId: 2391938111

Create a conversation (a new email thread) in inbox 12:

apiKey:        abc123:secretXYZ
operation:     create_conversation
mailboxId:     12
subject:       Welcome to support
text:          Hi there — how can we help?
customerEmail: [email protected]

Look up a customer:

apiKey:     abc123:secretXYZ
operation:  get_customer
customerId: 9817234

Notes

HTTPS only; the API is at https://api.helpscout.net/v2.
Access tokens expire after ~2 days; this tool always requests a fresh token, so expiry is transparent.
Grounded in the official docs: https://developer.helpscout.com/mailbox-api/.