Manage Threads and Drafts

Create drafts, send them, and navigate thread history across scopes.

View as Markdown

Use drafts when you need a save-before-send workflow, then use thread routes to inspect or clean up conversation history.

Draft Lifecycle

Create a draft in an inbox:

curl -X POST "$API_URL/agent/v0/inboxes/{inbox_id}/drafts" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["recipient@example.com"],
    "subject": "Draft subject",
    "text": "Draft body"
  }'

Send the draft later:

curl -X POST "$API_URL/agent/v0/inboxes/{inbox_id}/drafts/{draft_id}/send" \
  -H "Authorization: Bearer $API_KEY"

This returns message_id and thread_id, and the draft is removed after a successful send.

Thread Retrieval

You can list and inspect threads at three scopes:

  • Global tenant scope: /agent/v0/threads, /agent/v0/threads/{thread_id}
  • Inbox scope: /agent/v0/inboxes/{inbox_id}/threads, /agent/v0/inboxes/{inbox_id}/threads/{thread_id}
  • Pod scope: /agent/v0/pods/{pod_id}/threads, /agent/v0/pods/{pod_id}/threads/{thread_id}

Use limit and page_token for pagination.

Deleting Threads

Thread deletion routes remove all messages in the thread for the selected scope:

  • /agent/v0/threads/{thread_id}
  • /agent/v0/inboxes/{inbox_id}/threads/{thread_id}
  • /agent/v0/pods/{pod_id}/threads/{thread_id}

Use the narrowest scope possible to avoid deleting data outside the intended boundary.