{"id":"261bd937-c22a-40b2-81b5-034b2dcf6090","entityType":"agent","slug":"clawhub-sammy-spk-igpt-email-intelligence","name":"iGPT Email Intelligence","canonicalUrl":"https://www.xpersona.co/agent/clawhub-sammy-spk-igpt-email-intelligence","canonicalPath":"/agent/clawhub-sammy-spk-igpt-email-intelligence","generatedAt":"2026-10-12T12:02:49.585Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-12T01:56:37.869Z","emptyReason":null},"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 hist... Skill: iGPT Email Intelligence Owner: sammy-spk Summary: 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 hist... Tags: ai-agents:1.0.0, context:1.0.0, email:1.0.0, gmail:1.0.0, intelligence:1.0.0, latest:1.0.2 Version history: v1.0.2 | 2026-02-19T12:02:29.032Z | user Version 1.0.2 - Removed the sample file SKILL (","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 959 downloads reported by the source. Last updated 10/12/2026.","installCommand":"clawhub skill install s175ewjj72r9z2r6h79a2h1wah885twq:igpt-email-intelligence","sourceUrl":"https://clawhub.ai/sammy-spk/igpt-email-intelligence","homepage":"https://clawhub.ai/sammy-spk/skills/igpt-email-intelligence","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/sammy-spk/igpt-email-intelligence","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/sammy-spk/skills/igpt-email-intelligence","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"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 hist..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:56:37.869Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:56:37.869Z","emptyReason":null},"stars":null,"forks":null,"downloads":959,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.2","tractionLabel":"959 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-12T01:56:37.805Z","emptyReason":null},"lastUpdatedAt":"2026-10-12T01:56:37.869Z","lastCrawledAt":"2026-10-12T01:56:37.805Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-13T01:56:37.805Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.2","createdAt":"2026-02-19T12:02:29.032Z","changelog":"Version 1.0.2 - Removed the sample file SKILL (1).md from the repository. - No user-facing functionality changes; documentation and core features remain unchanged.","fileCount":2,"zipByteSize":4059},{"version":"1.0.1","createdAt":"2026-02-19T09:26:07.865Z","changelog":"- Added new SKILL.md file with enhanced security, privacy, and endpoint documentation. - Updated metadata with explicit required environment variables and config examples. - Clarified difference between this skill (retrieval) and igpt-email-ask (reasoning/analysis). - Improved and reorganized usage instructions, setup, and error handling sections. - Removed Skill.md and igpt-email-ask-SKILL.md; standardized file naming and documentation layout.","fileCount":3,"zipByteSize":8255},{"version":"1.0.0","createdAt":"2026-02-18T12:14:31.953Z","changelog":"Initial release. Adds email search and ask capabilities for AI agents via iGPT's context engine.","fileCount":3,"zipByteSize":6687}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s175ewjj72r9z2r6h79a2h1wah885twq:igpt-email-intelligence","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T12:02:49.584Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-sammy-spk-igpt-email-intelligence/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-12T01:56:37.869Z","emptyReason":null},"readme":"Skill: iGPT Email Intelligence\n\nOwner: sammy-spk\n\nSummary: 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 hist...\n\nTags: ai-agents:1.0.0, context:1.0.0, email:1.0.0, gmail:1.0.0, intelligence:1.0.0, latest:1.0.2\n\nVersion history:\n\nv1.0.2 | 2026-02-19T12:02:29.032Z | user\n\nVersion 1.0.2\n\n- Removed the sample file SKILL (1).md from the repository.\n- No user-facing functionality changes; documentation and core features remain unchanged.\n\nv1.0.1 | 2026-02-19T09:26:07.865Z | user\n\n- Added new SKILL.md file with enhanced security, privacy, and endpoint documentation.\n- Updated metadata with explicit required environment variables and config examples.\n- Clarified difference between this skill (retrieval) and igpt-email-ask (reasoning/analysis).\n- Improved and reorganized usage instructions, setup, and error handling sections.\n- Removed Skill.md and igpt-email-ask-SKILL.md; standardized file naming and documentation layout.\n\nv1.0.0 | 2026-02-18T12:14:31.953Z | user\n\nInitial release. Adds email search and ask capabilities for AI agents via iGPT's context engine.\n\nArchive index:\n\nArchive v1.0.2: 2 files, 4059 bytes\n\nFiles: SKILL.md (8926b), _meta.json (142b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: igpt-email-search\ndescription: >\n  Secure, per-user-isolated semantic email search via the iGPT API. Hybrid semantic + keyword\n  retrieval across a user's full Gmail, Outlook, or IMAP inbox history — no shell access, no\n  filesystem access, API-key scoped only. Returns relevant messages and threads ranked by meaning,\n  not just keyword overlap. Use when the user needs to find specific emails, threads, or\n  conversations by topic, participant, date range, or content. Retrieval only — for reasoning,\n  summaries, or structured extraction, use the companion skill igpt-email-ask.\nhomepage: https://igpt.ai/hub/playground/\nmetadata: {\"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\"]}\n---\n\n# iGPT Email Search\n\nSearch a user's email by meaning, not just keywords. Hybrid semantic + keyword retrieval across their entire inbox history.\n\n## What This Skill Does\n\nThis skill queries iGPT's `recall/search` endpoint to find relevant emails and threads from a user's connected inbox. The search engine:\n\n- Combines semantic vector search (understands meaning) with keyword matching (catches exact terms)\n- Searches across the user's full indexed email history (not limited to 90 days like some providers)\n- Supports date range filtering for time-bounded queries\n- Returns ranked results with relevance scoring\n- Includes attachment references when present\n\nThis 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`](https://clawhub.ai/skills/igpt-email-ask) — the companion skill that runs iGPT's Context Engine for analysis, summarization, and structured extraction.\n\n## When to Use This Skill\n\n- Find emails about a specific topic, project, or person\n- Locate threads within a date range\n- Retrieve raw email content for further processing\n- Feed email context into another tool or agent step\n- Check what was discussed about a topic before taking action\n- Pull recent correspondence with a specific contact or company\n\n## When to Use igpt-email-ask Instead\n\nIf 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`](https://clawhub.ai/skills/igpt-email-ask), not search.\n\nRule of thumb: if the prompt is a question, use ask. If the prompt is a lookup, use search.\n\n## Prerequisites\n\n1. An iGPT API key (get one at https://igpt.ai/hub/apikeys/)\n2. A connected email datasource — the user must have completed OAuth authorization via `connectors/authorize` before search will return results\n3. Python >= 3.8 with the `igptai` package installed\n\n## Setup\n\n```bash\npip install igptai\n```\n\nSet your API key as an environment variable:\n\n```bash\nexport IGPT_API_KEY=\"your-api-key-here\"\n```\n\n## Usage\n\n### Basic: Search by topic\n\n```python\nfrom igptai import IGPT\nimport os\n\nigpt = IGPT(api_key=os.environ[\"IGPT_API_KEY\"], user=\"user_123\")\n\nresults = igpt.recall.search(query=\"board meeting notes\")\nprint(results)\n```\n\nReturns a ranked list of relevant emails and threads matching the query, ordered by relevance.\n\n### Search with date range\n\nNarrow results to a specific time window:\n\n```python\nresults = igpt.recall.search(\n    query=\"budget allocation\",\n    date_from=\"2026-01-01\",\n    date_to=\"2026-01-31\"\n)\nprint(results)\n```\n\n### Limit number of results\n\n```python\nresults = igpt.recall.search(\n    query=\"partnership proposals\",\n    max_results=10\n)\nprint(results)\n```\n\n### Search for a specific person's emails\n\nThe semantic engine understands participant context:\n\n```python\nresults = igpt.recall.search(\n    query=\"emails from Sarah about the product launch\",\n    date_from=\"2026-01-01\"\n)\nprint(results)\n```\n\n### Combine with ask for a two-step workflow\n\nA common pattern: search first to see what's there, then ask for analysis:\n\n```python\n# Step 1: Find relevant threads\nresults = igpt.recall.search(\n    query=\"Acme Corp contract negotiation\",\n    max_results=20\n)\nprint(f\"Found {len(results)} relevant threads\")\n\n# Step 2: Ask for structured analysis\nanalysis = igpt.recall.ask(\n    input=\"Summarize the current status of the Acme Corp contract negotiation. What are the open issues and who owns them?\",\n    output_format=\"json\"\n)\nprint(analysis)\n```\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| query | string | Yes | Search query. Supports natural language (semantic) and exact terms (keyword). |\n| user | string | Yes (or set in constructor) | Unique user identifier scoping the query to their connected data. |\n| date_from | string | No | Start date filter in YYYY-MM-DD format. |\n| date_to | string | No | End date filter in YYYY-MM-DD format. |\n| max_results | integer | No | Maximum number of results to return. |\n\n## Error Handling\n\nThe SDK uses a no-throw pattern. Errors are returned as values, not exceptions:\n\n```python\nresults = igpt.recall.search(query=\"Q4 planning\")\n\nif isinstance(results, dict) and results.get(\"error\"):\n    error = results[\"error\"]\n    if error == \"auth\":\n        print(\"Check your API key\")\n    elif error == \"params\":\n        print(\"Check your request parameters\")\n    elif error == \"network_error\":\n        print(\"Network issue, retry\")\nelse:\n    for result in results:\n        print(result)\n```\n\n## External Endpoints\n\nThis skill communicates exclusively with:\n\n- `https://api.igpt.ai/v1/recall/search` — the search endpoint\n- `https://api.igpt.ai/v1/connectors/authorize` — only during initial datasource connection setup\n\nNo 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.\n\n## Security & Privacy\n\n- **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.\n- **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.\n- **OAuth read-only**: The email datasource connection uses OAuth with read-only scopes. The skill does not send, modify, or delete emails.\n- **No data retention**: Prompts are discarded after execution. Memory is reconstructed on-demand, not stored.\n- **Transport encryption**: All communication occurs over HTTPS. No plaintext endpoints.\n- **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.\n\nFor the full security model, see https://docs.igpt.ai/docs/security/model.\n\n## How It Differs from Basic Email Search\n\n| Basic email/Gmail search | iGPT Email Search |\n|---|---|\n| Keyword matching only | Semantic + keyword hybrid |\n| Misses related content using different words | Understands meaning, finds conceptually related emails |\n| Limited to Gmail's search operators | Natural language queries work |\n| Provider-specific (Gmail OR Outlook) | Searches across all connected providers |\n| Often limited history (Nylas: 90 days) | Full email history indexed |\n| Returns raw MIME data | Returns clean, structured results |\n\n## Example Queries\n\nThese all work as natural language:\n\n- `\"board meeting notes\"` — finds emails about board meetings even if they don't contain that exact phrase\n- `\"emails about the product launch timeline\"` — semantic understanding of the topic\n- `\"anything from legal about compliance\"` — understands department and topic context\n- `\"invoices from Q4 2025\"` — combines topic with implicit date context\n- `\"conversations where deadlines were mentioned\"` — conceptual search\n\n## Companion Skills\n\n| Skill | What it does | When to use it |\n|-------|-------------|----------------|\n| **[igpt-email-ask](https://clawhub.ai/skills/igpt-email-ask)** | Reasoning, summaries, structured extraction, sentiment | When you need answers, not just results |\n| **igpt-email-search** (this skill) | Hybrid semantic + keyword retrieval | When you need to find and retrieve emails |\n\nBoth skills use the same `IGPT_API_KEY` and connected datasources. Install both for the full search → analyze workflow.\n\n## Resources\n\n- **Get API Key**: https://igpt.ai/hub/apikeys/\n- **Documentation**: https://docs.igpt.ai\n- **API Reference**: https://docs.igpt.ai/docs/api-reference/search\n- **Playground**: https://igpt.ai/hub/playground/\n- **Python SDK**: https://pypi.org/project/igptai/\n- **Node.js SDK**: https://www.npmjs.com/package/igptai\n- **GitHub**: https://github.com/igptai/igptai-python\n\nFile v1.0.2:_meta.json\n\n{\n  \"ownerId\": \"kn796exy66shzmrken55danra181d3fa\",\n  \"slug\": \"igpt-email-intelligence\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1771502549032\n}\n\nArchive v1.0.1: 3 files, 8255 bytes\n\nFiles: SKILL (1).md (10505b), SKILL.md (9108b), _meta.json (142b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: igpt-email-search\ndescription: >\n  Secure, per-user-isolated semantic email search via the iGPT API. Hybrid semantic + keyword\n  retrieval across a user's full Gmail, Outlook, or IMAP inbox history — no shell access, no\n  filesystem access, API-key scoped only. Returns relevant messages and threads ranked by meaning,\n  not just keyword overlap. Use when the user needs to find specific emails, threads, or\n  conversations by topic, participant, date range, or content. Retrieval only — for reasoning,\n  summaries, or structured extraction, use the companion skill igpt-email-ask.\nmetadata:\n  clawdbot:\n    config:\n      requiredEnv:\n        - IGPT_API_KEY\n      primaryCredential: IGPT_API_KEY\n      example: |\n        config = {\n          env = {\n            IGPT_API_KEY = \"<your-api-key-from-igpt.ai/hub/apikeys>\";\n          };\n        };\n  author: igptai\n  homepage: https://igpt.ai/hub/playground/\n  version: \"1.0.0\"\n  license: MIT\n  tags:\n    - email\n    - search\n    - retrieval\n    - semantic-search\n    - context\n    - productivity\n---\n\n# iGPT Email Search\n\nSearch a user's email by meaning, not just keywords. Hybrid semantic + keyword retrieval across their entire inbox history.\n\n## What This Skill Does\n\nThis skill queries iGPT's `recall/search` endpoint to find relevant emails and threads from a user's connected inbox. The search engine:\n\n- Combines semantic vector search (understands meaning) with keyword matching (catches exact terms)\n- Searches across the user's full indexed email history (not limited to 90 days like some providers)\n- Supports date range filtering for time-bounded queries\n- Returns ranked results with relevance scoring\n- Includes attachment references when present\n\nThis 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`](https://clawhub.ai/skills/igpt-email-ask) — the companion skill that runs iGPT's Context Engine for analysis, summarization, and structured extraction.\n\n## When to Use This Skill\n\n- Find emails about a specific topic, project, or person\n- Locate threads within a date range\n- Retrieve raw email content for further processing\n- Feed email context into another tool or agent step\n- Check what was discussed about a topic before taking action\n- Pull recent correspondence with a specific contact or company\n\n## When to Use igpt-email-ask Instead\n\nIf 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`](https://clawhub.ai/skills/igpt-email-ask), not search.\n\nRule of thumb: if the prompt is a question, use ask. If the prompt is a lookup, use search.\n\n## Prerequisites\n\n1. An iGPT API key (get one at https://igpt.ai/hub/apikeys/)\n2. A connected email datasource — the user must have completed OAuth authorization via `connectors/authorize` before search will return results\n3. Python >= 3.8 with the `igptai` package installed\n\n## Setup\n\n```bash\npip install igptai\n```\n\nSet your API key as an environment variable:\n\n```bash\nexport IGPT_API_KEY=\"your-api-key-here\"\n```\n\n## Usage\n\n### Basic: Search by topic\n\n```python\nfrom igptai import IGPT\nimport os\n\nigpt = IGPT(api_key=os.environ[\"IGPT_API_KEY\"], user=\"user_123\")\n\nresults = igpt.recall.search(query=\"board meeting notes\")\nprint(results)\n```\n\nReturns a ranked list of relevant emails and threads matching the query, ordered by relevance.\n\n### Search with date range\n\nNarrow results to a specific time window:\n\n```python\nresults = igpt.recall.search(\n    query=\"budget allocation\",\n    date_from=\"2026-01-01\",\n    date_to=\"2026-01-31\"\n)\nprint(results)\n```\n\n### Limit number of results\n\n```python\nresults = igpt.recall.search(\n    query=\"partnership proposals\",\n    max_results=10\n)\nprint(results)\n```\n\n### Search for a specific person's emails\n\nThe semantic engine understands participant context:\n\n```python\nresults = igpt.recall.search(\n    query=\"emails from Sarah about the product launch\",\n    date_from=\"2026-01-01\"\n)\nprint(results)\n```\n\n### Combine with ask for a two-step workflow\n\nA common pattern: search first to see what's there, then ask for analysis:\n\n```python\n# Step 1: Find relevant threads\nresults = igpt.recall.search(\n    query=\"Acme Corp contract negotiation\",\n    max_results=20\n)\nprint(f\"Found {len(results)} relevant threads\")\n\n# Step 2: Ask for structured analysis\nanalysis = igpt.recall.ask(\n    input=\"Summarize the current status of the Acme Corp contract negotiation. What are the open issues and who owns them?\",\n    output_format=\"json\"\n)\nprint(analysis)\n```\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| query | string | Yes | Search query. Supports natural language (semantic) and exact terms (keyword). |\n| user | string | Yes (or set in constructor) | Unique user identifier scoping the query to their connected data. |\n| date_from | string | No | Start date filter in YYYY-MM-DD format. |\n| date_to | string | No | End date filter in YYYY-MM-DD format. |\n| max_results | integer | No | Maximum number of results to return. |\n\n## Error Handling\n\nThe SDK uses a no-throw pattern. Errors are returned as values, not exceptions:\n\n```python\nresults = igpt.recall.search(query=\"Q4 planning\")\n\nif isinstance(results, dict) and results.get(\"error\"):\n    error = results[\"error\"]\n    if error == \"auth\":\n        print(\"Check your API key\")\n    elif error == \"params\":\n        print(\"Check your request parameters\")\n    elif error == \"network_error\":\n        print(\"Network issue, retry\")\nelse:\n    for result in results:\n        print(result)\n```\n\n## External Endpoints\n\nThis skill communicates exclusively with:\n\n- `https://api.igpt.ai/v1/recall/search` — the search endpoint\n- `https://api.igpt.ai/v1/connectors/authorize` — only during initial datasource connection setup\n\nNo 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.\n\n## Security & Privacy\n\n- **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.\n- **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.\n- **OAuth read-only**: The email datasource connection uses OAuth with read-only scopes. The skill does not send, modify, or delete emails.\n- **No data retention**: Prompts are discarded after execution. Memory is reconstructed on-demand, not stored.\n- **Transport encryption**: All communication occurs over HTTPS. No plaintext endpoints.\n- **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.\n\nFor the full security model, see https://docs.igpt.ai/docs/security/model.\n\n## How It Differs from Basic Email Search\n\n| Basic email/Gmail search | iGPT Email Search |\n|---|---|\n| Keyword matching only | Semantic + keyword hybrid |\n| Misses related content using different words | Understands meaning, finds conceptually related emails |\n| Limited to Gmail's search operators | Natural language queries work |\n| Provider-specific (Gmail OR Outlook) | Searches across all connected providers |\n| Often limited history (Nylas: 90 days) | Full email history indexed |\n| Returns raw MIME data | Returns clean, structured results |\n\n## Example Queries\n\nThese all work as natural language:\n\n- `\"board meeting notes\"` — finds emails about board meetings even if they don't contain that exact phrase\n- `\"emails about the product launch timeline\"` — semantic understanding of the topic\n- `\"anything from legal about compliance\"` — understands department and topic context\n- `\"invoices from Q4 2025\"` — combines topic with implicit date context\n- `\"conversations where deadlines were mentioned\"` — conceptual search\n\n## Companion Skills\n\n| Skill | What it does | When to use it |\n|-------|-------------|----------------|\n| **[igpt-email-ask](https://clawhub.ai/skills/igpt-email-ask)** | Reasoning, summaries, structured extraction, sentiment | When you need answers, not just results |\n| **igpt-email-search** (this skill) | Hybrid semantic + keyword retrieval | When you need to find and retrieve emails |\n\nBoth skills use the same `IGPT_API_KEY` and connected datasources. Install both for the full search → analyze workflow.\n\n## Resources\n\n- **Get API Key**: https://igpt.ai/hub/apikeys/\n- **Documentation**: https://docs.igpt.ai\n- **API Reference**: https://docs.igpt.ai/docs/api-reference/search\n- **Playground**: https://igpt.ai/hub/playground/\n- **Python SDK**: https://pypi.org/project/igptai/\n- **Node.js SDK**: https://www.npmjs.com/package/igptai\n- **GitHub**: https://github.com/igptai/igptai-python\n\nFile v1.0.1:_meta.json\n\n{\n  \"ownerId\": \"kn796exy66shzmrken55danra181d3fa\",\n  \"slug\": \"igpt-email-intelligence\",\n  \"version\": \"1.0.1\",\n  \"publishedAt\": 1771493167865\n}\n\nFile v1.0.1:SKILL (1).md\n\n---\nname: igpt-email-ask\ndescription: >\n  Secure, per-user-isolated email reasoning and analysis via the iGPT Context Engine API.\n  Summarizes threads, extracts tasks and decisions, detects sentiment, and reasons across multiple\n  conversations — no shell access, no filesystem access, API-key scoped only. Supports structured\n  JSON output with schema validation and streaming (SSE). Use when the user needs analysis,\n  summaries, structured data extraction, or answers that require understanding email context.\n  For retrieval/lookup only, use the companion skill igpt-email-search.\nmetadata:\n  clawdbot:\n    config:\n      requiredEnv:\n        - IGPT_API_KEY\n      primaryCredential: IGPT_API_KEY\n      example: |\n        config = {\n          env = {\n            IGPT_API_KEY = \"<your-api-key-from-igpt.ai/hub/apikeys>\";\n          };\n        };\n  author: igptai\n  homepage: https://igpt.ai/hub/playground/\n  version: \"1.0.0\"\n  license: MIT\n  tags:\n    - email\n    - analysis\n    - reasoning\n    - summarization\n    - context-engine\n    - productivity\n---\n\n# iGPT Email Ask\n\nAsk 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.\n\n## What This Skill Does\n\nThis skill queries iGPT's `recall/ask` endpoint to generate answers grounded in a user's connected email data. Unlike basic retrieval, the Context Engine:\n\n- Reconstructs full conversation threads across replies, forwards, and CCs\n- Identifies who decided what, who owns what, and what's still open\n- Extracts structured data (tasks, deadlines, contacts, risks) from unstructured email\n- Supports multiple quality tiers for different complexity levels\n- Returns text, JSON, or schema-validated structured output\n- Supports streaming (SSE) for real-time responses\n\nThis is the reasoning layer. It understands and analyzes email content. For finding and retrieving raw emails, use [`igpt-email-search`](https://clawhub.ai/skills/igpt-email-search) — the companion skill for hybrid semantic + keyword retrieval.\n\n## When to Use This Skill\n\n- Summarize what happened in a thread or across threads\n- Extract action items, decisions, or open questions\n- Analyze sentiment or risk in deal/customer threads\n- Answer questions that require understanding context across multiple emails\n- Generate structured data from email content (JSON, schema-validated)\n- Prepare briefings before meetings based on recent correspondence\n\n## When to Use igpt-email-search Instead\n\nIf you only need to find and retrieve emails without analysis — use [`igpt-email-search`](https://clawhub.ai/skills/igpt-email-search). Search returns raw results. Ask returns reasoned answers.\n\nRule of thumb: if the prompt is a question, use ask. If the prompt is a lookup, use search.\n\n## Prerequisites\n\n1. An iGPT API key (get one at https://igpt.ai/hub/apikeys/)\n2. A connected email datasource — the user must have completed OAuth authorization via `connectors/authorize`\n3. Python >= 3.8 with the `igptai` package installed\n\n## Setup\n\n```bash\npip install igptai\n```\n\nSet your API key as an environment variable:\n\n```bash\nexport IGPT_API_KEY=\"your-api-key-here\"\n```\n\n## Usage\n\n### Basic: Ask a question\n\n```python\nfrom igptai import IGPT\nimport os\n\nigpt = IGPT(api_key=os.environ[\"IGPT_API_KEY\"], user=\"user_123\")\n\nresponse = igpt.recall.ask(\n    input=\"Summarize key risks, decisions, and next steps from this week's meetings.\"\n)\nprint(response)\n```\n\n### Get structured JSON output\n\n```python\nresponse = igpt.recall.ask(\n    input=\"Open action items from this week\",\n    quality=\"cef-1-normal\",\n    output_format={\n        \"strict\": True,\n        \"schema\": {\n            \"type\": \"object\",\n            \"properties\": {\n                \"action_items\": {\n                    \"type\": \"array\",\n                    \"items\": {\n                        \"type\": \"object\",\n                        \"properties\": {\n                            \"title\": {\"type\": \"string\"},\n                            \"owner\": {\"type\": \"string\"},\n                            \"due_date\": {\"type\": \"string\"}\n                        }\n                    }\n                }\n            }\n        }\n    }\n)\nprint(response)\n```\n\nExample response:\n\n```json\n{\n    \"action_items\": [\n        {\n            \"title\": \"Approve revised Q1 budget allocation\",\n            \"owner\": \"Dvir Ben-Aroya\",\n            \"due_date\": \"2026-01-15\"\n        },\n        {\n            \"title\": \"Approve final FY2026 strategic priorities\",\n            \"owner\": \"Board of Directors\",\n            \"due_date\": \"2026-01-31\"\n        }\n    ]\n}\n```\n\n### Use quality tiers\n\niGPT's Context Engine has multiple quality tiers for different complexity levels:\n\n```python\n# Normal: fast, good for straightforward questions\nresponse = igpt.recall.ask(\n    input=\"When is my next meeting with Acme Corp?\",\n    quality=\"cef-1-normal\"\n)\n\n# High: deeper reasoning, better for complex multi-thread analysis\nresponse = igpt.recall.ask(\n    input=\"What is the current negotiation status with Acme Corp and what leverage do we have?\",\n    quality=\"cef-1-high\"\n)\n```\n\n### Stream responses\n\nFor real-time output in interactive contexts:\n\n```python\nstream = igpt.recall.ask(\n    input=\"Walk me through the timeline of the Acme deal from first contact to now.\",\n    stream=True\n)\n\nfor chunk in stream:\n    if isinstance(chunk, dict) and chunk.get(\"error\"):\n        print(\"Stream error:\", chunk)\n        break\n    print(chunk, end=\"\", flush=True)\n```\n\nStreaming is resilient: if the connection breaks, the iterator yields an error chunk and finishes rather than throwing.\n\n### Two-step workflow with search\n\nSearch first to scope what's available, then ask for analysis:\n\n```python\n# Step 1: Find relevant threads\nresults = igpt.recall.search(\n    query=\"Acme Corp contract negotiation\",\n    max_results=20\n)\nprint(f\"Found {len(results)} relevant threads\")\n\n# Step 2: Ask for structured analysis\nanalysis = igpt.recall.ask(\n    input=\"Summarize the current status of the Acme Corp contract negotiation. What are the open issues and who owns them?\",\n    output_format=\"json\"\n)\nprint(analysis)\n```\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| input | string | Yes | The prompt or question to ask. |\n| user | string | Yes (or set in constructor) | Unique user identifier scoping the query to their connected data. |\n| stream | boolean | No (default: false) | If true, returns an SSE stream of response chunks. |\n| quality | string | No | Context Engine quality tier: `\"cef-1-normal\"` or `\"cef-1-high\"`. |\n| output_format | string or object | No | `\"text\"` (default), `\"json\"`, or `{ \"schema\": <JSON Schema> }` for validated structured output. |\n\n## Error Handling\n\nThe SDK uses a no-throw pattern. Errors are returned as values, not exceptions:\n\n```python\nresponse = igpt.recall.ask(input=\"What happened in yesterday's board meeting?\")\n\nif isinstance(response, dict) and response.get(\"error\"):\n    error = response[\"error\"]\n    if error == \"auth\":\n        print(\"Check your API key\")\n    elif error == \"params\":\n        print(\"Check your request parameters\")\n    elif error == \"network_error\":\n        print(\"Network issue, retry\")\nelse:\n    print(response)\n```\n\n## External Endpoints\n\nThis skill communicates exclusively with:\n\n- `https://api.igpt.ai/v1/recall/ask` — the reasoning endpoint\n- `https://api.igpt.ai/v1/connectors/authorize` — only during initial datasource connection setup\n\nNo 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.\n\n## Security & Privacy\n\n- **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.\n- **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.\n- **OAuth read-only**: The email datasource connection uses OAuth with read-only scopes. The skill does not send, modify, or delete emails.\n- **No data retention**: Prompts are discarded after execution. Memory is reconstructed on-demand, not stored.\n- **Transport encryption**: All communication occurs over HTTPS. No plaintext endpoints.\n- **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.\n\nFor the full security model, see https://docs.igpt.ai/docs/security/model.\n\n## What This Skill Does NOT Do\n\n- Does not send, modify, forward, or delete emails\n- Does not access the filesystem or execute shell commands\n- Does not install persistent services or scheduled tasks\n- Does not contact endpoints other than `api.igpt.ai`\n- Does not store API keys or OAuth tokens outside the environment variable\n\n## Example Questions\n\nThese all work as natural language prompts:\n\n- `\"Summarize key risks from this week's email threads\"` — cross-thread analysis\n- `\"What are the open action items from yesterday's board meeting?\"` — task extraction\n- `\"What's the current status of the Acme deal?\"` — deal intelligence\n- `\"Who owns the budget approval and when is it due?\"` — ownership and deadline extraction\n- `\"Are there any threads where tone has shifted negatively in the last 7 days?\"` — sentiment analysis\n- `\"Generate a briefing for my meeting with Sarah tomorrow\"` — meeting prep\n\n## Companion Skills\n\n| Skill | What it does | When to use it |\n|-------|-------------|----------------|\n| **igpt-email-ask** (this skill) | Reasoning, summaries, structured extraction, sentiment | When you need answers and analysis |\n| **[igpt-email-search](https://clawhub.ai/skills/igpt-email-search)** | Hybrid semantic + keyword retrieval | When you need to find and retrieve emails |\n\nBoth skills use the same `IGPT_API_KEY` and connected datasources. Install both for the full search → analyze workflow.\n\n## Resources\n\n- **Get API Key**: https://igpt.ai/hub/apikeys/\n- **Documentation**: https://docs.igpt.ai\n- **API Reference**: https://docs.igpt.ai/docs/api-reference/ask\n- **Playground**: https://igpt.ai/hub/playground/\n- **Python SDK**: https://pypi.org/project/igptai/\n- **Node.js SDK**: https://www.npmjs.com/package/igptai\n- **GitHub**: https://github.com/igptai/igptai-python\n\nArchive v1.0.0: 3 files, 6687 bytes\n\nFiles: igpt-email-ask-SKILL.md (8385b), Skill.md (6592b), _meta.json (142b)\n\nFile v1.0.0:Skill.md\n\n```yaml\nname: igpt-email-search\ndescription: >\n  Search a user's email history using semantic + keyword hybrid search. Returns relevant messages\n  and threads ranked by meaning, not just keyword overlap. Powered by iGPT's Context Engine,\n  which indexes entire email histories across Gmail, Outlook, and IMAP providers.\n  Use this skill when you need to find specific emails, threads, or conversations by topic,\n  participant, date range, or content. Unlike basic email search, this understands what you\n  mean, not just what you typed. Returns retrieval results only (no reasoning layer).\n  For answers and analysis, use igpt-email-ask instead.\n```\n\n# iGPT Email Search\n\nSearch a user's email by meaning, not just keywords. Hybrid semantic + keyword retrieval across their entire inbox history.\n\n## What This Skill Does\n\nThis skill queries iGPT's `recall/search` endpoint to find relevant emails and threads from a user's connected inbox. The search engine:\n\n1. Combines semantic vector search (understands meaning) with keyword matching (catches exact terms)\n2. Searches across the user's full indexed email history (not limited to 90 days like some providers)\n3. Supports date range filtering for time-bounded queries\n4. Returns ranked results with relevance scoring\n5. Includes attachment references when present\n\nThis 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`.\n\n## When to Use This Skill\n\n- Find emails about a specific topic, project, or person\n- Locate threads within a date range\n- Retrieve raw email content for further processing\n- Feed email context into another tool or agent step\n- Check what was discussed about a topic before taking action\n- Pull recent correspondence with a specific contact or company\n\n## When to Use `igpt-email-ask` Instead\n\nIf you need any of these, use the ask skill, not search:\n\n- Summarized or synthesized answers\n- Structured data extraction (tasks, decisions, contacts)\n- Sentiment analysis\n- Reasoning across multiple threads\n- Questions that require understanding, not just finding\n\n**Rule of thumb:** If your prompt is a question, use ask. If your prompt is a lookup, use search.\n\n## Prerequisites\n\n- An iGPT API key (get one at https://igpt.ai/hub/apikeys/)\n- A connected email datasource (user must have completed OAuth authorization via `connectors/authorize`)\n- Python >= 3.8 with `igptai` package installed\n\n## Setup\n\n```bash\npip install igptai\n```\n\nSet your API key as an environment variable:\n\n```bash\nexport IGPT_API_KEY=\"your-api-key-here\"\n```\n\n## Usage\n\n### Basic: Search by topic\n\n```python\nfrom igptai import IGPT\nimport os\n\nigpt = IGPT(api_key=os.environ[\"IGPT_API_KEY\"], user=\"user_123\")\n\nresults = igpt.recall.search(query=\"board meeting notes\")\nprint(results)\n```\n\nReturns a ranked list of relevant emails and threads matching the query, ordered by relevance.\n\n### Search with date range\n\nNarrow results to a specific time window:\n\n```python\nresults = igpt.recall.search(\n    query=\"budget allocation\",\n    date_from=\"2026-01-01\",\n    date_to=\"2026-01-31\"\n)\nprint(results)\n```\n\n### Limit number of results\n\nControl how many results come back:\n\n```python\nresults = igpt.recall.search(\n    query=\"partnership proposals\",\n    max_results=10\n)\nprint(results)\n```\n\n### Search for a specific person's emails\n\nThe semantic engine understands participant context:\n\n```python\nresults = igpt.recall.search(\n    query=\"emails from Sarah about the product launch\",\n    date_from=\"2026-01-01\"\n)\nprint(results)\n```\n\n### Combine with ask for a two-step workflow\n\nA common pattern: search first to see what's there, then ask for analysis:\n\n```python\n# Step 1: Find relevant threads\nresults = igpt.recall.search(\n    query=\"Acme Corp contract negotiation\",\n    max_results=20\n)\nprint(f\"Found {len(results)} relevant threads\")\n\n# Step 2: Ask for structured analysis\nanalysis = igpt.recall.ask(\n    input=\"Summarize the current status of the Acme Corp contract negotiation. What are the open issues and who owns them?\",\n    output_format=\"json\"\n)\nprint(analysis)\n```\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string | Yes | Search query. Supports natural language (semantic) and exact terms (keyword). |\n| `user` | string | Yes (or set in constructor) | Unique user identifier scoping the query to their connected data |\n| `date_from` | string | No | Start date filter in `YYYY-MM-DD` format |\n| `date_to` | string | No | End date filter in `YYYY-MM-DD` format |\n| `max_results` | integer | No | Maximum number of results to return |\n\n## Error Handling\n\nSame no-throw pattern as all iGPT SDK methods:\n\n```python\nresults = igpt.recall.search(query=\"Q4 planning\")\n\nif isinstance(results, dict) and results.get(\"error\"):\n    error = results[\"error\"]\n    if error == \"auth\":\n        print(\"Check your API key\")\n    elif error == \"params\":\n        print(\"Check your request parameters\")\n    elif error == \"network_error\":\n        print(\"Network issue, retry\")\nelse:\n    for result in results:\n        print(result)\n```\n\n## How It Differs from Basic Email Search\n\n| Basic email/Gmail search | iGPT Email Search |\n|--------------------------|-------------------|\n| Keyword matching only | Semantic + keyword hybrid |\n| Misses related content that uses different words | Understands meaning and finds conceptually related emails |\n| Limited to Gmail's search operators | Natural language queries work |\n| Provider-specific (Gmail OR Outlook) | Searches across all connected providers |\n| Often limited history (Nylas: 90 days) | Full email history indexed |\n| Returns raw MIME data | Returns clean, structured results |\n\n## Example Queries\n\nThese all work as natural language:\n\n- `\"board meeting notes\"` — finds emails about board meetings even if they don't contain that exact phrase\n- `\"emails about the product launch timeline\"` — semantic understanding of the topic\n- `\"anything from legal about compliance\"` — understands department and topic context\n- `\"invoices from Q4 2025\"` — combines topic with implicit date context\n- `\"conversations where deadlines were mentioned\"` — conceptual search\n\n## Resources\n\n- Get API Key: https://igpt.ai/hub/apikeys/\n- Documentation: https://docs.igpt.ai\n- API Reference: https://docs.igpt.ai/docs/api-reference/search\n- Playground: https://igpt.ai/hub/playground/\n- Python SDK: https://pypi.org/project/igptai/\n- Node.js SDK: https://www.npmjs.com/package/igptai\n- GitHub: https://github.com/igptai/igptai-python\n\nFile v1.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn796exy66shzmrken55danra181d3fa\",\n  \"slug\": \"igpt-email-intelligence\",\n  \"version\": \"1.0.0\",\n  \"publishedAt\": 1771416871953\n}\n\nFile v1.0.0:igpt-email-ask-SKILL.md\n\n```yaml\nname: igpt-email-ask\ndescription: >\n  Ask natural language questions about a user's email history and get reasoning-ready answers with citations.\n  Powered by iGPT's Context Engine, which reconstructs full thread logic, participant roles, decisions,\n  sentiment, and action items from connected email accounts (Gmail, Outlook, IMAP).\n  Use this skill when you need to understand what happened in someone's email: summarize threads,\n  extract tasks, identify decisions, detect sentiment, find who owns what, or answer any question\n  that requires deep email context. Returns structured JSON or plain text with source citations.\n```\n\n# iGPT Email Ask\n\nAsk questions about a user's connected email in plain English. Get answers that understand full thread context, not just keyword matches.\n\n## What This Skill Does\n\nThis skill sends a natural language question to iGPT's `recall/ask` endpoint. iGPT's Context Engine then:\n\n1. Searches across the user's entire indexed email history\n2. Reconstructs full thread context (replies, forwards, CCs, the whole chain)\n3. Identifies participants, their roles, tone, and relationships\n4. Reasons over the content to produce a grounded answer\n5. Returns the answer with citations linking back to source messages\n\nThis is not a simple search. The engine understands conversation flow, decisions, ownership, deadlines, and sentiment across threads.\n\n## When to Use This Skill\n\n- Summarize what happened in a project, deal, or conversation\n- Extract action items, owners, and deadlines from threads\n- Identify who decided what and when\n- Detect sentiment or risk in customer/deal threads\n- Prepare briefings before meetings\n- Answer any question that requires understanding email context\n- Generate structured data (tasks, contacts, decisions) from unstructured email\n\n## Prerequisites\n\n- An iGPT API key (get one at https://igpt.ai/hub/apikeys/)\n- A connected email datasource (user must have completed OAuth authorization via `connectors/authorize`)\n- Python >= 3.8 with `igptai` package installed\n\n## Setup\n\n```bash\npip install igptai\n```\n\nSet your API key as an environment variable:\n\n```bash\nexport IGPT_API_KEY=\"your-api-key-here\"\n```\n\n## Usage\n\n### Basic: Ask a question in plain English\n\n```python\nfrom igptai import IGPT\nimport os\n\nigpt = IGPT(api_key=os.environ[\"IGPT_API_KEY\"], user=\"user_123\")\n\nresponse = igpt.recall.ask(\n    input=\"What are the open action items from this week's meetings?\"\n)\nprint(response)\n```\n\nThe engine returns a text answer grounded in the user's actual email content, with citations pointing to the specific messages that informed the answer.\n\n### Structured JSON output\n\nWhen you need machine-readable data (for agents, automations, dashboards), request JSON:\n\n```python\nresponse = igpt.recall.ask(\n    input=\"List all action items from yesterday's board meeting.\",\n    output_format=\"json\"\n)\nprint(response)\n```\n\n### Enforced schema output\n\nFor predictable, validated structure, pass a JSON Schema. The engine will conform its output exactly to your schema:\n\n```python\ntask_schema = {\n    \"strict\": True,\n    \"schema\": {\n        \"type\": \"object\",\n        \"properties\": {\n            \"action_items\": {\n                \"type\": \"array\",\n                \"description\": \"Action items extracted from email threads\",\n                \"items\": {\n                    \"type\": \"object\",\n                    \"properties\": {\n                        \"title\": {\"type\": \"string\", \"description\": \"Short summary of the task\"},\n                        \"owner\": {\"type\": \"string\", \"description\": \"Person responsible\"},\n                        \"due_date\": {\"type\": \"string\", \"format\": \"date\", \"description\": \"Deadline if mentioned\"},\n                        \"status\": {\"type\": \"string\", \"description\": \"Current status: open, in_progress, done\"},\n                        \"source_thread\": {\"type\": \"string\", \"description\": \"Subject line of the source email thread\"}\n                    },\n                    \"required\": [\"title\", \"owner\"],\n                    \"additionalProperties\": False\n                }\n            }\n        },\n        \"required\": [\"action_items\"],\n        \"additionalProperties\": False\n    }\n}\n\nresponse = igpt.recall.ask(\n    input=\"Open action items from this week across all threads\",\n    output_format=task_schema,\n    quality=\"cef-1-normal\"\n)\nprint(response)\n```\n\nExample response:\n\n```json\n{\n  \"action_items\": [\n    {\n      \"title\": \"Approve revised Q1 budget allocation\",\n      \"owner\": \"Dvir Ben-Aroya\",\n      \"due_date\": \"2026-01-15\",\n      \"status\": \"open\",\n      \"source_thread\": \"Re: Q1 Budget Review - Final Numbers\"\n    },\n    {\n      \"title\": \"Send updated contract to legal\",\n      \"owner\": \"Sarah Chen\",\n      \"due_date\": \"2026-01-10\",\n      \"status\": \"in_progress\",\n      \"source_thread\": \"Acme Corp Partnership Agreement\"\n    }\n  ]\n}\n```\n\n### Streaming responses\n\nFor real-time UI output (chat interfaces, live dashboards):\n\n```python\nstream = igpt.recall.ask(\n    input=\"Summarize the status of the Acme deal.\",\n    stream=True\n)\n\nfor chunk in stream:\n    if isinstance(chunk, dict) and chunk.get(\"error\"):\n        print(\"Error:\", chunk)\n        break\n    print(chunk, end=\"\", flush=True)\n```\n\n### Quality tiers\n\nControl the depth of reasoning per request using CEF (Context Engine Framework) tiers:\n\n- `cef-1-normal` — Fast, cost-effective. Good for summaries, simple lookups, everyday automation.\n- `cef-1-high` — More precision. Better for complex threads, long context, nuanced questions.\n- `cef-1-reasoning` — Deep multi-step analysis. Use for strategic questions, risk assessment, relationship mapping.\n\n```python\nresponse = igpt.recall.ask(\n    input=\"Analyze sentiment trajectory across all threads with Acme Corp over the past month. Are they at risk of churning?\",\n    quality=\"cef-1-reasoning\"\n)\n```\n\n## Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `input` | string | Yes | The question to ask in natural language |\n| `user` | string | Yes (or set in constructor) | Unique user identifier scoping the query to their connected data |\n| `stream` | boolean | No (default: false) | If true, returns server-sent events for real-time output |\n| `quality` | string | No | CEF tier: `\"cef-1-normal\"`, `\"cef-1-high\"`, or `\"cef-1-reasoning\"` |\n| `output_format` | string or object | No (default: \"text\") | `\"text\"`, `\"json\"`, or `{\"schema\": <JSON Schema>}` for structured output |\n\n## Error Handling\n\nThe SDK uses a no-throw design. Errors are returned as objects, not exceptions:\n\n```python\nresponse = igpt.recall.ask(input=\"What happened with the Acme deal?\")\n\nif isinstance(response, dict) and response.get(\"error\"):\n    error = response[\"error\"]\n    if error == \"auth\":\n        print(\"Check your API key\")\n    elif error == \"params\":\n        print(\"Check your request parameters\")\n    elif error == \"network_error\":\n        print(\"Network issue, retry\")\nelse:\n    print(response)\n```\n\n## Example Use Cases\n\n**Sales intelligence:** \"What commitments did we make to Acme Corp in the last 30 days?\"\n\n**Customer success:** \"Which customers have expressed frustration in the past week?\"\n\n**Meeting prep:** \"Give me a briefing on everything discussed with the Johnson account, including open items and recent sentiment.\"\n\n**Task extraction:** \"What tasks are assigned to me that I haven't responded to?\"\n\n**Decision audit:** \"Who approved the budget increase and when?\"\n\n**Deal risk detection:** \"Are there any deals where sentiment has shifted negative in the last two weeks?\"\n\n## How It Differs from Basic Email Search\n\n| Basic email/Gmail API | iGPT Email Ask |\n|-----------------------|----------------|\n| Returns raw messages | Returns reasoned answers |\n| Keyword matching only | Understands meaning and context |\n| No thread awareness | Reconstructs full conversation logic |\n| No structured output | Returns tasks, decisions, owners as JSON |\n| No sentiment analysis | Detects tone, risk, trajectory |\n| No citations | Every answer cites source messages |\n\n## Resources\n\n- Get API Key: https://igpt.ai/hub/apikeys/\n- Documentation: https://docs.igpt.ai\n- API Reference: https://docs.igpt.ai/docs/api-reference/ask\n- Playground: https://igpt.ai/hub/playground/\n- Python SDK: https://pypi.org/project/igptai/\n- Node.js SDK: https://www.npmjs.com/package/igptai\n- GitHub: https://github.com/igptai/igptai-python","readmeExcerpt":"Skill: iGPT Email Intelligence Owner: sammy-spk Summary: 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 hist... Tags: ai-agents:1.0.0, context:1.0.0, email:1.0.0, gmail:1.0.0, intelligence:1.0.0, latest:1.0.2 Version history: v1.0.2 | 2026-02-19T12:02:29.032Z | user Version 1.0.2 - Removed the sample file SKILL (","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"pip install igptai"},{"language":"bash","snippet":"export IGPT_API_KEY=\"your-api-key-here\""},{"language":"python","snippet":"from igptai import IGPT\nimport os\n\nigpt = IGPT(api_key=os.environ[\"IGPT_API_KEY\"], user=\"user_123\")\n\nresults = igpt.recall.search(query=\"board meeting notes\")\nprint(results)"},{"language":"python","snippet":"results = igpt.recall.search(\n    query=\"budget allocation\",\n    date_from=\"2026-01-01\",\n    date_to=\"2026-01-31\"\n)\nprint(results)"},{"language":"python","snippet":"results = igpt.recall.search(\n    query=\"partnership proposals\",\n    max_results=10\n)\nprint(results)"},{"language":"python","snippet":"results = igpt.recall.search(\n    query=\"emails from Sarah about the product launch\",\n    date_from=\"2026-01-01\"\n)\nprint(results)"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: igpt-email-search\ndescription: >\n  Secure, per-user-isolated semantic email search via the iGPT API. Hybrid semantic + keyword\n  retrieval across a user's full Gmail, Outlook, or IMAP inbox history — no shell access, no\n  filesystem access, API-key scoped only. Returns relevant messages and threads ranked by meaning,\n  not just keyword overlap. Use when the user needs to find specific emails, threads, or\n  conversations by topic, participant, date range, or content. Retrieval only — for reasoning,\n  summaries, or structured extraction, use the companion skill igpt-email-ask.\nhomepage: https://igpt.ai/hub/playground/\nmetadata: {\"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\"]}\n---\n\n# iGPT Email Search\n\nSearch a user's email by meaning, not just keywords. Hybrid semantic + keyword retrieval across their entire inbox history.\n\n## What This Skill Does\n\nThis skill queries iGPT's `recall/search` endpoint to find relevant emails and threads from a user's connected inbox. The search engine:\n\n- Combines semantic vector search (understands meaning) with keyword matching (catches exact terms)\n- Searches across the user's full indexed email history (not limited to 90 days like some providers)\n- Supports date range filtering for time-bounded queries\n- Returns ranked results with relevance scoring\n- Includes attachment references when present\n\nThis 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`](https://clawhub.ai/skills/igpt-email-ask) — the companion skill that runs iGPT's Context Engine for analysis, summarization, and structured extraction.\n\n## When to Use This Skill\n\n- Find emails about a specific topic, project, or person\n- Locate threads within a date range\n- Retrieve raw email content for further processing\n- Feed email context into another tool or agent step\n- Check what was discussed about a topic before taking action\n- Pull recent correspondence with a specific contact or company\n\n## When to Use igpt-email-ask Instead\n\nIf 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`](https://clawhub.ai/skills/igpt-email-ask), not search.\n\nRule of thumb: if the prompt is a question, use ask. If the prompt is a lookup, use search.\n\n## Prerequisites\n\n1. An iGPT API key (get one at https://igpt.ai/hub/apikeys/)\n2. A connected email datasource — the user must have completed OAuth authorization via `connectors/authorize` before search will return results\n3. Python >= 3.8 with the `igptai` package installed\n\n## Setup\n\n```bash\npip install igptai\n```\n\nSet your API key as an environment variable:"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn796exy66shzmrken55danra181d3fa\",\n  \"slug\": \"igpt-email-intelligence\",\n  \"version\": \"1.0.2\",\n  \"publishedAt\": 1771502549032\n}"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"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 hist... Skill: iGPT Email Intelligence Owner: sammy-spk Summary: 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 hist... Tags: ai-agents:1.0.0, context:1.0.0, email:1.0.0, gmail:1.0.0, intelligence:1.0.0, latest:1.0.2 Version history: v1.0.2 | 2026-02-19T12:02:29.032Z | user Version 1.0.2 - Removed the sample file SKILL (","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":902,"uniquenessScore":54,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-12T01:56:37.869Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-12T01:56:37.869Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T12:02:49.585Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}