Help Scout Conversations API
Create, retrieve, list, update, and delete conversations including threads, attachments, custom fields, tags, and snooze states. Core Mailbox API resource for ticket-style customer interactions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Help Scout Mailbox API
description: >-
Minimal OpenAPI description for Help Scout's Mailbox API v2 covering core
resources for conversations, threads, customers, mailboxes, users, teams,
tags, workflows, and webhooks. Generated from public documentation; verify
before production use.
version: "2.0"
contact:
name: Help Scout Developer Documentation
url: https://developer.helpscout.com/mailbox-api/
x-generated-from: https://developer.helpscout.com/mailbox-api/
x-generated-by: claude-crawl-2026-05-08
servers:
- url: https://api.helpscout.net/v2
description: Help Scout Mailbox API production
security:
- oauth2: []
tags:
- name: Conversations
- name: Threads
- name: Customers
- name: Mailboxes
- name: Users
- name: Teams
- name: Tags
- name: Workflows
- name: Webhooks
paths:
/conversations:
get:
operationId: listConversations
summary: List conversations
tags:
- Conversations
parameters:
- name: page
in: query
schema:
type: integer
- name: status
in: query
schema:
type: string
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
post:
operationId: createConversation
summary: Create conversation
tags:
- Conversations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
responses:
'201':
description: Created
/conversations/{id}:
get:
operationId: getConversation
summary: Get conversation
tags:
- Conversations
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Conversation'
patch:
operationId: updateConversation
summary: Update conversation
tags:
- Conversations
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'204':
description: Updated
delete:
operationId: deleteConversation
summary: Delete conversation
tags:
- Conversations
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'204':
description: Deleted
/conversations/{id}/threads:
post:
operationId: createThread
summary: Create thread
tags:
- Threads
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Thread'
responses:
'201':
description: Created
/customers:
get:
operationId: listCustomers
summary: List customers
tags:
- Customers
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
post:
operationId: createCustomer
summary: Create customer
tags:
- Customers
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
responses:
'201':
description: Created
/customers/{id}:
get:
operationId: getCustomer
summary: Get customer
tags:
- Customers
parameters:
- name: id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
patch:
operationId: updateCustomer
summary: Update customer
tags:
- Customers
parameters:
- name: id
in: path
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'204':
description: Updated
/mailboxes:
get:
operationId: listMailboxes
summary: List mailboxes
tags:
- Mailboxes
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/users:
get:
operationId: listUsers
summary: List users
tags:
- Users
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/teams:
get:
operationId: listTeams
summary: List teams
tags:
- Teams
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/tags:
get:
operationId: listTags
summary: List tags
tags:
- Tags
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/workflows:
get:
operationId: listWorkflows
summary: List workflows
tags:
- Workflows
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/webhooks:
get:
operationId: listWebhooks
summary: List webhooks
tags:
- Webhooks
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
post:
operationId: createWebhook
summary: Create webhook
tags:
- Webhooks
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Webhook'
responses:
'201':
description: Created
components:
securitySchemes:
oauth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://api.helpscout.net/v2/oauth2/token
scopes: {}
schemas:
Conversation:
type: object
properties:
id:
type: integer
subject:
type: string
status:
type: string
type:
type: string
mailboxId:
type: integer
Thread:
type: object
properties:
type:
type: string
text:
type: string
customer:
type: object
Customer:
type: object
properties:
id:
type: integer
firstName:
type: string
lastName:
type: string
emails:
type: array
items:
type: object
Webhook:
type: object
properties:
url:
type: string
events:
type: array
items:
type: string
secret:
type: string