@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/inbox.md

@@ -0,0 +1,1067 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.inbox`: Inbox
+
+22 operations (12 read, 5 write, 1 destructive, 4 external).
+
+6 of these also have a hand-written method (`g8.inbox`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [inbox.d.ts](inbox.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`assignReply`](#op-assignreply) ★ | `POST /api/v1/inbox/{reply_id}/assign` | external | `inbox:run` | Assign Reply |
+| [`autoTagInboxChat`](#op-autotaginboxchat) | `POST /api/v1/inbox/chats/auto-tag` | write | `inbox:write` | Auto Tag Inbox Chat |
+| [`createUniversalActivitySavedView`](#op-createuniversalactivitysavedview) | `POST /api/v1/universal-activity/save-view` | write | `inbox:write` | Create Universal Activity Saved View |
+| [`discardInboxEmailDraft`](#op-discardinboxemaildraft) | `DELETE /api/v1/inbox/emails/{email_id}/draft` | destructive | `inbox:delete` | Discard Inbox Email Draft |
+| [`getDraft`](#op-getdraft) ★ | `GET /api/v1/inbox/{reply_id}/draft` | read | `inbox:read` | Get Draft |
+| [`getInboxChat`](#op-getinboxchat) | `GET /api/v1/inbox/chats/{chat_id}` | read | `inbox:read` | Get Inbox Chat |
+| [`getInboxEmail`](#op-getinboxemail) | `GET /api/v1/inbox/emails/{email_id}` | read | `inbox:read` | Get Inbox Email |
+| [`getReply`](#op-getreply) ★ | `GET /api/v1/inbox/{reply_id}` | read | `inbox:read` | Get Reply |
+| [`getUniversalActivityMetrics`](#op-getuniversalactivitymetrics) | `GET /api/v1/universal-activity/metrics` | read | `inbox:read` | Get Universal Activity Metrics |
+| [`getUniversalActivityPreview`](#op-getuniversalactivitypreview) | `GET /api/v1/universal-activity/preview/{event_id}` | read | `inbox:read` | Get Universal Activity Preview |
+| [`hotContacts`](#op-hotcontacts) | `GET /api/v1/inbox/hot-contacts` | read | `inbox:read` | Hot Contacts |
+| [`listInbox`](#op-listinbox) ★ | `GET /api/v1/inbox` | read | `inbox:read` | List Inbox |
+| [`listUniversalActivityQueues`](#op-listuniversalactivityqueues) | `GET /api/v1/universal-activity/queues` | read | `inbox:read` | List Universal Activity Queues |
+| [`listUniversalActivitySavedViews`](#op-listuniversalactivitysavedviews) | `GET /api/v1/universal-activity/saved-views` | read | `inbox:read` | List Universal Activity Saved Views |
+| [`markInboxChatViewed`](#op-markinboxchatviewed) | `POST /api/v1/inbox/chats/{chat_id}/mark-viewed` | write | `inbox:write` | Mark Inbox Chat Viewed |
+| [`queryUniversalActivity`](#op-queryuniversalactivity) | `POST /api/v1/universal-activity` | write | `inbox:write` | Query Universal Activity |
+| [`searchInboxChats`](#op-searchinboxchats) | `POST /api/v1/inbox/chats/search` | read | `inbox:read` | Search Inbox Chats |
+| [`searchInboxEmails`](#op-searchinboxemails) | `POST /api/v1/inbox/emails/search` | read | `inbox:read` | Search Inbox Emails |
+| [`sendInboxEmail`](#op-sendinboxemail) | `POST /api/v1/inbox/emails/{email_id}/send` | external | `inbox:run` | Send Inbox Email |
+| [`sendReply`](#op-sendreply) ★ | `POST /api/v1/inbox/{reply_id}/send` | external | `inbox:run` | Send Reply |
+| [`starInboxChat`](#op-starinboxchat) | `PUT /api/v1/inbox/chats/{chat_id}/star` | write | `inbox:write` | Star Inbox Chat |
+| [`tagReply`](#op-tagreply) ★ | `POST /api/v1/inbox/{reply_id}/tag` | external | `inbox:run` | Tag Reply |
+
+---
+
+<a id="op-assignreply"></a>
+
+### `g8.api.inbox.assignReply(input)`
+
+**Assign Reply**
+
+- HTTP: `POST /api/v1/inbox/{reply_id}/assign`
+- operationId: `assign_reply_inbox__reply_id__assign_post` (also callable as `g8.api.call("assign_reply_inbox__reply_id__assign_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `inbox:run`
+- ★ Hand-written: [`g8.inbox.assign()`](../sdk-clients.md#g8-inbox-assign)
+
+Assign a user to an inbox thread.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Thread/reply ID |
+| `body` | `AssignRequest` | yes | Request body; fields below. |
+| `query.channel` | `InboxChannel` | no | Channel type default `"email"` |
+
+Body fields (`AssignRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.assignee_email` | `string` | yes | Email of the user to assign |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.inbox.assignReply({
+  path: { reply_id: "id" },
+  body: { assignee_email: "jane@acme.com" },
+});
+```
+
+---
+
+<a id="op-autotaginboxchat"></a>
+
+### `g8.api.inbox.autoTagInboxChat(input)`
+
+**Auto Tag Inbox Chat**
+
+- HTTP: `POST /api/v1/inbox/chats/auto-tag`
+- operationId: `auto_tag_inbox_chat_inbox_chats_auto_tag_post` (also callable as `g8.api.call("auto_tag_inbox_chat_inbox_chats_auto_tag_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Ask the model to suggest tags for a chat.
+
+`org_id` is OVERWRITTEN from the key's own principal whatever the body
+says. The app's `ChatTaggingSuggestRequest` carries an `org_id` field
+because the in-app caller already knows its tenant - accepting it from a
+client here would let a key name someone else's org in a request body.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `Record<string, unknown>` | yes | Request body; fields below. |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.autoTagInboxChat({ body: {} });
+```
+
+---
+
+<a id="op-createuniversalactivitysavedview"></a>
+
+### `g8.api.inbox.createUniversalActivitySavedView(input)`
+
+**Create Universal Activity Saved View**
+
+- HTTP: `POST /api/v1/universal-activity/save-view`
+- operationId: `create_universal_activity_saved_view_universal_activity_save_view_post` (also callable as `g8.api.call("create_universal_activity_saved_view_universal_activity_save_view_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Save a named queue + filter combination.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `SavedViewCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`SavedViewCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.name` | `string` | yes | Display name. min length 1 |
+| `body.filters` | `Record<string, unknown>` | no | Filter set to restore. |
+| `body.icon` | `string \| null` | no |  |
+| `body.queue` | `string \| null` | no |  |
+| `body.shared` | `boolean` | no | Visible to teammates when true. default `false` |
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.createUniversalActivitySavedView({ body: { name: "Example" } });
+```
+
+---
+
+<a id="op-discardinboxemaildraft"></a>
+
+### `g8.api.inbox.discardInboxEmailDraft(input)`
+
+**Discard Inbox Email Draft**
+
+- HTTP: `DELETE /api/v1/inbox/emails/{email_id}/draft`
+- operationId: `discard_inbox_email_draft_inbox_emails__email_id__draft_delete` (also callable as `g8.api.call("discard_inbox_email_draft_inbox_emails__email_id__draft_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Throw away the AI draft on this thread.
+
+Discards the DRAFT, not the thread - the conversation and every message
+already sent survive. There is nothing to undo, so a UI should confirm
+before calling it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.email_id` | `string` | yes | Email thread id. |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.inbox.discardInboxEmailDraft({ path: { email_id: "jane@acme.com" } });
+```
+
+---
+
+<a id="op-getdraft"></a>
+
+### `g8.api.inbox.getDraft(input)`
+
+**Get Draft**
+
+- HTTP: `GET /api/v1/inbox/{reply_id}/draft`
+- operationId: `get_draft_inbox__reply_id__draft_get` (also callable as `g8.api.call("get_draft_inbox__reply_id__draft_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+- ★ Hand-written: [`g8.inbox.draft()`](../sdk-clients.md#g8-inbox-draft)
+
+Generate an AI draft reply. Charges credits - returns 402 on insufficient balance.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Thread/reply ID |
+| `query.channel` | `InboxChannel` | no | Channel type default `"email"` |
+
+**Returns** `ApiResponse_DraftResponse_`: the envelope `{ data: DraftResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DraftResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string` | yes | Generated draft text (HTML) |
+| `credits_charged` | `integer` | no | default `0` |
+| `plain_content` | `string \| null` | no | Plain text version |
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.getDraft({ path: { reply_id: "id" } });
+```
+
+---
+
+<a id="op-getinboxchat"></a>
+
+### `g8.api.inbox.getInboxChat(input)`
+
+**Get Inbox Chat**
+
+- HTTP: `GET /api/v1/inbox/chats/{chat_id}`
+- operationId: `get_inbox_chat_inbox_chats__chat_id__get` (also callable as `g8.api.call("get_inbox_chat_inbox_chats__chat_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+One chat thread, with its messages.
+
+Returned whole rather than wrapped in a page: this is a single `Chat`, and
+forcing it into an `items` list would hide the thread from a caller
+reading the obvious field.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.chat_id` | `string` | yes | Chat id. |
+
+**Returns** `ApiResponse_InboxPage_`: the envelope `{ data: InboxPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InboxPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.getInboxChat({ path: { chat_id: "id" } });
+```
+
+---
+
+<a id="op-getinboxemail"></a>
+
+### `g8.api.inbox.getInboxEmail(input)`
+
+**Get Inbox Email**
+
+- HTTP: `GET /api/v1/inbox/emails/{email_id}`
+- operationId: `get_inbox_email_inbox_emails__email_id__get` (also callable as `g8.api.call("get_inbox_email_inbox_emails__email_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+One email thread, with its messages.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.email_id` | `string` | yes | Email thread id. |
+
+**Returns** `ApiResponse_InboxPage_`: the envelope `{ data: InboxPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InboxPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.getInboxEmail({ path: { email_id: "jane@acme.com" } });
+```
+
+---
+
+<a id="op-getreply"></a>
+
+### `g8.api.inbox.getReply(input)`
+
+**Get Reply**
+
+- HTTP: `GET /api/v1/inbox/{reply_id}`
+- operationId: `get_reply_inbox__reply_id__get` (also callable as `g8.api.call("get_reply_inbox__reply_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+- ★ Hand-written: [`g8.inbox.get()`](../sdk-clients.md#g8-inbox-get)
+
+Get a single inbox thread by ID.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Thread/reply ID |
+| `query.channel` | `InboxChannel` | no | Channel type default `"email"` |
+
+**Returns** `ApiResponse_InboxThreadResponse_`: the envelope `{ data: InboxThreadResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InboxThreadResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `channel` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `assignees` | `Array<Record<string, unknown>>` | no |  |
+| `contact` | `Record<string, unknown> \| null` | no | Contact snapshot: name, email, company |
+| `created_at` | `string \| null` | no |  |
+| `messages` | `Array<InboxMessageItem>` | no |  |
+| `status` | `string \| null` | no |  |
+| `subject` | `string \| null` | no |  |
+| `tags` | `Array<Record<string, unknown>>` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.getReply({ path: { reply_id: "id" } });
+```
+
+---
+
+<a id="op-getuniversalactivitymetrics"></a>
+
+### `g8.api.inbox.getUniversalActivityMetrics(input)`
+
+**Get Universal Activity Metrics**
+
+- HTTP: `GET /api/v1/universal-activity/metrics`
+- operationId: `get_universal_activity_metrics_universal_activity_metrics_get` (also callable as `g8.api.call("get_universal_activity_metrics_universal_activity_metrics_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Activity metrics for a window.
+
+`tz` is REQUIRED, deliberately: every bucket boundary is a local calendar
+day, so a default would silently bucket a customer's data in the wrong
+timezone rather than failing loudly.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.tz` | `string` | yes | IANA timezone name, e.g. `America/New_York`. |
+| `query.range` | `"today" \| "yesterday" \| "week" \| "month" \| "custom"` | no | default `"today"` |
+| `query.scope` | `"mine" \| "all" \| "team"` | no | `team` is accepted for back-compat; the service aliases it to `mine`. default `"mine"` |
+| `query.start_date` | `string (date) \| null` | no | Custom range start, inclusive, in `tz`. |
+| `query.end_date` | `string (date) \| null` | no | Custom range end, inclusive, in `tz`. |
+| `query.workspace_id` | `string \| null` | no | Workspace UUID; omit for org-wide. |
+| `query.channel` | `string \| null` | no | Restrict to one channel. |
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.getUniversalActivityMetrics({ query: { tz: "example" } });
+```
+
+---
+
+<a id="op-getuniversalactivitypreview"></a>
+
+### `g8.api.inbox.getUniversalActivityPreview(input)`
+
+**Get Universal Activity Preview**
+
+- HTTP: `GET /api/v1/universal-activity/preview/{event_id}`
+- operationId: `get_universal_activity_preview_universal_activity_preview__event_id__get` (also callable as `g8.api.call("get_universal_activity_preview_universal_activity_preview__event_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Right-pane preview: email, thread and contact data for one event.
+
+Applies the same per-user mailbox privacy the app applies - the key sees
+what its owner sees, no more.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.event_id` | `string` | yes | Activity event id. |
+| `query.tabs` | `string` | no | Comma-separated tabs to hydrate. default `"preview,thread,contact"` |
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.getUniversalActivityPreview({ path: { event_id: "id" } });
+```
+
+---
+
+<a id="op-hotcontacts"></a>
+
+### `g8.api.inbox.hotContacts(input?)`
+
+**Hot Contacts**
+
+- HTTP: `GET /api/v1/inbox/hot-contacts`
+- operationId: `hot_contacts_inbox_hot_contacts_get` (also callable as `g8.api.call("hot_contacts_inbox_hot_contacts_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Most-engaged ('hot') contacts ranked by recent INBOUND interaction
+events (replies / opens / meeting RSVPs) — NOT a static score column.
+
+Org-scoped to the authenticated key's organization. Registered before
+`/{reply_id}` so 'hot-contacts' isn't captured as an id.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.days` | `integer` | no | Lookback window in days default `30` |
+| `query.limit` | `integer` | no | Max contacts to return default `10` |
+
+**Returns** `ApiResponse_HotContactsResult_`: the envelope `{ data: HotContactsResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`HotContactsResult` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `days` | `integer` | yes |  |
+| `contacts` | `Array<HotContact>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.hotContacts();
+```
+
+---
+
+<a id="op-listinbox"></a>
+
+### `g8.api.inbox.listInbox(input?)`
+
+**List Inbox**
+
+- HTTP: `GET /api/v1/inbox`
+- operationId: `list_inbox_inbox_get` (also callable as `g8.api.call("list_inbox_inbox_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+- ★ Hand-written: [`g8.inbox.list()`](../sdk-clients.md#g8-inbox-list)
+
+List inbox threads across email, SMS, and LinkedIn channels.
+
+``status`` accepts ``SENT``, ``AI_RESPONDED`` or ``DRAFT`` (case-insensitive)
+and is forwarded to the channel handler; an unknown value returns 422.
+
+CAVEAT — ``assignee``: this cannot filter by an arbitrary email in this
+layer. ``ChannelsService.get_channels`` only exposes ``assigned_to_me`` (a
+boolean bound to the *caller's* identity), so the value is used purely as a
+trigger to return the caller's own assigned threads — NOT threads assigned
+to the requested email. For an org (machine) API key the caller identity is
+the synthetic ``api-key@graph8.com``, which owns no threads, so the result
+is effectively empty. A true per-assignee filter needs an ``assignee_email``
+field on the shared ``ChannelRequest`` (out of scope for the dev-API layer).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.channel` | `InboxChannel \| null` | no | Filter by channel: email, sms, linkedin |
+| `query.sequence_id` | `string \| null` | no | Filter by sequence (campaign) ID |
+| `query.status` | `string \| null` | no | Filter by status |
+| `query.assignee` | `string \| null` | no | Filter by assignee email |
+| `query.tag` | `string \| null` | no | Filter by tag ID |
+| `query.page` | `integer` | no | Page number default `1` |
+| `query.page_size` | `integer` | no | Items per page default `50` |
+
+**Returns** `ApiResponse_list_InboxThreadResponse__`: the envelope `{ data: Array<InboxThreadResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InboxThreadResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `channel` | `string` | yes |  |
+| `id` | `string` | yes |  |
+| `assignees` | `Array<Record<string, unknown>>` | no |  |
+| `contact` | `Record<string, unknown> \| null` | no | Contact snapshot: name, email, company |
+| `created_at` | `string \| null` | no |  |
+| `messages` | `Array<InboxMessageItem>` | no |  |
+| `status` | `string \| null` | no |  |
+| `subject` | `string \| null` | no |  |
+| `tags` | `Array<Record<string, unknown>>` | no |  |
+| `updated_at` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.listInbox();
+```
+
+---
+
+<a id="op-listuniversalactivityqueues"></a>
+
+### `g8.api.inbox.listUniversalActivityQueues(input?)`
+
+**List Universal Activity Queues**
+
+- HTTP: `GET /api/v1/universal-activity/queues`
+- operationId: `list_universal_activity_queues_universal_activity_queues_get` (also callable as `g8.api.call("list_universal_activity_queues_universal_activity_queues_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Queue chips.
+
+NOTE this is a stub upstream: the chips row was removed in the 2026-05-18
+dashboard pivot and the endpoint stays live only so the existing frontend
+hook keeps resolving. Exposed for shape parity - do not build on its
+contents.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.scope` | `"mine" \| "all" \| "team"` | no | default `"mine"` |
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.listUniversalActivityQueues();
+```
+
+---
+
+<a id="op-listuniversalactivitysavedviews"></a>
+
+### `g8.api.inbox.listUniversalActivitySavedViews(input?)`
+
+**List Universal Activity Saved Views**
+
+- HTTP: `GET /api/v1/universal-activity/saved-views`
+- operationId: `list_universal_activity_saved_views_universal_activity_saved_views_get` (also callable as `g8.api.call("list_universal_activity_saved_views_universal_activity_saved_views_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Saved queue + filter combinations for this principal, plus shared ones.
+
+**Input**: none.
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.listUniversalActivitySavedViews();
+```
+
+---
+
+<a id="op-markinboxchatviewed"></a>
+
+### `g8.api.inbox.markInboxChatViewed(input)`
+
+**Mark Inbox Chat Viewed**
+
+- HTTP: `POST /api/v1/inbox/chats/{chat_id}/mark-viewed`
+- operationId: `mark_inbox_chat_viewed_inbox_chats__chat_id__mark_viewed_post` (also callable as `g8.api.call("mark_inbox_chat_viewed_inbox_chats__chat_id__mark_viewed_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Mark a chat read. Idempotent - marking a read chat read again is a no-op.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.chat_id` | `string` | yes | Chat id. |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.markInboxChatViewed({ path: { chat_id: "id" } });
+```
+
+---
+
+<a id="op-queryuniversalactivity"></a>
+
+### `g8.api.inbox.queryUniversalActivity(input?)`
+
+**Query Universal Activity**
+
+- HTTP: `POST /api/v1/universal-activity`
+- operationId: `query_universal_activity_universal_activity_post` (also callable as `g8.api.call("query_universal_activity_universal_activity_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+The unified activity timeline, cursor-paginated.
+
+POST rather than GET because the filter set is large and structured -
+matching the app, so a rebuilt inbox sends the same body.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `UniversalActivityQuery` | no | Request body; fields below. |
+
+Body fields (`UniversalActivityQuery`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.assignee_emails` | `Array<string> \| null` | no |  |
+| `body.campaign_ids` | `Array<string> \| null` | no |  |
+| `body.channels` | `Array<string> \| null` | no | Restrict to channels, e.g. `["email", "sms"]`. |
+| `body.company_id` | `string \| null` | no |  |
+| `body.contact_id` | `string \| null` | no |  |
+| `body.cursor` | `string \| null` | no | Opaque cursor from the previous page. |
+| `body.direction` | `string \| null` | no | `inbound` or `outbound`. |
+| `body.exclude_tag_ids` | `Array<string> \| null` | no |  |
+| `body.page_size` | `integer` | no | Rows per page (1-100). default `15`, min 1, max 100 |
+| `body.queue` | `"hot_replies" \| "follow_up" \| "booked_meetings" \| "everything" \| null` | no | Named queue to read. |
+| `body.search` | `string \| null` | no |  |
+| `body.tag_ids` | `Array<string> \| null` | no |  |
+| `body.updated_after` | `string (date-time) \| null` | no |  |
+| `body.updated_before` | `string (date-time) \| null` | no |  |
+| `body.workspace_all_mail` | `boolean \| null` | no | Only meaningful with `workspace_id`. A workspace normally auto-scopes the email leg to its own campaign and direct sequences; set true to show all mail through that workspace's mailboxes. |
+| `body.workspace_id` | `string \| null` | no | Workspace UUID; omit for org-wide. |
+
+**Returns** `ApiResponse_Any_`: the envelope `{ data: unknown, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.queryUniversalActivity();
+```
+
+---
+
+<a id="op-searchinboxchats"></a>
+
+### `g8.api.inbox.searchInboxChats(input?)`
+
+**Search Inbox Chats**
+
+- HTTP: `POST /api/v1/inbox/chats/search`
+- operationId: `search_inbox_chats_inbox_chats_search_post` (also callable as `g8.api.call("search_inbox_chats_inbox_chats_search_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Search and page the chat inbox.
+
+A POST because the filter is a body, not because it writes anything.
+
+`exclude_tag_ids` is the field that makes a Focused view work: the app
+sends the archived / deleted / warmup / bounced tags there. Omit it and
+those threads come back.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `ChatSearchRequest` | no | Request body; fields below. |
+
+Body fields (`ChatSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.exclude_tag_ids` | `Array<string> \| null` | no | Drop chats carrying ANY of these tag ids. This is what makes a Focused view work - the app sends the archived/deleted/warmup/bounced tags here. Without it those threads come back. |
+| `body.page` | `integer` | no | default `1`, min 1 |
+| `body.page_size` | `integer` | no | default `20`, min 1, max 100 |
+| `body.sort_by` | `"updated_at" \| "created_at" \| "last_message_at"` | no | Field to sort by. See `SortByField` for the accepted values. default `"created_at"` |
+| `body.sort_order` | `"asc" \| "desc"` | no | default `"desc"` |
+| `body.tags` | `Array<string> \| null` | no | Keep chats carrying ANY of these tag ids. |
+| `body.updated_after` | `string (date-time) \| null` | no |  |
+| `body.updated_before` | `string (date-time) \| null` | no |  |
+| `body.user_id` | `string \| null` | no | Restrict to one user's chats. |
+
+**Returns** `ApiResponse_InboxPage_`: the envelope `{ data: InboxPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InboxPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.searchInboxChats();
+```
+
+---
+
+<a id="op-searchinboxemails"></a>
+
+### `g8.api.inbox.searchInboxEmails(input)`
+
+**Search Inbox Emails**
+
+- HTTP: `POST /api/v1/inbox/emails/search`
+- operationId: `search_inbox_emails_inbox_emails_search_post` (also callable as `g8.api.call("search_inbox_emails_inbox_emails_search_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `inbox:read`
+
+Search email threads across one or more mailboxes.
+
+`mailboxes` is REQUIRED and an empty list is not "all mailboxes" - the
+inbox is per-mailbox, so an empty list is simply no result. Paging is on
+the query string, matching the app, because the body is the filter.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `EmailSearchRequest` | yes | Request body; fields below. |
+| `query.page` | `integer` | no | default `1` |
+| `query.page_size` | `integer` | no | default `10` |
+
+Body fields (`EmailSearchRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.mailboxes` | `Array<string>` | yes | Mailbox addresses to search. REQUIRED: the inbox is per-mailbox, and an empty list is not 'all mailboxes', it is no result. min items 1 |
+| `body.assigned_to_user_email` | `string \| null` | no | Only threads assigned to this user. |
+| `body.campaign_ids` | `Array<string> \| null` | no |  |
+| `body.exclude_tag_ids` | `Array<string> \| null` | no |  |
+| `body.search` | `string \| null` | no |  |
+| `body.search_emails` | `Array<string> \| null` | no | Return threads touching ANY of these addresses, in the thread owner or in a message's from/to. OR-matched - a scope filter, not a full-text search. |
+| `body.sort_by` | `"updated_at" \| "created_at" \| "last_message_at"` | no | default `"updated_at"` |
+| `body.sort_order` | `"asc" \| "desc"` | no | default `"desc"` |
+| `body.status` | `"SENT" \| "AI_RESPONDED" \| "DRAFT" \| null` | no | Keep threads in one delivery state. Closed to the three the internal `EmailStatus` enum accepts - an open string here reaches a strict enum inside the handler and raises a bare `pydantic.ValidationError`, which no handler catches, so it escapes as a 500 instead of a 422. |
+| `body.tag_ids` | `Array<string> \| null` | no |  |
+| `body.updated_after` | `string (date-time) \| null` | no |  |
+| `body.updated_before` | `string (date-time) \| null` | no |  |
+
+**Returns** `ApiResponse_InboxPage_`: the envelope `{ data: InboxPage, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`InboxPage` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.searchInboxEmails({ body: { mailboxes: ["example"] } });
+```
+
+---
+
+<a id="op-sendinboxemail"></a>
+
+### `g8.api.inbox.sendInboxEmail(input)`
+
+**Send Inbox Email**
+
+- HTTP: `POST /api/v1/inbox/emails/{email_id}/send`
+- operationId: `send_inbox_email_inbox_emails__email_id__send_post` (also callable as `g8.api.call("send_inbox_email_inbox_emails__email_id__send_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `inbox:run`
+
+SEND. THIS DELIVERS A REAL MESSAGE TO A REAL RECIPIENT.
+
+Classifies `external`, so it needs the `inbox:run` grant rather than plain
+write - a customer can hand out "read and triage my inbox" without handing
+out "send as me".
+
+Pass `message_id` to keep the reply in its thread; without it the message
+arrives as a new conversation.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.email_id` | `string` | yes | Email thread id. |
+| `query.mailbox` | `string` | yes | Mailbox address to send FROM. |
+| `query.provider` | `"google_mailbox" \| "smtp"` | yes | Required and not inferred: the same address can be connected either way, and guessing would send through the wrong transport. Declared as a Literal so an unknown value is a request-layer 422 - as a bare `str` it reached `Mailbox(provider)` inside the handler and raised a ValueError, which is a 500 on the single most consequential call on this surface. |
+| `body` | `EmailSendRequest` | yes | Request body; fields below. |
+
+Body fields (`EmailSendRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.content` | `string` | yes | Body. |
+| `body.from_email` | `Array<string>` | yes | min items 1 |
+| `body.subject` | `string` | yes | Subject. |
+| `body.to` | `Array<string>` | yes | Recipients. At least one. min items 1 |
+| `body.bcc_email` | `Array<string>` | no |  |
+| `body.cc_email` | `Array<string>` | no |  |
+| `body.message_id` | `string \| null` | no | Message being replied to, to keep the thread. |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.inbox.sendInboxEmail({
+  path: { email_id: "jane@acme.com" },
+  query: { mailbox: "example", provider: "google_mailbox" },
+  body: {
+    content: "example",
+    from_email: ["jane@acme.com"],
+    subject: "Example",
+    to: ["+15555550100"],
+  },
+});
+```
+
+---
+
+<a id="op-sendreply"></a>
+
+### `g8.api.inbox.sendReply(input)`
+
+**Send Reply**
+
+- HTTP: `POST /api/v1/inbox/{reply_id}/send`
+- operationId: `send_reply_inbox__reply_id__send_post` (also callable as `g8.api.call("send_reply_inbox__reply_id__send_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `inbox:run`
+- ★ Hand-written: [`g8.inbox.send()`](../sdk-clients.md#g8-inbox-send)
+
+Send a reply through the specified channel (email, sms, or linkedin).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Thread/reply ID |
+| `body` | `SendRequest` | yes | Request body; fields below. |
+
+Body fields (`SendRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | Message body to send |
+| `body.channel` | `InboxChannel` | yes | Channel to send through: email, sms, or linkedin |
+| `body.from_address` | `string \| null` | no | Sender address (mailbox email, phone number, or LinkedIn account ID) |
+| `body.subject` | `string \| null` | no | Email subject (optional, for email channel) |
+| `body.to` | `string \| null` | no | Recipient override (email address, phone number, or LinkedIn ID) |
+
+**Returns** `ApiResponse_SendResponse_`: the envelope `{ data: SendResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`SendResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `channel` | `string` | no | default `"email"` |
+| `message_id` | `string \| null` | no |  |
+| `status` | `string` | no | default `"sent"` |
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.inbox.sendReply({
+  path: { reply_id: "id" },
+  body: { body: "example", channel: "email" },
+});
+```
+
+---
+
+<a id="op-starinboxchat"></a>
+
+### `g8.api.inbox.starInboxChat(input)`
+
+**Star Inbox Chat**
+
+- HTTP: `PUT /api/v1/inbox/chats/{chat_id}/star`
+- operationId: `star_inbox_chat_inbox_chats__chat_id__star_put` (also callable as `g8.api.call("star_inbox_chat_inbox_chats__chat_id__star_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+SET the starred state. `is_starred` is required and is not a toggle.
+
+A toggle is not idempotent: a retried request would silently un-star the
+thread it just starred. A PUT with an explicit value is safe to retry,
+which is why the app models it this way and why this surface does not
+"helpfully" make the field optional.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.chat_id` | `string` | yes | Chat id. |
+| `body` | `ChatStarRequest` | yes | Request body; fields below. |
+
+Body fields (`ChatStarRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.is_starred` | `boolean` | yes |  |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.inbox.starInboxChat({ path: { chat_id: "id" }, body: { is_starred: true } });
+```
+
+---
+
+<a id="op-tagreply"></a>
+
+### `g8.api.inbox.tagReply(input)`
+
+**Tag Reply**
+
+- HTTP: `POST /api/v1/inbox/{reply_id}/tag`
+- operationId: `tag_reply_inbox__reply_id__tag_post` (also callable as `g8.api.call("tag_reply_inbox__reply_id__tag_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `inbox:run`
+- ★ Hand-written: [`g8.inbox.tag()`](../sdk-clients.md#g8-inbox-tag)
+
+Attach tags to an inbox thread.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Thread/reply ID |
+| `body` | `developer_api__interfaces__dtos__inbox__TagRequest` | yes | Request body; fields below. |
+| `query.channel` | `InboxChannel` | no | Channel type default `"email"` |
+
+Body fields (`developer_api__interfaces__dtos__inbox__TagRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.tag_ids` | `Array<string>` | yes | Tag IDs to associate with the thread |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.inbox.tagReply({ path: { reply_id: "id" }, body: { tag_ids: ["id"] } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-hotcontact"></a>
+
+### `HotContact`
+
+One most-engaged contact (ranked by recent inbound activity).
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `contact_id` | `string` | yes |  |
+| `email` | `string \| null` | no |  |
+| `events` | `integer` | no | Inbound interaction events in the window default `0` |
+| `last_at` | `string \| null` | no | Most recent inbound activity (ISO) |
+| `meetings` | `integer` | no | Of those events, how many were meetings default `0` |
+| `who` | `string \| null` | no | Display name, else email, else id |
+
+<a id="type-inboxchannel"></a>
+
+### `InboxChannel`
+
+Type: `"email" | "sms" | "linkedin"`.
+
+<a id="type-inboxmessageitem"></a>
+
+### `InboxMessageItem`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content` | `string \| null` | no |  |
+| `date` | `string \| null` | no |  |
+| `from_address` | `string \| null` | no |  |
+| `is_draft` | `boolean` | no | default `false` |
+| `message_id` | `string \| null` | no |  |
+| `responder` | `string \| null` | no | USER, AI, or OTHER |
+| `to_addresses` | `Array<string>` | no |  |