Use Case 2: Unified Inbox (Unibox)

Read and manage all email replies across all your mailboxes in one place. Unibox aggregates conversations and provides smart filtering to surface only relevant messages.

Prerequisites

Active workspace with mailboxes (see Mailboxes & Domains)

API key with access to the workspace

How It Works

Unibox provides two modes:

Mode	Description	When to use
Full	All messages from all mailboxes	When you want complete visibility and do your own filtering
Relevant	Filtered — excludes warmup, test, and outbound-only messages	When you only care about real prospect replies

If you have a sequencer connected (Instantly, Smartlead, etc.) or warmup enabled, Unibox automatically excludes those system-generated emails from the "relevant" view.

Check Capabilities

Before querying, check what features are available for your workspace:

GET /threads/capabilities?workspaceId=42

Response:

{
  "inbox": true,
  "outbound": true,
  "syncMode": "incremental",
  "providers": ["opensrs", "maildoso"]
}

List Threads

Fetch conversations (threads) with filtering and pagination:

GET /threads?workspaceId=42

Query Parameters:

Parameter	Type	Default	Description
`workspaceId`	integer	required	Workspace to query
`limit`	integer	50	Results per page (1-200)
`cursor`	string	null	Pagination cursor from previous response
`mailboxId`	string	null	Filter by specific mailbox
`replyIntent`	string	null	Filter by classification (see below)

Response:

{
  "threads": [
    {
      "id": "thr_abc123",
      "external_thread_id": "msg-id@mail.com",
      "subject": "Re: Partnership opportunity",
      "subject_display": "Partnership opportunity",
      "last_message": {
        "from_email": "prospect@company.com",
        "date_received": "2026-03-09T14:30:00Z",
        "body_text": "Hi John, thanks for reaching out..."
      },
      "is_warming": false,
      "is_postmaster": false,
      "message_count": 3,
      "replyIntent": "interested",
      "campaignId": "cmp_xyz789"
    }
  ],
  "next_cursor": "cursor_def456"
}

Pagination

Use cursor-based pagination to iterate through all threads:

Filtering

By mailbox — only show threads for a specific sender:

GET /threads?workspaceId=42&mailboxId=john@cooloutreach.com

By reply intent — only show threads classified as interested:

GET /threads?workspaceId=42&replyIntent=interested

Reply intent values:

Intent	Description
`interested`	Prospect expressed interest
`not_interested`	Prospect declined
`out_of_office`	Auto-reply / OOO
`bounced`	Email bounced
`unsubscribe`	Unsubscribe request
`neutral`	General reply, no clear intent

Incremental Sync

For real-time applications, use sync mode to only fetch new/updated threads:

GET /threads?workspaceId=42&updatedSince=2026-03-09T10:00:00Z

This returns only threads that have new messages since the given timestamp.

Read Thread Messages

Get all messages in a specific thread:

GET /threads/{thread_id}/messages?workspaceId=42

Response:

{
  "replyIntent": "interested",
  "campaignId": "cmp_xyz789",
  "messages": [
    {
      "id": "msg_001",
      "message_id": "<unique-id@mail.com>",
      "from_email": "john@cooloutreach.com",
      "to_emails": ["prospect@company.com"],
      "cc_emails": [],
      "subject": "Partnership opportunity",
      "date_received": "2026-03-08T10:00:00Z",
      "body_text": "Hi, I wanted to reach out about...",
      "body_html": "<p>Hi, I wanted to reach out about...</p>",
      "is_incoming": false,
      "folder": "sent"
    },
    {
      "id": "msg_002",
      "message_id": "<reply-id@company.com>",
      "from_email": "prospect@company.com",
      "to_emails": ["john@cooloutreach.com"],
      "cc_emails": [],
      "subject": "Re: Partnership opportunity",
      "date_received": "2026-03-09T14:30:00Z",
      "body_text": "Hi John, thanks for reaching out...",
      "body_html": "<p>Hi John, thanks for reaching out...</p>",
      "is_incoming": true,
      "folder": "inbox"
    }
  ]
}

Key fields:

is_incoming: true — message received from the prospect

is_incoming: false — message you sent

folder — inbox, sent, spam, etc.

Reply to a Thread

Send a reply within an existing conversation:

POST /threads/{thread_id}/reply?workspaceId=42

Request:

{
  "bodyText": "Thanks for your interest! Let's schedule a call.",
  "bodyHtml": "<p>Thanks for your interest! Let's schedule a call.</p>",
  "fromMailboxAddress": "john@cooloutreach.com"
}

Response:

{
  "status": "queued",
  "message_id": "<reply-msg-id@cooloutreach.com>",
  "operation_id": "op_reply_123"
}

The reply is sent asynchronously. Track delivery status with the operation ID.

Check Send Status

GET /threads/outbound-operations/op_reply_123?workspaceId=42

Send a New Message

Start a new conversation (not a reply to an existing thread):

POST /threads/new?workspaceId=42

Request:

{
  "toAddress": "newprospect@company.com",
  "subject": "Quick question about your product",
  "bodyText": "Hi, I saw your product on...",
  "bodyHtml": "<p>Hi, I saw your product on...</p>",
  "fromMailboxAddress": "john@cooloutreach.com"
}

Response:

{
  "status": "queued",
  "message_id": "<new-msg-id@cooloutreach.com>",
  "thread_id": "thr_new123",
  "operation_id": "op_send_456"
}

Forward a Thread

Forward a conversation to someone else:

POST /threads/{thread_id}/forward?workspaceId=42

Request:

{
  "toAddress": "colleague@company.com",
  "bodyText": "FYI — check this reply from the prospect",
  "fromMailboxAddress": "john@cooloutreach.com"
}

Classify Reply Intent

Manually set or override the AI-assigned reply classification:

PATCH /threads/{thread_id}/reply-intent?workspaceId=42

Request:

{
  "replyIntent": "interested"
}

Complete Python Example: Inbox Monitor

Build a simple inbox monitor that checks for new interested replies:

Filtering Warmup & System Emails

Unibox automatically filters out:

Warmup emails — if warmup is enabled via our platform

Test/system emails — postmaster notifications, delivery reports

Your outbound emails — only shows when they're part of a reply thread

If you connect a third-party warmup provider via Sequencers, those emails are also excluded.

The is_warming and is_postmaster flags on threads let you identify these if you're working with the full (unfiltered) feed.

Mailboxes & Domains — set up the mailboxes that feed into Unibox

Campaigns — replies from campaigns appear in Unibox with campaignId

Use Case 2: Unified Inbox (Unibox)

Prerequisites#

How It Works#

Check Capabilities#

List Threads#

Pagination#

Filtering#

Incremental Sync#

Read Thread Messages#

Reply to a Thread#

Check Send Status#

Send a New Message#

Forward a Thread#

Classify Reply Intent#

Complete Python Example: Inbox Monitor#

Filtering Warmup & System Emails#

Related#

Prerequisites

How It Works

Check Capabilities

List Threads

Pagination

Filtering

Incremental Sync

Read Thread Messages

Reply to a Thread

Check Send Status

Send a New Message

Forward a Thread

Classify Reply Intent

Complete Python Example: Inbox Monitor

Filtering Warmup & System Emails

Related