Tools — Inbox & Messaging

The Inbox & Messaging tools give your AI assistant read access to the unified inbox (Email, LinkedIn, WhatsApp) and the ability to mark email threads and send messages on your connected channels.

crm_inbox

Read email and message conversations from the unified inbox (read-only).

Parameters

Key behaviors

• App-parity visibility — You only ever see threads you own. Email/meeting threads are owned via the connected account that synced them; LinkedIn/WhatsApp threads are owned via the thread's managed-by-workspace-user. A non-owned single message fetched via get_interaction is gated by that thread's content visibility.
• Decrypted bodies — Message bodies are decrypted at read time for threads you own, so you get the full content just like in the app.
• Thread pagination — Listing is paginated server-side. Use cursor and limit to page through results.
• Message pagination — Large threads paginate internally via message_cursor and message_limit. When next_message_cursor is null, all messages have been returned.

Examples

List the most recent email threads:

{
  "action": "list_threads",
  "channel": "email",
  "limit": 10
}

Response:

{
  "data": [
    {
      "id": "t_abc123",
      "subject": "Q3 contract renewal",
      "channel": "email",
      "last_message_date": "2026-06-10T14:22:00Z"
    }
  ],
  "total": 23,
  "nextCursor": "eyJvZmZzZXQiOjEwLCJsaW1pdCI6MTB9"
}

Get a thread with paginated messages:

{
  "action": "get_thread",
  "thread_id": "t_abc123",
  "message_limit": 20
}

Response:

{
  "thread": {
    "id": "t_abc123",
    "subject": "Q3 contract renewal",
    "channel": "email"
  },
  "messages": [
    {
      "id": "msg_001",
      "date": "2026-06-10T14:22:00Z",
      "body": "Hi Bob, following up on the renewal..."
    }
  ],
  "total_messages": 4,
  "next_message_cursor": null
}

Get a single message by id:

{
  "action": "get_interaction",
  "interaction_id": "550e8400-e29b-41d4-a716-446655440000"
}

crm_mark_email

Mark an email thread as read/unread or favorite/unfavorite. Email channel only.

Parameters

Key behaviors

• Email only — These map to Gmail labels (UNREAD / STARRED) or Outlook flags in your own mailbox. A non-email thread_id is rejected with INVALID_CHANNEL.
• Ownership-checked — You can only act on a thread you own (you must have synced an interaction in it). Otherwise you get PERMISSION_DENIED.
• Provider-resolved — The handler resolves the CRM thread to its external thread id (external_thread_id) and to the connected account that synced it, then applies the change in the provider mailbox. The CRM stores no read/favorite state — it lives in your mailbox.
• Reversible — Every action has its inverse (read↔unread, favorite↔unfavorite).

Get the thread_id from crm_inbox or crm_find_activity.

Examples

Mark a thread as read:

{
  "action": "read",
  "thread_id": "t_abc123"
}

Response:

{
  "thread_id": "t_abc123",
  "action": "read",
  "channel": "email",
  "applied": true
}

Star (favorite) a thread:

{
  "action": "favorite",
  "thread_id": "t_abc123"
}

crm_send_message

Send a message on a connected channel — Email, LinkedIn, or WhatsApp.

Parameters

Per-channel requirements

Key behaviors

• Own accounts only — You can only send from your own connected accounts, and can only reply within a thread you own. Ownership is re-checked on every send.
• Per-channel validation — Preview surfaces missing/ambiguous inputs as structured errors (MISSING_REQUIRED_FIELD, AMBIGUOUS_SENDER, NO_ACCOUNT, PERMISSION_DENIED, INVALID_CHANNEL, SEND_NOT_ENABLED) before anything is sent.
• Stateful confirmation — The confirm_token from preview is single-use, expires after ~5 minutes, and is bound to the message fingerprint. A send with no/expired token returns CONFIRM_REQUIRED/CONFIRM_INVALID; one whose recipients or body changed since preview returns CONFIRM_MISMATCH. (If the rate-limit/confirmation store is unavailable the gate fails open so an outage can't block legitimate sends.)
• Idempotent — An identical message sent twice in quick succession is de-duplicated server-side: the second call returns mode: "duplicate_suppressed" and is not delivered again.
• Rate limited — Real sends are capped (api:messaging-send, 30/hour per user); previewing is free.

Examples

Step 1 — preview a new email:

{
  "action": "preview",
  "channel": "email",
  "to": ["bob@acme.com"],
  "subject": "Q3 contract renewal",
  "body": "<p>Hi Bob, following up on the renewal...</p>",
  "from_account_email": "alice@example.com"
}

Preview response:

{
  "mode": "preview",
  "confirm_required": true,
  "confirm_token": "a1b2c3d4-…",
  "message": {
    "channel": "email",
    "from": "alice@example.com",
    "to": ["bob@acme.com"],
    "cc": [],
    "bcc": [],
    "subject": "Q3 contract renewal",
    "body": "<p>Hi Bob, following up on the renewal...</p>",
    "reply_to_thread": null
  },
  "note": "Present this message to the user. Call again with action=\"send\" AND echo this confirm_token ONLY after the user has explicitly confirmed. Sending is irreversible."
}

Step 2 — send after the user confirms (echo the confirm_token from step 1):

{
  "action": "send",
  "channel": "email",
  "to": ["bob@acme.com"],
  "subject": "Q3 contract renewal",
  "body": "<p>Hi Bob, following up on the renewal...</p>",
  "from_account_email": "alice@example.com",
  "confirm_token": "a1b2c3d4-…"
}

Sent response:

{
  "mode": "sent",
  "channel": "email",
  "message_id": "msg_001",
  "message": {
    "channel": "email",
    "from": "alice@example.com",
    "to": ["bob@acme.com"],
    "subject": "Q3 contract renewal",
    "body": "<p>Hi Bob, following up on the renewal...</p>"
  }
}

Reply on LinkedIn (preview):

{
  "action": "preview",
  "channel": "linkedin",
  "thread_id": "t_li_456",
  "body": "Thanks for connecting — happy to set up a call next week."
}

Send a WhatsApp message by chat id:

{
  "action": "send",
  "channel": "whatsapp",
  "chat_id": "33612345678@c.us",
  "body": "Hi! Just confirming our meeting tomorrow at 10am."
}