Skip to content

Latest commit

 

History

History
971 lines (740 loc) · 31.2 KB

inbox-api.md

File metadata and controls

971 lines (740 loc) · 31.2 KB

Inbox API Reference

Inbox API commands are namespaced under hs inbox .... Uses OAuth2 client credentials for authentication.

Authentication

The CLI uses HelpScout's OAuth2 client credentials flow. You'll need an App ID and App Secret from your HelpScout app settings (Your Profile > My Apps > Create App).

Interactive login (recommended)

hs inbox auth login

This prompts for your App ID and App Secret, validates them against the API, and stores them securely in your OS keyring.

Non-interactive setup

hs inbox config set --inbox-app-id your-app-id --inbox-app-secret your-app-secret
hs inbox config set --inbox-default-mailbox 12345 --format json
hs inbox config set --inbox-pii-mode customers --inbox-pii-allow-unredacted

Check status

hs inbox auth status

Logout

hs inbox auth logout

Environment variables

Variable Description
HS_INBOX_APP_ID HelpScout App ID (overrides inbox_app_id)
HS_INBOX_APP_SECRET HelpScout App Secret (overrides inbox_app_secret)
HS_FORMAT Output format (overrides format)
HS_INBOX_PII_MODE PII redaction mode (overrides inbox_pii_mode)
HS_INBOX_PII_ALLOW_UNREDACTED Allow --unredacted bypass (overrides inbox_pii_allow_unredacted)
HS_INBOX_PII_SECRET Optional secret salt for deterministic pseudonyms
HS_INBOX_PERMISSIONS Inbox permission policy
HS_NO_UPDATE_CHECK Disable daily update check (1)

Permissions

An allowlist-based permission system that restricts which Inbox operations are permitted. When HS_INBOX_PERMISSIONS is set, only explicitly granted resource:operation pairs are allowed. When unset, everything is allowed (backward compatible).

Format

Comma-separated resource:operation pairs. Wildcards (*) supported.

# Read-only access to conversations and customers
HS_INBOX_PERMISSIONS="conversations:read,customers:read"

# Read-only across all resources
HS_INBOX_PERMISSIONS="*:read"

# Full access to conversations, read-only everything else
HS_INBOX_PERMISSIONS="conversations:*,*:read"

# Unrestricted (explicit)
HS_INBOX_PERMISSIONS="*:*"

Resources: conversations, customers, mailboxes, tags, users, teams, organizations, properties, workflows, webhooks, saved-replies, reports, ratings

Operations: read (list/get), write (create/update/reply/note/run), delete

Source priority: HS_INBOX_PERMISSIONS env var > inbox_permissions in config.yaml > unrestricted default

MCP / LLM setup

Use permissions to restrict what an LLM can do via MCP or shell access:

{
  "env": {
    "HS_INBOX_APP_ID": "...",
    "HS_INBOX_APP_SECRET": "...",
    "HS_INBOX_PERMISSIONS": "conversations:read,customers:read,mailboxes:read,tags:read"
  }
}

Inspect permissions

# Show current policy, source, and per-command allow/deny table
hs inbox permissions

# With a policy set
HS_INBOX_PERMISSIONS="conversations:read" hs inbox permissions

Denied commands

When a command is denied:

Error: permission denied: conversations:write not allowed

Current policy: conversations:read,customers:read
To allow, add conversations:write to HS_INBOX_PERMISSIONS

Commands

Config

# Set one or more config values
hs inbox config set --inbox-app-id xxx --inbox-app-secret yyy
hs inbox config set --inbox-default-mailbox 12345
hs inbox config set --format json
hs inbox config set --inbox-pii-mode customers
hs inbox config set --inbox-pii-allow-unredacted

# Disable/unset PII features explicitly
hs inbox config set --inbox-pii-allow-unredacted=false
hs inbox config set --inbox-pii-mode off --inbox-pii-allow-unredacted=false

# View all config values
hs inbox config get

# View a single value
hs inbox config get inbox-app-id

# Print config file path
hs inbox config path

config set flags

Flag Type Description
--inbox-app-id string HelpScout App ID
--inbox-app-secret string HelpScout App Secret
--inbox-default-mailbox int Default mailbox ID
--format string Output format: table, json, json-full, csv
--inbox-pii-mode string PII redaction mode: off, customers, all
--inbox-pii-allow-unredacted bool Allow per-request --unredacted override
--docs-api-key string HelpScout Docs API key

Mailboxes

# List all mailboxes
hs inbox mailboxes list
hs inbox mb list                 # alias

# Get mailbox details
hs inbox mailboxes get 12345

# Mailbox folders, custom fields, and routing
hs inbox mailboxes folders list 12345
hs inbox mailboxes custom-fields list 12345
hs inbox mailboxes routing get 12345
hs inbox mailboxes routing update 12345 --json '{"enabled":true}'

# JSON output
hs inbox mailboxes list --format json

# Fetch all pages
hs inbox mailboxes list --no-paginate

mailboxes routing update flags

Flag Type Required Description
--json string yes Routing update payload as JSON object

Conversations

# List conversations (default: active, sorted by createdAt desc)
hs inbox conversations list
hs inbox conv list               # alias

# Filter by status
hs inbox conversations list --status active   # default
hs inbox conversations list --status closed
hs inbox conversations list --status pending
hs inbox conversations list --status spam
hs inbox conversations list --status all      # everything

# Filter by mailbox (or set a default: hs inbox config set --inbox-default-mailbox 12345)
hs inbox conversations list --mailbox 12345

# Combine filters — folder, tag, assignee
hs inbox conversations list --folder 12 --tag billing --assigned-to 99

# Filter by modification date
hs inbox conversations list --modified-since "2026-01-01T00:00:00Z"

# Look up by conversation number
hs inbox conversations list --number 23053

# Sort options: createdAt, modifiedAt, number, subject, status, customerEmail,
#               customerName, mailboxid, score, waitingSince
hs inbox conversations list --sort-field modifiedAt --sort-order asc
hs inbox conversations list --sort-field waitingSince --sort-order desc

# Custom field filters (requires --mailbox)
hs inbox conversations list --mailbox 12345 --custom-fields-by-ids "10:foo,11:bar"

# Embed threads in response
hs inbox conversations list --embed threads

# Pagination
hs inbox conversations list --page 2 --per-page 50
hs inbox conversations list --no-paginate   # fetch ALL pages

# Combine flags freely
hs inbox conversations list --mailbox 12345 --status closed --tag billing \
  --sort-field modifiedAt --sort-order desc --format json

conversations list: --query (advanced search)

The --query flag maps directly to the HelpScout search API. It accepts a mini query language with field names, operators, and date ranges. When combined with other flags (e.g. --mailbox), they are ANDed together.

# Free-text search (searches subject + body)
hs inbox conversations list --query "billing issue"

# Search by subject
hs inbox conversations list --query '(subject:"password reset")'
hs inbox conversations list --query '(subject:"shipping" OR subject:"delivery")'

# Search by email (matches to, cc, bcc, and customer profile)
hs inbox conversations list --query '(email:"alice@example.com")'
hs inbox conversations list --query '(email:(alice@example.com OR bob@example.com))'

# Search message body
hs inbox conversations list --query '(body:"error 500")'
hs inbox conversations list --query '(body:"timeout" OR body:"connection refused")'

# Search by tag
hs inbox conversations list --query '(tag:"vip")'
hs inbox conversations list --query '(tag:"urgent" OR tag:"escalated")'

# Search by assignee name (or "Unassigned")
hs inbox conversations list --query '(assigned:"Jane Smith")'
hs inbox conversations list --query '(assigned:"Unassigned")'

# Search by mailbox name or ID
hs inbox conversations list --query '(mailbox:"Support")'
hs inbox conversations list --query '(mailboxid:12345)'

# Search by conversation number or ID
hs inbox conversations list --query '(number:23053)'
hs inbox conversations list --query '(id:100200300)'

# Search by customer ID
hs inbox conversations list --query '(customerIds:500001)'

# Search by replying user IDs
hs inbox conversations list --query '(replyUserIds:(23 OR 45))'

# Has attachments
hs inbox conversations list --query '(attachments:true)'

# Date ranges — createdAt and modifiedAt
hs inbox conversations list --query '(createdAt:[2026-01-01T00:00:00Z TO *])'
hs inbox conversations list --query '(createdAt:[2026-01-01T00:00:00Z TO 2026-01-31T23:59:59Z])'
hs inbox conversations list --query '(modifiedAt:[NOW-1HOUR TO *])'
hs inbox conversations list --query '(modifiedAt:[NOW-7DAY TO *])'
hs inbox conversations list --query '(createdAt:2026-01)'              # month shorthand

# Combine with AND (implicit) and OR
hs inbox conversations list --query '(tag:"billing" AND status:"active")'
hs inbox conversations list --query '(subject:"refund" OR subject:"cancel")'

# Negate with NOT
hs inbox conversations list --query '(NOT tag:"spam")'
hs inbox conversations list --query '(subject:"order" AND NOT assigned:"Unassigned")'

# Combine --query with other flags (ANDed together)
hs inbox conversations list --mailbox 12345 --query '(tag:"vip")'
hs inbox conversations list --status all --query '(email:"alice@example.com")'

Query searchable fields:

Field Example Notes
(free-text) "billing issue" Searches subject + body
subject (subject:"reset password") Case-insensitive phrase match
body (body:"error 500") Message body content
email (email:"alice@example.com") Matches to/cc/bcc/customer emails
tag (tag:"vip") Tag name
assigned (assigned:"Jane") Assignee name, or "Unassigned"
mailbox (mailbox:"Support") Mailbox name
mailboxid (mailboxid:12345) Mailbox ID
number (number:23053) Conversation number
id (id:100200300) Conversation ID
customerIds (customerIds:500001) Customer ID
replyUserIds (replyUserIds:(23 OR 45)) HelpScout user IDs who replied
attachments (attachments:true) Has attachments
createdAt (createdAt:[2026-01-01T00:00:00Z TO *]) Date range or shorthand
modifiedAt (modifiedAt:[NOW-1HOUR TO *]) Date range with relative time

Query operators: AND (implicit default), OR, NOT, [start TO end] (date range, * = open-ended), relative dates (NOW-1HOUR, NOW-7DAY).

Note: Special characters like + in email addresses must be URL-encoded when using the API directly. The CLI handles encoding automatically.

# Full example: complex search with output options
hs inbox conversations list \
  --status all \
  --query '(email:"alice@example.com" AND createdAt:[2026-01-01T00:00:00Z TO *])' \
  --sort-field modifiedAt --sort-order desc \
  --embed threads \
  --format json \
  --no-paginate

# Get conversation details
hs inbox conversations get 67890
hs inbox conversations get 67890 --embed threads

# Create a conversation
hs inbox conversations create \
  --mailbox 12345 \
  --subject "New issue" \
  --customer user@example.com \
  --body "Description of the issue" \
  --type email \
  --status active \
  --tags "bug,urgent" \
  --assign-to 999 \
  --created-at "2026-01-02T15:04:05Z" \
  --imported \
  --auto-reply \
  --field "10=foo" \
  --field "11=bar"

# Update a conversation
hs inbox conversations update 67890 --subject "Updated subject"
hs inbox conversations update 67890 --status closed

# Delete a conversation
hs inbox conversations delete 67890

# Set conversation tags
hs inbox conversations tags set 67890 --tag vip,bug

# Set conversation custom fields
hs inbox conversations fields set 67890 --field "10=foo" --field "11=bar"

# Snooze and unsnooze
hs inbox conversations snooze set 67890 --until "2026-02-20T00:00:00Z"
hs inbox conversations snooze clear 67890

# Upload/list/get/delete conversation attachments
hs inbox conversations attachments upload 67890 --thread-id 123 --file ./invoice.pdf --filename report.pdf --mime-type application/pdf
hs inbox conversations attachments list 67890
hs inbox conversations attachments get 67890 555
hs inbox conversations attachments delete 67890 555

conversations list flags

Flag Type Default Description
--status string active Filter: active, closed, pending, spam, all
--mailbox string config default Filter by mailbox ID (comma-separated for multiple)
--folder string Filter by folder ID
--tag string Filter by tag (comma-separated for multiple)
--assigned-to string Filter by assigned user ID
--modified-since string Filter: conversations modified after timestamp
--number string Look up by conversation number
--sort-field string createdAt Sort by: createdAt, modifiedAt, number, subject, status, customerEmail, customerName, mailboxid, score, waitingSince
--sort-order string desc Sort direction: asc, desc
--custom-fields-by-ids string Custom field filters (id:value,id:value); requires --mailbox
--query string Advanced search query (see query syntax above)
--embed string Embed sub-resources (threads)
--page int 1 Page number
--per-page int 25 Results per page
--no-paginate bool false Fetch all pages

conversations get flags

Flag Type Description
--embed string Embed sub-resources (e.g. threads)

conversations create flags

Flag Type Required Description
--mailbox string yes Mailbox ID
--subject string yes Conversation subject
--customer string yes Customer email
--body string yes Initial message body
--type string Conversation type (default: email)
--status string Initial status (default: active)
--tags strings Comma-separated tags
--assign-to int User ID to assign to
--created-at string Creation timestamp (for imports)
--imported bool Mark as imported
--auto-reply bool Trigger auto-reply
--field strings Custom field <id>=<value> (repeatable)

conversations update flags

Flag Type Description
--subject string New subject
--status string New status

conversations tags set flags

Flag Type Required Description
--tag strings yes Tags to apply (comma-separated)

conversations fields set flags

Flag Type Required Description
--field strings yes Custom field <id>=<value> (repeatable)

conversations snooze set flags

Flag Type Required Description
--until string yes Snooze-until timestamp

conversations attachments upload flags

Flag Type Required Description
--thread-id int yes Thread ID
--file string yes Path to file
--filename string Override filename
--mime-type string Override MIME type

Threads

Threads are subcommands of conversations.

# List threads for a conversation
hs inbox conversations threads list 67890

# Reply to a conversation
hs inbox conversations threads reply 67890 \
  --customer user@example.com \
  --body "Thanks for reaching out!" \
  --status closed \
  --user-id 999 \
  --to "recipient@example.com" \
  --cc "cc@example.com" \
  --bcc "bcc@example.com" \
  --draft \
  --imported \
  --created-at "2026-01-01T00:00:00Z" \
  --type email \
  --attachment-id 1,2

# Add an internal note
hs inbox conversations threads note 67890 \
  --body "Internal note about this ticket" \
  --user-id 999 \
  --status pending \
  --attachment-id 4,5

# Create chat/customer/phone threads
hs inbox conversations threads create-chat 67890 --customer user@example.com --body "Live chat transcript"
hs inbox conversations threads create-customer 67890 --customer user@example.com --body "Customer follow-up" --imported --created-at "2026-01-01T00:00:00Z"
hs inbox conversations threads create-phone 67890 --body "Phone call summary" --attachment-id 3,4

# Update a thread
hs inbox conversations threads update 67890 123 --text "Updated text" --status closed

# Get original source
hs inbox conversations threads source 67890 123 --format json
hs inbox conversations threads source-rfc822 67890 123

threads reply flags

Flag Type Required Description
--customer string yes Customer email
--body string yes Reply body
--status string Set conversation status
--user-id int Author user ID
--to strings Recipient emails
--cc strings CC emails
--bcc strings BCC emails
--draft bool Create as draft
--imported bool Mark as imported
--created-at string Thread creation timestamp
--type string Thread type (e.g. email)
--attachment-id ints Attachment IDs (comma-separated)

threads note flags

Flag Type Required Description
--body string yes Note body
--user-id int Author user ID
--status string Set conversation status
--attachment-id ints Attachment IDs (comma-separated)

threads create-chat / create-customer / create-phone flags

Flag Type Required Description
--body string yes Thread body
--customer string Customer email
--imported bool Mark as imported
--created-at string Thread creation timestamp
--attachment-id ints Attachment IDs (comma-separated)

threads update flags

Flag Type Description
--text string Updated body text
--status string Updated status

Customers

# List customers
hs inbox customers list
hs inbox cust list               # alias

# Search customers by email
hs inbox customers list --query "alice@example.com"

# Filter flags
hs inbox customers list --mailbox 12345 --first-name Alice --last-name Smith
hs inbox customers list --modified-since "2026-01-01T00:00:00Z"
hs inbox customers list --sort-field firstName --sort-order asc

# --query supports a mini query language (same operators as conversations, fewer fields)
hs inbox customers list --query '(firstName:"John")'
hs inbox customers list --query '(firstName:"John" AND lastName:"Appleseed")'
hs inbox customers list --query '(firstName:"John" OR firstName:"Johnny")'
hs inbox customers list --query '(email:"alice@example.com")'
hs inbox customers list --query '(modifiedAt:[2026-01-01T00:00:00Z TO *])'

# Get customer details
hs inbox customers get 11111

# Create a customer
hs inbox customers create \
  --first-name Alice \
  --last-name Smith \
  --email alice@example.com \
  --phone "555-1234" \
  --job-title "Engineer" \
  --location "Paris" \
  --gender female \
  --background "VIP customer" \
  --age "35" \
  --photo-url "https://example.com/photo.jpg" \
  --organization-id 42

# Create with raw JSON (overrides all flags, supports nested objects)
hs inbox customers create \
  --json '{"firstName":"Alice","emails":[{"type":"work","value":"alice@example.com"}]}'

# Update a customer
hs inbox customers update 11111 --first-name "Alicia"

# Overwrite a customer (same flags as create)
hs inbox customers overwrite 11111 --first-name "Alice"

# Delete a customer
hs inbox customers delete 11111

# Delete asynchronously (returns 202)
hs inbox customers delete 11111 --async

customers list flags

Flag Type Description
--query string Search query — supports firstName, lastName, email, modifiedAt fields with AND/OR operators and [TO] date ranges
--mailbox string Filter by mailbox ID
--first-name string Filter by first name
--last-name string Filter by last name
--modified-since string Filter by last-modified timestamp
--sort-field string Sort field
--sort-order string Sort direction
--embed string Embed sub-resources (deprecated)

customers get flags

Flag Type Description
--embed string Embed sub-resources (deprecated)

customers create flags

Also used by overwrite.

Flag Type Required Description
--first-name string yes First name
--last-name string Last name
--email string Email address
--phone string Phone number
--job-title string Job title
--background string Background info
--location string Location
--gender string Gender: male, female, unknown
--age string Age
--photo-url string Photo URL
--organization-id int Organization ID
--json string Raw JSON body (overrides all flags)

customers update flags

Flag Type Description
--first-name string First name
--last-name string Last name
--phone string Phone number

customers delete flags

Flag Type Description
--async bool Delete asynchronously (returns 202)

Tags

# List tags
hs inbox tags list

# Get tag details
hs inbox tags get 123

Users

# List users
hs inbox users list
hs inbox users list --email agent@example.com --mailbox 12345

# Get user details
hs inbox users get 22222
hs inbox users me
hs inbox users delete 22222

# User statuses
hs inbox users status list
hs inbox users status get 22222
hs inbox users status set 22222 --status away
hs inbox users status set 22222 --json '{"status":"away","autoReply":"I am out of office"}'

users list flags

Flag Type Description
--email string Filter by email
--mailbox string Filter by mailbox ID

users status set flags

Flag Type Description
--status string Status value
--json string Full status payload as JSON

Teams

# List teams and team members
hs inbox teams list
hs inbox teams members 77

Organizations

# Organization CRUD
hs inbox organizations list
hs inbox organizations list --query "acme"
hs inbox organizations get 12
hs inbox organizations create --name "Acme" --domain "acme.com"
hs inbox organizations create --json '{"name":"Acme","domains":["acme.com","acme.io"]}'
hs inbox organizations update 12 --name "Acme Intl"
hs inbox organizations delete 12

# Related resources
hs inbox organizations conversations list 12
hs inbox organizations customers list 12

# Organization properties
hs inbox organizations properties list
hs inbox organizations properties get 3
hs inbox organizations properties create --name "Tier" --type "text"
hs inbox organizations properties update 3 --name "Tier 2"
hs inbox organizations properties delete 3

organizations list flags

Flag Type Description
--query string Search query

organizations create flags

Flag Type Required Description
--name string yes Organization name
--domain string Organization domain
--json string Full payload as JSON (overrides flags)

organizations update flags

Flag Type Description
--name string Organization name
--domain string Organization domain
--json string Full payload as JSON (overrides flags)

organizations properties create flags

Flag Type Required Description
--name string yes Property name
--type string Property type
--json string Full payload as JSON (overrides flags)

organizations properties update flags

Flag Type Description
--name string Property name
--type string Property type
--json string Full payload as JSON (overrides flags)

Properties

# Customer property definitions
hs inbox properties customers list
hs inbox properties customers get 5

# Conversation property definitions
hs inbox properties conversations list
hs inbox properties conversations get 8

Ratings

hs inbox ratings get 7

Reports

# One command per Inbox report family
hs inbox reports chats --start 2026-01-01 --end 2026-01-31
hs inbox reports company --start 2026-01-01 --end 2026-01-31
hs inbox reports conversations --start 2026-01-01 --end 2026-01-31
hs inbox reports customers --start 2026-01-01 --end 2026-01-31
hs inbox reports docs --start 2026-01-01 --end 2026-01-31
hs inbox reports email --start 2026-01-01 --end 2026-01-31
hs inbox reports productivity --start 2026-01-01 --end 2026-01-31
hs inbox reports ratings --start 2026-01-01 --end 2026-01-31
hs inbox reports users --start 2026-01-01 --end 2026-01-31

# Filter by mailbox or view
hs inbox reports conversations --start 2026-01-01 --end 2026-01-31 --mailbox 12345 --view tags

# Pass additional query params
hs inbox reports company --param "view=responses" --param "granularity=day"

reports flags

Shared across all report families. For the full set of available params per report family (views, granularity, tags, folders, etc.) see the HelpScout Reports API docs.

Flag Type Description
--start string Report start date/time
--end string Report end date/time
--mailbox string Filter by mailbox ID
--view string Report view filter
--param strings Additional params as key=value (repeatable) — pass-through to the API

Workflows

# List workflows
hs inbox workflows list
hs inbox wf list                 # alias
hs inbox workflows list --mailbox-id 12345 --type manual

# Activate or deactivate a workflow
hs inbox workflows update-status 33333 --status inactive
hs inbox workflows update-status 33333 --status active

# Run a workflow on specific conversations
hs inbox workflows run 33333 --conversation-ids 100,200,300

workflows list flags

Flag Type Description
--mailbox-id int Filter by mailbox ID
--type string Filter by workflow type

workflows update-status flags

Flag Type Required Description
--status string yes Status: active or inactive

workflows run flags

Flag Type Required Description
--conversation-ids strings yes Conversation IDs (comma-separated)

Webhooks

# List webhooks
hs inbox webhooks list
hs inbox wh list                 # alias

# Get webhook details
hs inbox webhooks get 44444

# Create a webhook
hs inbox webhooks create \
  --url https://example.com/hook \
  --events "convo.created,convo.updated" \
  --secret my-webhook-secret \
  --payload-version V2 \
  --mailbox-ids 12345,67890 \
  --notification \
  --label "Primary Hook"

# Update a webhook
hs inbox webhooks update 44444 \
  --url https://example.com/new-hook \
  --payload-version V1 \
  --mailbox-ids 12345 \
  --notification=false

# Delete a webhook
hs inbox webhooks delete 44444

webhooks create flags

Flag Type Required Description
--url string yes Webhook URL
--events strings yes Events to subscribe to (comma-separated)
--secret string yes Webhook secret
--payload-version string Payload version: V1, V2
--mailbox-ids ints Mailbox IDs to scope (comma-separated)
--notification bool Send lightweight notification payloads
--label string Human-readable label

webhooks update flags

Same flags as create, none required.

Saved Replies

# List and get saved replies
hs inbox saved-replies list --mailbox-id 12345
hs inbox saved-replies list --query "welcome"
hs inbox saved-replies get 44

# Create a saved reply
hs inbox saved-replies create --mailbox-id 12345 --name "Welcome" --body "Hi there" --subject "Welcome!" --private

# Update a saved reply
hs inbox saved-replies update 44 --name "Welcome v2" --body "Updated greeting" --subject "Welcome back!"

# Delete
hs inbox saved-replies delete 44

saved-replies list flags

Flag Type Description
--mailbox-id string Filter by mailbox ID
--query string Search query

saved-replies create flags

Flag Type Required Description
--mailbox-id string yes Mailbox ID
--name string yes Reply name
--body string yes Reply body text
--subject string Reply subject
--private bool Mark as private
--json string Full payload as JSON (overrides flags)

saved-replies update flags

Flag Type Description
--mailbox-id string Mailbox ID
--name string Reply name
--body string Reply body text
--subject string Reply subject
--private bool Mark as private
--json string Full payload as JSON (overrides flags)

Tools

Workflow commands that aggregate data from the Inbox API. Namespaced under hs inbox tools ....

# Team overview — conversation counts per agent
hs inbox tools briefing

# Filter by status
hs inbox tools briefing --status pending
hs inbox tools briefing --status all

# Agent summary — list conversations for a specific user
hs inbox tools briefing --assigned-to 531600

# Agent briefing with full thread data
hs inbox tools briefing --assigned-to 531600 --embed threads

# JSON output (clean — no HAL _embedded/_links)
hs inbox tools briefing --assigned-to 531600 --embed threads --format json

briefing flags

Flag Type Description
--assigned-to string Filter by assigned user ID
--status string Conversation status filter (default: active)
--embed string Embed sub-resources (e.g. threads, requires --assigned-to)

briefing output modes

Mode Command Description
Team overview briefing Agent names, emails, conversation counts
Agent summary briefing --assigned-to <id> Conversation list (same columns as conversations list)
Agent + threads briefing --assigned-to <id> --embed threads Conversation list with thread count and last activity

When --format json is used with --embed threads, the output is a JSON array where each conversation has a top-level threads array with full thread data. HAL envelope (_embedded, _links) is stripped from both conversation and thread objects.