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

Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

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

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.

error
result
status

Input Properties

Every property this tool accepts, from its own tool.iml.

Property	Type	Required	Default	Description
`apiKey`	string	yes	—	DEPRECATED — bind an API Key credential to the task with `credentialName` instead. A key pasted here is stored in the workflow definition in clear and appears in every export of it. Still honoured for workflows built before the change.
`operation`	string	yes	—	One of: list_inboxes, list_conversations, get_conversation, create_conversation, list_customers, get_customer
`conversationId`	string	no	—	Conversation id for get_conversation.
`customerId`	string	no	—	Customer id for get_customer.
`mailboxId`	string	no	—	Inbox (mailbox) id. Filters list_conversations; required for create_conversation.
`status`	string	no	—	Optional status filter for list_conversations: active, open, closed, pending, spam, or all.
`subject`	string	no	—	Subject line for create_conversation.
`text`	string	no	—	Message body (first thread) for create_conversation.
`customerEmail`	string	no	—	Customer email for create_conversation (identifies the customer the conversation is with).
`conversationType`	string	no	—	Optional conversation type for create_conversation: email, chat, or phone (defaults to email).