什么是 iGPT 邮件搜索？

iGPT 邮件搜索是专为 Openclaw Skills 库设计的先进检索工具。它允许 AI 智能体在用户的整个收件箱历史记录中执行混合语义和关键词搜索，支持 Gmail、Outlook 和标准 IMAP。与传统的仅限关键词搜索不同，此技能能够理解查询背后的概念含义，确保即使精确术语不匹配也能找到相关的对话。

该技能在构建时充分考虑了安全性，采用每用户隔离和 API 密钥范围限制。它作为基于电子邮件工作流的基础检索层，提供原始邮件内容和线程引用，可由推理智能体进一步处理。作为 Openclaw Skills 的核心组件，它弥补了静态知识与实时通信数据之间的鸿沟。

下载入口:https://github.com/openclaw/skills/tree/main/skills/sammy-spk/igpt-email-search

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

iGPT 邮件搜索 应用场景

• 使用自然语言定位特定的项目更新或董事会会议记录。
• 在日期范围内检索来自特定联系人或法律部门的所有信件。
• 查找特定财政季度的发票或财务文件。
• 将相关的电子邮件上下文送入 AI 智能体工作流以进行进一步分析。
• 在启动新任务或回复之前，检查关于某个主题的历史讨论。

1. AI 智能体通过 Openclaw Skills 界面使用自然语言查询发起搜索请求。
2. 请求被发送到 iGPT 召回/搜索端点，并通过安全的 API 密钥进行身份验证。
3. iGPT 引擎执行混合搜索，将语义含义的向量嵌入与传统的关键词索引相结合。
4. 结果按用户 ID 和可选的日期范围进行过滤，以确保隐私和准确性。
5. 返回相关邮件线程、内容和附件引用的排序列表以供处理。

iGPT 邮件搜索 配置指南

要使用 Openclaw Skills 将其集成到您的环境中，请安装官方 SDK 并配置您的凭据：

pip install igptai

配置您的环境变量：

export IGPT_API_KEY="your-api-key-here"

在尝试检索数据之前，请确保用户已通过 iGPT OAuth 流程授权其电子邮件提供商。

iGPT 邮件搜索 数据架构与分类体系

返回的数据包括结构化的线程对象，包含主题行、正文内容、发件人详情和附件元数据。

name: igpt-email-search
description: >
  Secure, per-user-isolated semantic email search via the iGPT API. Hybrid semantic + keyword
  retrieval across a user's full Gmail, Outlook, or IMAP inbox history — no shell access, no
  filesystem access, API-key scoped only. Returns relevant messages and threads ranked by meaning,
  not just keyword overlap. Use when the user needs to find specific emails, threads, or
  conversations by topic, participant, date range, or content. Retrieval only — for reasoning,
  summaries, or structured extraction, use the companion skill igpt-email-ask.
homepage: https://igpt.ai/hub/playground/
metadata: {"clawdbot":{"emoji":"??","requires":{"env":["IGPT_API_KEY"]},"primaryEnv":"IGPT_API_KEY"},"author":"igptai","version":"1.0.0","license":"MIT","tags":["email","search","retrieval","semantic-search","context","productivity"]}

iGPT Email Search

Search a user's email by meaning, not just keywords. Hybrid semantic + keyword retrieval across their entire inbox history.

What This Skill Does

This skill queries iGPT's recall/search endpoint to find relevant emails and threads from a user's connected inbox. The search engine:

• Combines semantic vector search (understands meaning) with keyword matching (catches exact terms)
• Searches across the user's full indexed email history (not limited to 90 days like some providers)
• Supports date range filtering for time-bounded queries
• Returns ranked results with relevance scoring
• Includes attachment references when present

This is retrieval only. It finds and returns email content. It does not reason over it, summarize it, or extract structured data. For that, use igpt-email-ask — the companion skill that runs iGPT's Context Engine for analysis, summarization, and structured extraction.

When to Use This Skill

• Find emails about a specific topic, project, or person
• Locate threads within a date range
• Retrieve raw email content for further processing
• Feed email context into another tool or agent step
• Check what was discussed about a topic before taking action
• Pull recent correspondence with a specific contact or company

When to Use igpt-email-ask Instead

If you need summarized or synthesized answers, structured data extraction (tasks, decisions, contacts), sentiment analysis, reasoning across multiple threads, or questions that require understanding rather than finding — use igpt-email-ask, not search.

Rule of thumb: if the prompt is a question, use ask. If the prompt is a lookup, use search.

Prerequisites

1. An iGPT API key (get one at https://igpt.ai/hub/apikeys/)
2. A connected email datasource — the user must have completed OAuth authorization via connectors/authorize before search will return results
3. Python >= 3.8 with the igptai package installed

Setup

pip install igptai

Set your API key as an environment variable:

export IGPT_API_KEY="your-api-key-here"

Usage

Basic: Search by topic

from igptai import IGPT
import os

igpt = IGPT(api_key=os.environ["IGPT_API_KEY"], user="user_123")

results = igpt.recall.search(query="board meeting notes")
print(results)

Returns a ranked list of relevant emails and threads matching the query, ordered by relevance.

Search with date range

Narrow results to a specific time window:

results = igpt.recall.search(
    query="budget allocation",
    date_from="2026-01-01",
    date_to="2026-01-31"
)
print(results)

Limit number of results

results = igpt.recall.search(
    query="partnership proposals",
    max_results=10
)
print(results)

Search for a specific person's emails

The semantic engine understands participant context:

results = igpt.recall.search(
    query="emails from Sarah about the product launch",
    date_from="2026-01-01"
)
print(results)

Combine with ask for a two-step workflow

A common pattern: search first to see what's there, then ask for analysis:

# Step 1: Find relevant threads
results = igpt.recall.search(
    query="Acme Corp contract negotiation",
    max_results=20
)
print(f"Found {len(results)} relevant threads")

# Step 2: Ask for structured analysis
analysis = igpt.recall.ask(
    input="Summarize the current status of the Acme Corp contract negotiation. What are the open issues and who owns them?",
    output_format="json"
)
print(analysis)

Parameters

Error Handling

The SDK uses a no-throw pattern. Errors are returned as values, not exceptions:

results = igpt.recall.search(query="Q4 planning")

if isinstance(results, dict) and results.get("error"):
    error = results["error"]
    if error == "auth":
        print("Check your API key")
    elif error == "params":
        print("Check your request parameters")
    elif error == "network_error":
        print("Network issue, retry")
else:
    for result in results:
        print(result)

External Endpoints

This skill communicates exclusively with:

• https://api.igpt.ai/v1/recall/search — the search endpoint
• https://api.igpt.ai/v1/connectors/authorize — only during initial datasource connection setup

No other external endpoints are contacted. No data is sent to any third-party service. The igptai PyPI package source is available at https://github.com/igptai/igptai-python.

Security & Privacy

• API-key scoped: All requests authenticate via IGPT_API_KEY sent as a Bearer token over HTTPS. No shell access, no filesystem access, no system commands.
• Per-user isolation: Every query is scoped to a specific user identifier. User A cannot access User B's email data. Isolation is enforced at the index and execution level, not as a filter layer.
• OAuth read-only: The email datasource connection uses OAuth with read-only scopes. The skill does not send, modify, or delete emails.
• No data retention: Prompts are discarded after execution. Memory is reconstructed on-demand, not stored.
• Transport encryption: All communication occurs over HTTPS. No plaintext endpoints.
• No local persistence: This skill does not write to disk, modify environment files, or create persistent configuration outside of the standard IGPT_API_KEY environment variable.

For the full security model, see https://docs.igpt.ai/docs/security/model.

How It Differs from Basic Email Search

Example Queries

These all work as natural language:

• "board meeting notes" — finds emails about board meetings even if they don't contain that exact phrase
• "emails about the product launch timeline" — semantic understanding of the topic
• "anything from legal about compliance" — understands department and topic context
• "invoices from Q4 2025" — combines topic with implicit date context
• "conversations where deadlines were mentioned" — conceptual search

Companion Skills

Both skills use the same IGPT_API_KEY and connected datasources. Install both for the full search → analyze workflow.

Resources

• Get API Key: https://igpt.ai/hub/apikeys/
• Documentation: https://docs.igpt.ai
• API Reference: https://docs.igpt.ai/docs/api-reference/search
• Playground: https://igpt.ai/hub/playground/
• Python SDK: https://pypi.org/project/igptai/
• Node.js SDK: https://www.npmjs.com/package/igptai
• GitHub: https://github.com/igptai/igptai-python