StateSet API Docs

A conversation layer sits on top of the inbox and outbound tables so a support agent — human or AI — can triage threads instead of individual messages.

Threading

Inbound mail is threaded by RFC headers (Message-ID, In-Reply-To, References) first, falling back to subject plus participants within CONVERSATION_MATCH_WINDOW_DAYS (default 30) when headers are missing.

Triage state

Each conversation carries:

Field	Values
`status`	`open`, `pending`, `closed`, `snoozed` (with `snoozed_until`)
`assignee`	An agent identifier, or unassigned
`tags`	Freeform
`is_read`	Read flag
Summaries	`participants`, `last_message_at`, `message_count`

A new inbound message to a closed or snoozed conversation reopens it to open.

Reopening is unconditional, and it is the behaviour that most often surprises people building automations: an auto-reply, an out-of-office bounce, or a “thanks!” all reopen a conversation an agent had just closed. If you triage on status, filter on last_message_at as well, or the same thread will come back around the queue.

Received attachment bytes are retained up to ATTACHMENT_MAX_BYTES (default 10 MB) and are individually fetchable. Message subject and body are indexed in FTS5 for full-text search.

REST API

Method	Path	Purpose
`GET`	`/v1/conversations`	List conversations
`GET`	`/v1/conversations/:id`	Get one conversation plus its thread
`POST`	`/v1/conversations/:id/reply`	Send a threaded reply
`POST`	`/v1/conversations/:id/status`	Update triage status
`POST`	`/v1/conversations/:id/assign`	Assign or unassign
`POST`	`/v1/conversations/:id/tags`	Add or remove tags
`POST`	`/v1/conversations/:id/read`	Mark read
`GET`	`/v1/messages/search`	Full-text search
`GET`	`/v1/inbox/messages/:id/attachments/:idx`	Fetch an attachment’s bytes

List filters include conversation age and unanswered state.

Triaging a thread

Pull the unanswered conversations for an assignee, read one, and reply on it:

# 1. What is waiting on me?
curl "https://api.stateset.com/v1/conversations?status=open&unanswered=true" \
  --header "Authorization: Bearer $STATESET_API_KEY"

# 2. Read one, with its full thread
curl "https://api.stateset.com/v1/conversations/conv_9Fx2" \
  --header "Authorization: Bearer $STATESET_API_KEY"

# 3. Reply — threading headers are set for you from the last inbound message
curl --request POST "https://api.stateset.com/v1/conversations/conv_9Fx2/reply" \
  --header "Authorization: Bearer $STATESET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "body": "Your replacement shipped this morning — tracking is 1Z999AA10123456784.",
    "from": "support@emails.stateset.com"
  }'

# 4. Close it
curl --request POST "https://api.stateset.com/v1/conversations/conv_9Fx2/status" \
  --header "Authorization: Bearer $STATESET_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"status": "closed"}'

Searching runs against the FTS5 index over subject and body, across both directions of the thread:

curl "https://api.stateset.com/v1/messages/search?q=damaged+in+transit&limit=20" \
  --header "Authorization: Bearer $STATESET_API_KEY"

MCP tools

Tool	Purpose
`list_conversations`	List and filter by status, assignee, tag, participant, unread, or query
`get_conversation`	Fetch one conversation plus its full chronological thread
`reply_to_conversation`	Send a reply, auto-threading off the most recent inbound message
`search_messages`	Full-text search across inbound and outbound messages
`set_conversation_status`	Set status to open/pending/closed/snoozed (`snooze_until` required for snoozed)
`assign_conversation`	Assign or unassign a conversation to an agent
`tag_conversation`	Add and/or remove tags
`mark_conversation_read`	Mark a conversation read
`mark_conversation_unread`	Mark a conversation unread
`fetch_attachment`	Fetch one inbound attachment as base64 by message id and index

A triage_inbox prompt is also served — see MCP server.

Mailboxes

Register addresses on a managed domain, e.g. support@emails.stateset.com. Incoming IMAP mail whose To: or Cc: matches a registered address is routed to that mailbox (inbox.mailbox_id). When MAIL_DOMAIN is set, the send endpoint requires the from address on that domain to be a registered mailbox. Managed-domain onboarding is driven by these settings:

Variable	Default	Purpose
`MAIL_DOMAIN`	unset	Managed mailbox domain
`MAIL_MX_HOST`	`mx.<message-id domain>`	Host customers point their MX record at
`MAIL_SPF_INCLUDE`	`_spf.<message-id domain>`	SPF include customers add to their domain
`MAIL_DMARC_RUA`	unset	Optional DMARC aggregate-report address surfaced in the suggested record
`DNS_VERIFY_INTERVAL_SECS`	`60`	How often the worker re-checks unsettled managed domains
`STALWART_ADMIN_URL` / `STALWART_ADMIN_TOKEN`	unset	MTA admin API for auto-provisioning verified domains. Unset is a logged no-op

Webhooks

Conversation activity is carried on the standard webhook stream. inbox.received events include the conversation, mailbox, domain, and tenant, plus attachment metadata; bounce events carry the recipient. Subscriptions can be scoped to a tenant. See Configuration for subscription management.

Next steps

Configuration

The environment variables referenced above, and how to subscribe to the webhook stream.

MCP server

Drive the same triage loop from an agent, including the triage_inbox prompt.

Last modified on August 29, 2026

Get started

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet iCommerce EDI Engine

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet iCommerce Sandbox Engine

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

Tools

Conversations

Threading

Triage state

REST API

Triaging a thread

MCP tools

Mailboxes

Webhooks

Next steps

Configuration

MCP server

​Threading

​Triage state

​REST API

​Triaging a thread

​MCP tools

​Mailboxes

​Webhooks

​Next steps

Configuration

MCP server

Threading

Triage state

REST API

Triaging a thread

MCP tools

Mailboxes

Webhooks

Next steps