mirror of
https://github.com/hanzoskill/imap-email.git
synced 2026-10-30 21:09:08 +00:00
4.3 KiB
4.3 KiB
IMAP Email Skill
Read and manage email via IMAP protocol. Built for ProtonMail Bridge, but works with any IMAP server.
Quick Setup (ProtonMail Bridge)
-
Run the setup helper:
cd skills/imap-email ./setup.sh -
Get your Bridge credentials:
- Open ProtonMail Bridge app
- Go to Settings → IMAP/SMTP
- Note your email address and IMAP password
- Default IMAP port is usually
1143
-
Enter credentials when prompted
-
Test the connection:
node scripts/imap.js check
Usage
Check for new emails
node scripts/imap.js check --limit 10
node scripts/imap.js check --recent 2h # Last 2 hours
node scripts/imap.js check --recent 30m # Last 30 minutes
Fetch specific email
node scripts/imap.js fetch <uid>
Search emails
node scripts/imap.js search --unseen
node scripts/imap.js search --from "[email protected]"
node scripts/imap.js search --subject "important"
node scripts/imap.js search --recent 24h # Last 24 hours
node scripts/imap.js search --recent 7d # Last 7 days
node scripts/imap.js search --since "2026-01-20"
Time format:
30m= last 30 minutes2h= last 2 hours7d= last 7 days
Mark as read/unread
node scripts/imap.js mark-read <uid>
node scripts/imap.js mark-unread <uid>
List mailboxes
node scripts/imap.js list-mailboxes
Integration with Bot
Manual email check
From any Bot session:
node skills/imap-email/scripts/imap.js check --limit 5
Automated email checking (cron)
Set up periodic checks:
bot cron add \
--name "email-check-hourly" \
--cron "0 * * * *" \
--session isolated \
--message "Check email inbox and summarize any new emails" \
--deliver \
--channel imessage \
--to "+15551234567"
The agent will automatically use this skill to check email and deliver summaries.
Configuration
Create a .env file in this folder with your IMAP settings:
# IMAP Email Configuration
# ProtonMail Bridge (example)
IMAP_HOST=127.0.0.1
IMAP_PORT=1143
IMAP_USER=[email protected]
IMAP_PASS=bridge_generated_password
IMAP_TLS=false
IMAP_REJECT_UNAUTHORIZED=false # Set to false for self-signed certs (e.g., ProtonMail Bridge)
IMAP_MAILBOX=INBOX
# Gmail IMAP (example)
# IMAP_HOST=imap.gmail.com
# IMAP_PORT=993
# [email protected]
# IMAP_PASS=app_specific_password
# IMAP_TLS=true
# IMAP_REJECT_UNAUTHORIZED=true # Default (omit this line for standard IMAP servers)
# IMAP_MAILBOX=INBOX
Configuration options:
IMAP_HOST- Server hostnameIMAP_PORT- Server portIMAP_USER- Your email addressIMAP_PASS- Your password or app-specific passwordIMAP_TLS- Use TLS (false for STARTTLS, true for SSL)IMAP_REJECT_UNAUTHORIZED- Accept self-signed certs (set to false for ProtonMail Bridge)IMAP_MAILBOX- Default mailbox (INBOX)
Troubleshooting
Connection errors:
- Verify IMAP server is running and accessible
- Check host/port settings in
.env - Test connectivity:
telnet <host> <port> - For ProtonMail Bridge: Verify Bridge app is running
Authentication failed:
- Verify email address and password in
.env - For Gmail: Use App Password (not account password if 2FA enabled)
- For ProtonMail Bridge: Use password from Bridge app (Settings → IMAP/SMTP)
TLS/SSL errors:
- For self-signed certs (ProtonMail Bridge): Set
IMAP_REJECT_UNAUTHORIZED=false - Match port to TLS setting (993 for SSL, 143 for STARTTLS)
Empty results:
- Check mailbox name (case-sensitive)
- Run
node scripts/imap.js list-mailboxesto see available folders
Files
SKILL.md- Skill documentation (loaded by Bot)scripts/imap.js- Main IMAP CLI toolpackage.json- Node.js dependencies.env- Your credentials (created by setup.sh or manually)setup.sh- Interactive setup helper
Security
.envcontains sensitive credentials - keep it private- Add
.envto.gitignoreif publishing this skill - Use app-specific passwords when available (Gmail, Outlook, etc.)
- For ProtonMail Bridge: Password is generated by Bridge app, not your account password
Next Steps
- Run
./setup.shto configure credentials - Test with
node scripts/imap.js check - Set up a cron job for automated email checking
- Customize email summaries by adjusting the cron message template