Loading list_unibox_threads
list_unibox_threads

Find conversations in a Workspace and obtain their local UUIDs for subsequent tools. Returns a bounded page of thread metadata, default 20 and maximum 100 items, with an opaque nextCursor.
# MCP tool reference

1 callable tools.

Use tools/call at https://mcp.schedulerzero.com/mcp with the exact tool name and arguments below. The /tools/ paths in this view are documentation identifiers, not HTTP endpoints. Request execution is disabled for this reference.

Inputs are shown for personal API keys (bound) and for OAuth/delegated agents. Output schemas describe MCP structuredContent: native objects pass through; arrays, scalars and null use a data wrapper. Text content retains the native JSON result.

[Connect a client](/mcp/connect) · [Authentication and authorization](/authentication) · [Generated auth guide](/auth.md) · [Download tool catalog](/mcp-catalog.json) · [Agent documentation](/llms.txt)

## list_unibox_threads

Find conversations in a Workspace and obtain their local UUIDs for subsequent tools. Returns a bounded page of thread metadata, default 20 and maximum 100 items, with an opaque nextCursor.

Use before list_thread_label_history. Select a conversation using search or folder. showAllEmails defaults to false (managed inbox conversations); set true to include other inbound inbox mail, including manually labeled conversations. Other folders retain their usual rules. Then pass its id as threadId and its organizationId as workspaceId. Pass nextCursor unchanged for another page.

Does not return message bodies or label history. Folder defaults to inbox; choose archived, sent, starred, trash, or warmup when appropriate. Never use providerThreadId as the local threadId.

Scopes: unibox:read

Risk: read; confirmation: none; idempotency: none.

### Input schema (personal API key)

```json
{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "cursor": {
      "$ref": "#/$defs/Cursor"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "search": {
      "$ref": "#/$defs/ShortText"
    },
    "folder": {
      "type": "string",
      "enum": [
        "inbox",
        "sent",
        "archived",
        "starred",
        "warmup",
        "trash"
      ]
    },
    "showAllEmails": {
      "type": "boolean"
    }
  },
  "required": [
    "workspaceId"
  ],
  "patternProperties": {
    "^(?!(?:workspaceId|cursor|limit|search|folder|showAllEmails)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "workspaceId",
      "cursor",
      "limit",
      "search",
      "folder",
      "showAllEmails"
    ]
  },
  "$defs": {
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "ShortText": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    }
  }
}
```

### Input schema (OAuth / delegated agent)

```json
{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "cursor": {
      "$ref": "#/$defs/Cursor"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "search": {
      "$ref": "#/$defs/ShortText"
    },
    "folder": {
      "type": "string",
      "enum": [
        "inbox",
        "sent",
        "archived",
        "starred",
        "warmup",
        "trash"
      ]
    },
    "showAllEmails": {
      "type": "boolean"
    }
  },
  "required": [
    "workspaceId"
  ],
  "patternProperties": {
    "^(?!(?:workspaceId|cursor|limit|search|folder|showAllEmails)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "workspaceId",
      "cursor",
      "limit",
      "search",
      "folder",
      "showAllEmails"
    ]
  },
  "$defs": {
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    },
    "ShortText": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    }
  }
}
```

### Output schema (structuredContent)

```json
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
            "format": "uuid"
          },
          "inboxId": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "organizationId": {
            "type": "string",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
            "format": "uuid"
          },
          "subject": {
            "anyOf": [
              {
                "$ref": "#/$defs/LeadStoredText"
              },
              {
                "type": "null"
              }
            ]
          },
          "snippet": {
            "anyOf": [
              {
                "$ref": "#/$defs/LeadStoredText"
              },
              {
                "type": "null"
              }
            ]
          },
          "contact": {
            "type": "object",
            "properties": {
              "emailAddress": {
                "$ref": "#/$defs/EmailAddress"
              },
              "name": {
                "anyOf": [
                  {
                    "$ref": "#/$defs/LeadStoredText"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "leadId": {
                "anyOf": [
                  {
                    "type": "string",
                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
                    "format": "uuid"
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            },
            "required": [
              "emailAddress",
              "name",
              "leadId"
            ],
            "patternProperties": {
              "^(?!(?:emailAddress|name|leadId)$)[\\s\\S]*$": false
            },
            "additionalProperties": true,
            "propertyNames": {
              "type": "string",
              "enum": [
                "emailAddress",
                "name",
                "leadId"
              ]
            }
          },
          "providerThreadId": {
            "$ref": "#/$defs/OpaqueId"
          },
          "provider": {
            "type": "string",
            "enum": [
              "google_workspace",
              "microsoft_365",
              "other"
            ]
          },
          "lastMessageAt": {
            "anyOf": [
              {
                "$ref": "#/$defs/UtcDateTimeEncoded"
              },
              {
                "type": "null"
              }
            ]
          },
          "messageCount": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "$ref": "#/$defs/ThreadLabelId"
                },
                "name": {
                  "$ref": "#/$defs/ShortText"
                },
                "hexColor": {
                  "$ref": "#/$defs/ShortText"
                },
                "sentiment": {
                  "anyOf": [
                    {
                      "type": "string",
                      "enum": [
                        "positive",
                        "negative",
                        "neutral"
                      ]
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "type": {
                  "type": "string",
                  "enum": [
                    "custom",
                    "default"
                  ]
                }
              },
              "required": [
                "id",
                "name",
                "hexColor",
                "sentiment",
                "type"
              ],
              "patternProperties": {
                "^(?!(?:id|name|hexColor|sentiment|type)$)[\\s\\S]*$": false
              },
              "additionalProperties": true,
              "propertyNames": {
                "type": "string",
                "enum": [
                  "id",
                  "name",
                  "hexColor",
                  "sentiment",
                  "type"
                ]
              }
            }
          },
          "assignees": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "userId": {
                  "type": "string",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
                  "format": "uuid"
                },
                "name": {
                  "anyOf": [
                    {
                      "$ref": "#/$defs/LeadStoredText"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "email": {
                  "$ref": "#/$defs/EmailAddress"
                },
                "image": {
                  "anyOf": [
                    {
                      "$ref": "#/$defs/HttpUrl"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "isFormerMember": {
                  "type": "boolean"
                }
              },
              "required": [
                "userId",
                "name",
                "email",
                "image",
                "isFormerMember"
              ],
              "patternProperties": {
                "^(?!(?:userId|name|email|image|isFormerMember)$)[\\s\\S]*$": false
              },
              "additionalProperties": true,
              "propertyNames": {
                "type": "string",
                "enum": [
                  "userId",
                  "name",
                  "email",
                  "image",
                  "isFormerMember"
                ]
              }
            }
          },
          "campaignId": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "campaignContactId": {
            "anyOf": [
              {
                "type": "string",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "isRead": {
            "type": "boolean"
          },
          "starredAt": {
            "anyOf": [
              {
                "$ref": "#/$defs/UtcDateTimeEncoded"
              },
              {
                "type": "null"
              }
            ]
          },
          "archivedAt": {
            "anyOf": [
              {
                "$ref": "#/$defs/UtcDateTimeEncoded"
              },
              {
                "type": "null"
              }
            ]
          },
          "deletedAt": {
            "anyOf": [
              {
                "$ref": "#/$defs/UtcDateTimeEncoded"
              },
              {
                "type": "null"
              }
            ]
          },
          "folders": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "inbox",
                "sent",
                "archived",
                "starred",
                "warmup",
                "trash"
              ]
            }
          },
          "recentMessages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
                  "format": "uuid"
                },
                "providerInternalMessageId": {
                  "$ref": "#/$defs/OpaqueId"
                },
                "from": {
                  "$ref": "#/$defs/NonEmptyString"
                },
                "to": {
                  "type": "array",
                  "items": {
                    "$ref": "#/$defs/NonEmptyString"
                  }
                },
                "cc": {
                  "type": "array",
                  "items": {
                    "$ref": "#/$defs/NonEmptyString"
                  }
                },
                "subject": {
                  "anyOf": [
                    {
                      "$ref": "#/$defs/LeadStoredText"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "snippet": {
                  "anyOf": [
                    {
                      "$ref": "#/$defs/LeadStoredText"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "receivedAt": {
                  "$ref": "#/$defs/UtcDateTimeEncoded"
                },
                "isRead": {
                  "type": "boolean"
                },
                "isFromInboxSender": {
                  "type": "boolean"
                }
              },
              "required": [
                "id",
                "providerInternalMessageId",
                "from",
                "to",
                "cc",
                "subject",
                "snippet",
                "receivedAt",
                "isRead",
                "isFromInboxSender"
              ],
              "patternProperties": {
                "^(?!(?:id|providerInternalMessageId|from|to|cc|subject|snippet|receivedAt|isRead|isFromInboxSender)$)[\\s\\S]*$": false
              },
              "additionalProperties": true,
              "propertyNames": {
                "type": "string",
                "enum": [
                  "id",
                  "providerInternalMessageId",
                  "from",
                  "to",
                  "cc",
                  "subject",
                  "snippet",
                  "receivedAt",
                  "isRead",
                  "isFromInboxSender"
                ]
              }
            },
            "maxItems": 20
          }
        },
        "required": [
          "id",
          "inboxId",
          "organizationId",
          "subject",
          "snippet",
          "contact",
          "providerThreadId",
          "provider",
          "lastMessageAt",
          "messageCount",
          "labels",
          "assignees",
          "campaignId",
          "campaignContactId",
          "isRead",
          "starredAt",
          "archivedAt",
          "deletedAt",
          "folders"
        ],
        "patternProperties": {
          "^(?!(?:id|inboxId|organizationId|subject|snippet|contact|providerThreadId|provider|lastMessageAt|messageCount|labels|assignees|campaignId|campaignContactId|isRead|starredAt|archivedAt|deletedAt|folders|recentMessages)$)[\\s\\S]*$": false
        },
        "additionalProperties": true,
        "propertyNames": {
          "type": "string",
          "enum": [
            "id",
            "inboxId",
            "organizationId",
            "subject",
            "snippet",
            "contact",
            "providerThreadId",
            "provider",
            "lastMessageAt",
            "messageCount",
            "labels",
            "assignees",
            "campaignId",
            "campaignContactId",
            "isRead",
            "starredAt",
            "archivedAt",
            "deletedAt",
            "folders",
            "recentMessages"
          ]
        }
      }
    },
    "nextCursor": {
      "anyOf": [
        {
          "$ref": "#/$defs/Cursor"
        },
        {
          "type": "null"
        }
      ]
    },
    "total": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "items",
    "nextCursor"
  ],
  "patternProperties": {
    "^(?!(?:items|nextCursor|total)$)[\\s\\S]*$": false
  },
  "additionalProperties": true,
  "propertyNames": {
    "type": "string",
    "enum": [
      "items",
      "nextCursor",
      "total"
    ]
  },
  "$defs": {
    "LeadStoredText": {
      "type": "string",
      "maxLength": 65536
    },
    "EmailAddress": {
      "type": "string",
      "minLength": 3,
      "maxLength": 320,
      "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
    },
    "OpaqueId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 512
    },
    "UtcDateTimeEncoded": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
    },
    "ThreadLabelId": {
      "type": "string",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$",
      "format": "uuid"
    },
    "ShortText": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "HttpUrl": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "pattern": "^https?:\\/\\/[^\\s/$.?#][^\\s]*$"
    },
    "NonEmptyString": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4096
    },
    "Cursor": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048
    }
  }
}
```

### Underlying API operations

- `uniboxThreads.list`: `GET /v1/workspaces/:workspaceId/unibox/threads`
Related MCP tools

browse_unibox_threads
Read a filtered thread list, one thread, its message metadata, one message, its contacts, or a contact photo by choosing an explicit action.
list_thread_label_history
Read a conversation's reply-label history, newest first (default 50 events, limit up to 100). Returns added/removed events with snapshotted label names/colors, source, actor and time; multiple labels may coexist, so this is not an atomic from/to status change. Pass nextCursor unchanged for the next page.
read_unibox_message_body
Read one message's body, with an explicit marker saying whether the HTML was sanitized, left raw, or produced by us.
delete_unibox_threads
Move one conversation, a batch of conversations, or one message to the trash, where retention eventually removes it for good. Select thread, threads, or message explicitly.
download_unibox_attachment
Mint a short-lived download URL for one attachment on one message.
preview_unibox_reply
Resolve reply personalization variables or preview a full draft. A full preview shows the final recipient set after auto-CC/BCC and suppression, and the rendered body. Inbox custom values require inbox:read; built-in sender values remain available without it.
See how this works in Scheduler Zero