iGPT Email Ask
Ask questions about a user's email and get reasoned, structured answers. Powered by iGPT's Context Engine, which reconstructs conversations, decisions, ownership, and intent across time.
What This Skill Does
This skill queries iGPT's recall/ask endpoint to generate answers grounded in a user's connected email data. Unlike basic retrieval, the Context Engine:
- - Reconstructs full conversation threads across replies, forwards, and CCs
- Identifies who decided what, who owns what, and what's still open
- Extracts structured data (tasks, deadlines, contacts, risks) from unstructured email
- Supports multiple quality tiers for different complexity levels
- Returns text, JSON, or schema-validated structured output
- Supports streaming (SSE) for real-time responses
When to Use This Skill
- - Summarize what happened in a thread or across threads
- Extract action items, decisions, or open questions
- Analyze sentiment or risk in deal/customer threads
- Answer questions that require understanding context across multiple emails
- Generate structured data from email content (JSON, schema-validated)
- Prepare briefings before meetings based on recent correspondence
Prerequisites
- 1. An iGPT API key (get one at https://igpt.ai/hub/apikeys/)
- A connected email datasource -- the user must have completed OAuth authorization via
connectors/authorize before ask will return results. You can check connection status with datasources.list(). - Python >= 3.8 with the
igptai package installed
Setup
CODEBLOCK0
Set your API key as an environment variable:
CODEBLOCK1
Usage
Basic: Ask a question
CODEBLOCK2
Get JSON output
Pass output_format="json" for unstructured JSON, or provide a schema for validated structured output:
CODEBLOCK3
Example response:
CODEBLOCK4
Use quality tiers
iGPT's Context Engine has three quality tiers:
CODEBLOCK5
Stream responses
Streaming returns parsed JSON chunks (dicts), not raw text. Extract content from each chunk:
CODEBLOCK6
Streaming is resilient: if the connection breaks, the iterator yields an error chunk and finishes rather than throwing.
Check datasource connection before asking
CODEBLOCK7
Parameters
| Parameter | Type | Required | Description |
|---|
| input | string | Yes | The prompt or question to ask. |
| user |
string | Yes (or set in constructor) | Unique user identifier scoping the query to their connected data. Per-call value overrides constructor default. |
| stream | boolean | No (default: false) | If true, returns a generator yielding parsed JSON dicts via SSE. |
| quality | string | No | Context Engine quality tier:
"cef-1-normal",
"cef-1-high", or
"cef-1-reasoning". |
| output_format | string or object | No |
"text" (default),
"json", or
{"strict": true, "schema": <JSON Schema>} for validated structured output. |
Error Handling
The SDK does not throw exceptions. It returns normalized error objects:
CODEBLOCK8
External Endpoints
This skill communicates exclusively with:
- -
https://api.igpt.ai/v1/recall/ask/ -- the reasoning endpoint - INLINECODE12 -- only during initial datasource connection setup
- INLINECODE13 -- to check connection status
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/igpt-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. - Built-in retries: The SDK retries failed requests with exponential backoff (default: 3 attempts, 100ms base, 2x factor) before returning a
network_error.
For the full security model, see https://docs.igpt.ai/docs/security/model.
What This Skill Does NOT Do
- - Does not send, modify, forward, or delete emails
- Does not access the filesystem or execute shell commands
- Does not install persistent services or scheduled tasks
- Does not contact endpoints other than INLINECODE19
- Does not store API keys or OAuth tokens outside the environment variable
Example Questions
These all work as natural language prompts:
- -
"Summarize key risks from this week's email threads" -- cross-thread analysis - INLINECODE21 -- task extraction
- INLINECODE22 -- deal intelligence
- INLINECODE23 -- ownership and deadline extraction
- INLINECODE24 -- sentiment analysis
- INLINECODE25 -- meeting prep
Resources
- - Get API Key: https://igpt.ai/hub/apikeys/
- Documentation: https://docs.igpt.ai
- API Reference: https://docs.igpt.ai/docs/api-reference/ask
- 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/igpt-python
iGPT 邮件问答
对用户的邮件提出问题，并获得有推理依据的结构化答案。由 iGPT 的上下文引擎驱动，该引擎能够跨时间重构对话、决策、所有权和意图。
该技能的功能
该技能调用 iGPT 的 recall/ask 端点，基于用户已连接的邮件数据生成答案。与基础检索不同，上下文引擎能够：
- - 跨回复、转发和抄送重构完整的对话线程
- 识别谁做了什么决策、谁拥有什么、以及哪些事项尚未解决
- 从非结构化邮件中提取结构化数据（任务、截止日期、联系人、风险）
- 支持多种质量等级，适用于不同复杂度的场景
- 返回文本、JSON 或经过模式验证的结构化输出
- 支持流式传输（SSE），实现实时响应
何时使用该技能
- - 总结单个线程或跨线程中发生的事情
- 提取行动项、决策或待解决问题
- 分析交易/客户线程中的情绪或风险
- 回答需要理解多封邮件上下文的问题
- 从邮件内容生成结构化数据（JSON、模式验证）
- 根据近期通信准备会议前的简报
前提条件
- 1. 一个 iGPT API 密钥（在 https://igpt.ai/hub/apikeys/ 获取）
- 一个已连接的邮件数据源——用户必须通过 connectors/authorize 完成 OAuth 授权后，ask 才能返回结果。您可以使用 datasources.list() 检查连接状态。
- Python >= 3.8，并已安装 igptai 包
安装
bash
pip install igptai
将您的 API 密钥设置为环境变量：
bash
export IGPTAPIKEY=your-api-key-here
使用方法
基础：提问
python
from igptai import IGPT
import os
igpt = IGPT(apikey=os.environ[IGPTAPIKEY], user=user123)
res = igpt.recall.ask(input=总结本周会议中的关键风险、决策和下一步行动。)
if res is not None and res.get(error):
print(iGPT 错误：, res)
else:
print(res)
获取 JSON 输出
传递 output_format=json 获取非结构化 JSON，或提供模式以获取经过验证的结构化输出：
python
简单 JSON 输出
res = igpt.recall.ask(
input=本周有哪些未完成的行动项？,
output_format=json
)
经过模式验证的结构化输出
res = igpt.recall.ask(
input=本周未完成的行动项,
quality=cef-1-normal,
output_format={
strict: True,
schema: {
type: object,
required: [action_items],
additionalProperties: False,
properties: {
action_items: {
type: array,
items: {
type: object,
required: [title, owner, due_date],
properties: {
title: {type: string},
owner: {type: string},
due_date: {type: string}
}
}
}
}
}
}
)
print(res)
示例响应：
json
{
action_items: [
{
title: 批准修订后的第一季度预算分配,
owner: Dvir Ben-Aroya,
due_date: 2026-01-15
},
{
title: 批准最终的2026财年战略优先事项,
owner: 董事会,
due_date: 2026-01-31
}
]
}
使用质量等级
iGPT 的上下文引擎有三个质量等级：
python
普通：速度快，适用于直接问题
res = igpt.recall.ask(
input=我下次与 Acme Corp 的会议是什么时候？,
quality=cef-1-normal
)
高：更深层次的推理，适用于复杂的多线程分析
res = igpt.recall.ask(
input=我们与 Acme Corp 当前的谈判状态如何，我们有哪些筹码？,
quality=cef-1-high
)
推理：最大深度，适用于复杂的跨线程综合
res = igpt.recall.ask(
input=在过去一个季度与 Acme 的所有通信中，哪些模式表明存在风险，我们应该如何应对？,
quality=cef-1-reasoning
)
流式响应
流式传输返回解析后的 JSON 块（字典），而非原始文本。从每个块中提取内容：
python
stream = igpt.recall.ask(
input=请向我介绍 Acme 交易从首次接触到现在的完整时间线。,
stream=True
)
for chunk in stream:
if isinstance(chunk, dict) and chunk.get(error):
print(流式错误：, chunk)
break
# 每个块都是一个解析后的 JSON 字典
print(chunk)
流式传输具有弹性：如果连接中断，迭代器会生成一个错误块并结束，而不是抛出异常。
在提问前检查数据源连接
python
验证用户是否有已连接的数据源
status = igpt.datasources.list()
if status is not None and not status.get(error):
print(已连接的数据源：, status)
else:
# 先连接数据源
auth = igpt.connectors.authorize(service=spike, scope=messages)
print(打开此 URL 进行授权：, auth.get(url))
参数
| 参数 | 类型 | 必填 | 描述 |
|---|
| input | 字符串 | 是 | 要提出的提示或问题。 |
| user |
字符串 | 是（或在构造函数中设置） | 唯一用户标识符，将查询范围限定为其已连接的数据。每次调用的值会覆盖构造函数默认值。 |
| stream | 布尔值 | 否（默认：false） | 如果为 true，则返回一个生成器，通过 SSE 生成解析后的 JSON 字典。 |
| quality | 字符串 | 否 | 上下文引擎质量等级：cef-1-normal、cef-1-high 或 cef-1-reasoning。 |
| output_format | 字符串或对象 | 否 | text（默认）、json 或 {strict: true, schema:
}，用于经过验证的结构化输出。 |
错误处理
SDK 不会抛出异常。它会返回规范化的错误对象：
python
res = igpt.recall.ask(input=昨天的董事会会议上发生了什么？)
if res is not None and res.get(error):
error = res[error]
if error == auth:
print(检查您的 API 密钥)
elif error == params:
print(检查您的请求参数)
elif error == network_error:
print(网络问题——SDK 在返回此错误前会使用指数退避进行重试（默认 3 次尝试）)
else:
print(res)
外部端点
该技能仅与以下端点通信：
- - https://api.igpt.ai/v1/recall/ask/——推理端点
- https://api.igpt.ai/v1/connectors/authorize/——仅在初始数据源连接设置期间
- https://api.igpt.ai/v1/datasources/list/——用于检查连接状态
不会联系其他外部端点。不会向任何第三方服务发送数据。igptai PyPI 包的源代码可在 https://github.com/igptai/igpt-python 获取。
安全与隐私
- - API 密钥作用域：所有请求通过 IGPTAPIKEY 作为 Bearer 令牌通过 HTTPS 进行身份验证。无 shell 访问权限、无文件系统访问权限、无系统命令。
- 按用户隔离：每个查询都限定在特定的 user 标识符范围内。用户 A 无法访问用户 B 的邮件数据。隔离在索引和执行级别强制执行，而非作为过滤层。
- OAuth 只读：邮件数据源连接使用具有只读作用域的 OAuth。该技能不会发送、修改或删除邮件。
- 无数据保留：提示在执行后被丢弃。内存按需重建，而非存储。
- 传输加密：所有通信通过 HTTPS 进行。无明文端点。
- 无本地持久化：该技能不会写入磁盘、修改环境文件或在标准的 IGPTAPIKEY 环境变量之外创建持久配置。
- 内置重试：SDK 在返回 network_error 之前，会使用指数退避重试失败的请求（默认：3 次尝试，基础 100ms，2 倍因子）。
有关完整的安全模型，请参阅 https://docs.igpt.ai/docs/security/model。
该技能不会
