feat: add email integration (read, send, manage) - #800
Merged
Conversation
OpenSpec change: email-integration - Proposal: multi-provider email integration (Gmail, MS Graph, IMAP) - Design: provider abstraction with OAuth2 credential management - Specs: email-tools, email-providers, email-auth capabilities - Tasks: 30 implementation tasks across 7 groups Closes #779
- Add email module: src/tools/email/ with provider abstraction - Implement GmailProvider, GraphProvider, ImapProvider - Create email tools: read, send, draft (save/list/update/delete), organize, search - Add email provider config schemas (Gmail, Graph, IMAP) - Register email tools in TOOL_PERMISSIONS and TOOL_CLASSIFICATIONS - Add comprehensive tests for all providers, tools, and config schemas - Dependencies: googleapis, @microsoft/microsoft-graph-client, nodemailer, imap-simple Closes #779
- Archive OpenSpec change: 2026-08-16-email-integration - Apply spec deltas: email-auth (+4), email-providers (+5), email-tools (+4) - Total: +13 lines added to spec files
avoidwork
enabled auto-merge (squash)
August 16, 2026 01:55
avoidwork
disabled auto-merge
August 16, 2026 09:12
- Add EmailConfigSchema with provider discriminated union (gmail, graph, imap) - Add email section to config.yaml with all provider fields - Add env var allowlist for email config (EMAIL_PROVIDER_*, EMAIL_*) - Env resolution maps email.provider.clientId → EMAIL_PROVIDER_CLIENT_ID - All schema fields nullable with sensible defaults - Add factory.test.js for email provider creation - Update provider tests for new schema structure
- Add timeoutMs to base class, AbortController pattern to all providers - Add validateConfig() to all providers with required field checks - GmailProvider: fix hardcoded From: madz header, fix base64 encoding (standard not URL-safe), remove duplicate CATEGORY_UPDATES in archive - GraphProvider: add timeout to all fetch calls, fix folder case (INBOX), fix updateDraft null safety, fix organize addLabel/removeLabel to use params.label - ImapProvider: fix search/listDrafts folder handling, fix deleteDraft expunge API, use imap-simple addMessage for drafts instead of SMTP hack, add timeout, add validation
…efresh, config schema, startup validation - Add AES-256-GCM credential encryption module (crypto.js) - Add #sanitizeError() to all providers to strip credentials from error messages - Implement OAuth token refresh for GmailProvider and GraphProvider - Add 401 retry with token refresh in GraphProvider #fetchWithTimeout - Fix GraphProvider OData injection — escape single quotes in filter values - Fix Graph archive folder — use 'deleteditems' instead of 'deletedmessages' - Fix IMAP organize to use params.folder instead of hardcoded INBOX - Fix IMAP draft IDs — use actual IMAP UIDs instead of synthetic IDs - Fix IMAP read/search/listDrafts — use UID-based pagination - Add provider config validation at startup in deepAgents.js - Fix config.yaml — remove cross-provider fields from email section - Make Zod provider schemas passthrough to allow extra fields in config - Add #sanitizeError to IMAP provider alongside Gmail/Graph
- email-auth: update credential storage to reflect config-based AES-256-GCM encryption (not memory system) - email-auth: update startup validation to reflect config-level validation (not API test requests) - email-auth: add error message sanitization requirement - email-tools: fix date filter parameter names (dateFrom/dateTo, not dateAfter/dateBefore)
- Remove crypto.js — no encryption needed, credentials never touch config - Remove all credential fields from Zod schemas (clientId, clientSecret, etc.) - GmailProvider reads from EMAIL_GMAIL_* env vars - GraphProvider reads from EMAIL_GRAPH_* env vars - ImapProvider reads from EMAIL_IMAP_* env vars - validateProviderConfig checks env vars instead of config fields - Clean config.yaml — only provider type and non-secret settings remain - All 1106 tests pass, lint clean
…on dispatch - Replace email_read, email_send, email_draft_save/list/update/delete, email_organize, email_search with single 'email' tool - Export emailImpl for testability, wrapped by tool() for registration - Action dispatch: read, send, draftSave, draftList, draftUpdate, draftDelete, organize, search - Unknown action validated before provider check - All 1106 tests pass, lint clean
- Add email tool to Built-in Tools table with action list - Add EMAIL_* env var section with all Gmail, Graph, and IMAP variables
- Split email credentials into EMAIL_IMAP_* and EMAIL_SMTP_* env vars - IMAP provider uses nodemailer for SMTP sending, imap-simple for IMAP reading - SMTP defaults to IMAP host when not explicitly configured - Updated config.yaml sandbox env allowlist - Updated schema with imapHost, imapPort, imapSecure, smtpHost, smtpPort - Updated README with new env var documentation
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Add email integration tools for reading, sending, and managing emails across Gmail, Outlook/MS Graph, and IMAP — including inbox organization and draft management. This change introduces a unified email tool with action-based dispatch, multi-provider support, and dedicated IMAP/SMTP configuration.
Type of Change
Testing
Coverage
Checklist
npm run lintpassesFiles Changed
src/tools/email/src/tools/index.jssrc/agent/deepAgents.jssrc/config/config.jssrc/config/schemas/providers.jstests/unit/tools/email/tests/unit/config/providers.test.jspackage.jsongoogleapis,nodemailer,imap-simpleopenspec/specs/README.mdconfig.yaml