Skip to content

feat: add email gateway platform (IMAP/SMTP)#797

Closed
0xbyt4 wants to merge 1 commit into
NousResearch:mainfrom
0xbyt4:feat/email-gateway
Closed

feat: add email gateway platform (IMAP/SMTP)#797
0xbyt4 wants to merge 1 commit into
NousResearch:mainfrom
0xbyt4:feat/email-gateway

Conversation

@0xbyt4

@0xbyt4 0xbyt4 commented Mar 10, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Add email as a new gateway platform — users can interact with Hermes by sending emails
  • IMAP polling for incoming messages, SMTP for threaded replies
  • Full integration with all 14 gateway extension points per ADDING_A_PLATFORM.md checklist

How it works

  1. Configure EMAIL_ADDRESS, EMAIL_PASSWORD, EMAIL_IMAP_HOST, EMAIL_SMTP_HOST in .env
  2. Run hermes gateway
  3. Send an email to the agent's address
  4. Agent processes the message and replies via email with proper threading

Features

  • IMAP polling — checks for UNSEEN messages every 15 seconds (configurable)
  • SMTP replies — threaded via In-Reply-To and References headers
  • Attachment support — images cached for vision tool, documents cached for file access
  • HTML fallback — extracts plain text from HTML-only emails
  • Self-message filtering — prevents reply loops
  • Subject threading — Re: prefix handling without duplication
  • Gmail-ready — works with App Passwords, documented in setup wizard

Integration points (14/14)

# Point File
1 Core adapter gateway/platforms/email.py
2 Platform enum gateway/config.py
3 Env overrides gateway/config.py
4 Connected platforms gateway/config.py
5 Adapter factory gateway/run.py
6 Authorization maps gateway/run.py
7 Platform hints agent/prompt_builder.py
8 Toolset toolsets.py
9 Cron delivery cron/scheduler.py
10 Send message tool tools/send_message_tool.py
11 Channel directory gateway/channel_directory.py
12 Setup wizard hermes_cli/gateway.py
13 Status display hermes_cli/status.py
14 .env.example .env.example

Test plan

  • 65 tests covering all layers:
    • Config loading, env overrides, connected platforms
    • Header decoding, body extraction (plain/HTML/multipart), address parsing
    • Attachment caching (image + document)
    • Message dispatch (self-filter, subject handling, reply detection, empty body, photo type, source building)
    • Reply threading (Re: prefix, double-Re prevention, In-Reply-To headers, default subject)
    • SMTP send (success, failure, image URL, document attachment, typing noop, chat info)
    • IMAP connect/disconnect lifecycle (success, IMAP failure, SMTP failure, poll cancel)
    • IMAP fetch (UID skip, no unseen, error handling, sender name extraction)
    • Poll loop (inbox check + dispatch)
    • Standalone send_message_tool _send_email function
    • All 14 integration points verified

@0xbyt4
feat: add email gateway platform (IMAP/SMTP)
ef7e973 
Allow users to interact with Hermes by sending and receiving emails.
Uses IMAP polling for incoming messages and SMTP for replies with
proper threading (In-Reply-To, References headers).

Integrates with all 14 gateway extension points: config, adapter
factory, authorization, send_message tool, cron delivery, toolsets,
prompt hints, channel directory, setup wizard, status display, and
env example.

65 tests covering config, parsing, dispatch, threading, IMAP fetch,
SMTP send, attachments, and all integration points.
teknium1 added a commit that referenced this pull request Mar 11, 2026
@teknium1
fix: wire email platform into toolset mappings + add documentation
eac5f8f 
Post-merge fixes for the email gateway (PR #797):

1. Add Platform.EMAIL to all 4 platform-to-toolset/config mapping
   dicts in gateway/run.py. Without this, email sessions silently
   fell back to the Telegram toolset because these dicts were added
   after the PR branched off main.

2. Add email (and signal) to hermes_cli/tools_config.py and
   hermes_cli/skills_config.py PLATFORMS dicts so they appear in
   'hermes tools' and 'hermes skills' CLI commands.

3. Add full email setup documentation:
   - website/docs/user-guide/messaging/email.md — setup guide with
     Gmail/Outlook instructions, configuration, troubleshooting,
     security advice, and env var reference
   - Update messaging/index.md — add email to architecture diagram,
     platform toolset table, security examples, and next steps
@teknium1

teknium1 commented Mar 11, 2026

Copy link
Copy Markdown
Contributor

Merged in commit bdcf247 with contributor credit preserved. 🎉

Post-merge fixes applied in eac5f8f:

  • Added Platform.EMAIL to all 4 platform→toolset/config mapping dicts in gateway/run.py (these were added after your branch and would have silently defaulted to Telegram toolset)
  • Added email + signal to hermes tools and hermes skills CLI config UIs
  • Added full email setup documentation at website/docs/user-guide/messaging/email.md (Gmail/Outlook instructions, troubleshooting, security, env var reference)
  • Updated the messaging gateway index page (architecture diagram, platform table, security examples)

Excellent work @0xbyt4 — 65 tests, all 14 integration points, clean merge. Thank you! 🙏

@teknium1 teknium1 closed this Mar 11, 2026
lmsanch added a commit to lmsanch/hermes-agent that referenced this pull request Apr 23, 2026
@lmsanch
fix(tts): fail loud on unknown provider + CI guard preventing NousRes…
6395da1 
…earch#797 regression

Addresses the permanence gap revealed by toryx-private#797: commit
19098b0 reverted the Fish Audio implementation (_generate_fish_audio +
elif provider == 'fish' branch), and the broken state went unnoticed for
nearly a day because the dispatcher's final else: silently fell back to
Edge TTS. Ray's responses were generated in a generic Microsoft voice
instead of his cloned Fish voice, but no error ever surfaced.

This PR closes the mechanism:

1. text_to_speech_tool dispatch: unknown provider now returns a loud
   JSON error listing the known providers, rather than silently routing
   to Edge. The 'edge' default is preserved via an explicit
   elif provider == 'edge' branch.

2. tests/tools/test_tts_providers.py: new CI test that parses
   tts_tool.py and asserts every documented provider has a generator
   function AND a dispatch branch. Fish Audio has a dedicated canary
   test. Deleting Fish (or any other provider) will now fail CI.

Together these make the NousResearch#797-class regression impossible to re-ship
without an explicit, visible deletion from REQUIRED_PROVIDERS — which
a human reviewer has to approve.

Related: closes lmsanch/toryx-private#797 (reopened)
@lmsanch lmsanch mentioned this pull request Apr 23, 2026
Merged
lmsanch added a commit to lmsanch/hermes-agent that referenced this pull request Apr 23, 2026
@lmsanch
fix(tts): fail loud on unknown provider + CI guard preventing NousRes…
76bb951 
…earch#797 regression (#9)

Addresses the permanence gap revealed by toryx-private#797: commit
19098b0 reverted the Fish Audio implementation (_generate_fish_audio +
elif provider == 'fish' branch), and the broken state went unnoticed for
nearly a day because the dispatcher's final else: silently fell back to
Edge TTS. Ray's responses were generated in a generic Microsoft voice
instead of his cloned Fish voice, but no error ever surfaced.

This PR closes the mechanism:

1. text_to_speech_tool dispatch: unknown provider now returns a loud
   JSON error listing the known providers, rather than silently routing
   to Edge. The 'edge' default is preserved via an explicit
   elif provider == 'edge' branch.

2. tests/tools/test_tts_providers.py: new CI test that parses
   tts_tool.py and asserts every documented provider has a generator
   function AND a dispatch branch. Fish Audio has a dedicated canary
   test. Deleting Fish (or any other provider) will now fail CI.

Together these make the NousResearch#797-class regression impossible to re-ship
without an explicit, visible deletion from REQUIRED_PROVIDERS — which
a human reviewer has to approve.

Related: closes lmsanch/toryx-private#797 (reopened)
angelburgosrosado pushed a commit to angelburgosrosado/hermes-agent that referenced this pull request Apr 27, 2026
@teknium1
fix: wire email platform into toolset mappings + add documentation
bf89697 
Post-merge fixes for the email gateway (PR NousResearch#797):

1. Add Platform.EMAIL to all 4 platform-to-toolset/config mapping
   dicts in gateway/run.py. Without this, email sessions silently
   fell back to the Telegram toolset because these dicts were added
   after the PR branched off main.

2. Add email (and signal) to hermes_cli/tools_config.py and
   hermes_cli/skills_config.py PLATFORMS dicts so they appear in
   'hermes tools' and 'hermes skills' CLI commands.

3. Add full email setup documentation:
   - website/docs/user-guide/messaging/email.md — setup guide with
     Gmail/Outlook instructions, configuration, troubleshooting,
     security advice, and env var reference
   - Update messaging/index.md — add email to architecture diagram,
     platform toolset table, security examples, and next steps
02356abc pushed a commit to 02356abc/hermes-agent that referenced this pull request May 14, 2026
@teknium1
fix: wire email platform into toolset mappings + add documentation
2fb4ae6 
Post-merge fixes for the email gateway (PR NousResearch#797):

1. Add Platform.EMAIL to all 4 platform-to-toolset/config mapping
   dicts in gateway/run.py. Without this, email sessions silently
   fell back to the Telegram toolset because these dicts were added
   after the PR branched off main.

2. Add email (and signal) to hermes_cli/tools_config.py and
   hermes_cli/skills_config.py PLATFORMS dicts so they appear in
   'hermes tools' and 'hermes skills' CLI commands.

3. Add full email setup documentation:
   - website/docs/user-guide/messaging/email.md — setup guide with
     Gmail/Outlook instructions, configuration, troubleshooting,
     security advice, and env var reference
   - Update messaging/index.md — add email to architecture diagram,
     platform toolset table, security examples, and next steps
olympus-terminal pushed a commit to olympus-terminal/hermes-agent that referenced this pull request May 16, 2026
@teknium1
fix: wire email platform into toolset mappings + add documentation
58dc8d2 
Post-merge fixes for the email gateway (PR NousResearch#797):

1. Add Platform.EMAIL to all 4 platform-to-toolset/config mapping
   dicts in gateway/run.py. Without this, email sessions silently
   fell back to the Telegram toolset because these dicts were added
   after the PR branched off main.

2. Add email (and signal) to hermes_cli/tools_config.py and
   hermes_cli/skills_config.py PLATFORMS dicts so they appear in
   'hermes tools' and 'hermes skills' CLI commands.

3. Add full email setup documentation:
   - website/docs/user-guide/messaging/email.md — setup guide with
     Gmail/Outlook instructions, configuration, troubleshooting,
     security advice, and env var reference
   - Update messaging/index.md — add email to architecture diagram,
     platform toolset table, security examples, and next steps
lmsanch added a commit to lmsanch/hermes-agent that referenced this pull request May 23, 2026
@lmsanch
fix(tts): fail loud on unknown provider + CI guard preventing NousRes…
3b62151 
…earch#797 regression (#9)

Addresses the permanence gap revealed by toryx-private#797: commit
19098b0 reverted the Fish Audio implementation (_generate_fish_audio +
elif provider == 'fish' branch), and the broken state went unnoticed for
nearly a day because the dispatcher's final else: silently fell back to
Edge TTS. Ray's responses were generated in a generic Microsoft voice
instead of his cloned Fish voice, but no error ever surfaced.

This PR closes the mechanism:

1. text_to_speech_tool dispatch: unknown provider now returns a loud
   JSON error listing the known providers, rather than silently routing
   to Edge. The 'edge' default is preserved via an explicit
   elif provider == 'edge' branch.

2. tests/tools/test_tts_providers.py: new CI test that parses
   tts_tool.py and asserts every documented provider has a generator
   function AND a dispatch branch. Fish Audio has a dedicated canary
   test. Deleting Fish (or any other provider) will now fail CI.

Together these make the NousResearch#797-class regression impossible to re-ship
without an explicit, visible deletion from REQUIRED_PROVIDERS — which
a human reviewer has to approve.

Related: closes lmsanch/toryx-private#797 (reopened)
Egavasyug pushed a commit to Egavasyug/hermes-agent that referenced this pull request Jun 10, 2026
@teknium1
fix: wire email platform into toolset mappings + add documentation
38c03dd 
Post-merge fixes for the email gateway (PR NousResearch#797):

1. Add Platform.EMAIL to all 4 platform-to-toolset/config mapping
   dicts in gateway/run.py. Without this, email sessions silently
   fell back to the Telegram toolset because these dicts were added
   after the PR branched off main.

2. Add email (and signal) to hermes_cli/tools_config.py and
   hermes_cli/skills_config.py PLATFORMS dicts so they appear in
   'hermes tools' and 'hermes skills' CLI commands.

3. Add full email setup documentation:
   - website/docs/user-guide/messaging/email.md — setup guide with
     Gmail/Outlook instructions, configuration, troubleshooting,
     security advice, and env var reference
   - Update messaging/index.md — add email to architecture diagram,
     platform toolset table, security examples, and next steps
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@0xbyt4 @teknium1