Email Operations Skill
Overview
This skill provides email capabilities through direct IMAP/SMTP protocol access using curl. It supports:
- Sending emails via SMTP with TLS
- Fetching email lists via IMAP
- Reading email content by ID
- Multi-account support with secure credential storage
Architecture
- Protocol: Direct IMAP (port 993) and SMTP (port 465) over TLS
- Security: Passwords stored in macOS Keychain, never in config files
- Compatibility: Uses curl with OpenSSL/LibreSSL (better Tencent Enterprise Mail support than rustls)
- Configuration: YAML-based account management in
references/accounts.yaml
Available Scripts
1. Send Email (send-email.sh)
Send emails via SMTP with support for inline or file-based content.
Usage:
./scripts/send-email.sh -t recipient@example.com -s "Subject" -b "Message"
./scripts/send-email.sh -t recipient@example.com -s "Subject" -f message.txt
./scripts/send-email.sh -t recipient@example.com -c another@example.com -s "Subject" -b "Message"
Parameters:
-a ACCOUNT - Account name (default: from accounts.yaml)-t EMAIL - Recipient email (required)-c EMAIL - CC recipient (optional)-s TEXT - Email subject (required)-b TEXT - Email body inline (required if no -f)-f FILE - Email body from file (required if no -b)
2. Fetch Emails (fetch-emails.sh)
Retrieve email headers from a mailbox.
Usage:
./scripts/fetch-emails.sh # Fetch 10 latest from INBOX
./scripts/fetch-emails.sh -n 20 # Fetch 20 latest
./scripts/fetch-emails.sh -m "Sent" # Fetch from Sent folder
Parameters:
-a ACCOUNT - Account name (default: from accounts.yaml)-m FOLDER - Mailbox folder (default: INBOX)-n N - Number of emails to fetch (default: 10)
3. Read Email (read-email.sh)
Read full content of a specific email by ID.
Usage:
./scripts/read-email.sh 123 # Read full email
./scripts/read-email.sh -p HEADER 123 # Headers only
./scripts/read-email.sh -p BODY 123 # Body only
Parameters:
-a ACCOUNT - Account name (default: from accounts.yaml)-m FOLDER - Mailbox folder (default: INBOX)-p PART - Part to retrieve: HEADER, BODY, or TEXT (default: TEXT)EMAIL_ID - Email ID (required, positional argument)
Configuration
Account Setup
Edit references/accounts.yaml to add email accounts:
default_account: SUSTech
accounts:
SUSTech:
email: qihr2022@mail.sustech.edu.cn
display_name: Hanrui Qi
imap:
host: imap.exmail.qq.com
port: 993
login: qihr2022@mail.sustech.edu.cn
protocol: imaps
smtp:
host: smtp.exmail.qq.com
port: 465
login: qihr2022@mail.sustech.edu.cn
protocol: smtps
Password Management
Passwords are stored in macOS Keychain. Set them using:
# IMAP password
security add-generic-password \
-a "qihr2022@mail.sustech.edu.cn" \
-s "email-imap-sustech" \
-w "your-password" \
-U
# SMTP password
security add-generic-password \
-a "qihr2022@mail.sustech.edu.cn" \
-s "email-smtp-sustech" \
-w "your-password" \
-U
Keychain service naming convention:
- IMAP:
email-imap-{account_name_lowercase}
- SMTP:
email-smtp-{account_name_lowercase}
Common Use Cases
1. Send a Quick Email
When user says: "Send an email to alice@example.com about the meeting"
cd /Users/seven/Claude/.claude/skills/email
./scripts/send-email.sh \
-t alice@example.com \
-s "Meeting Discussion" \
-b "Hi Alice, I wanted to follow up on our meeting..."
2. Check Recent Emails
When user says: "Check my email" or "Any new emails?"
cd /Users/seven/Claude/.claude/skills/email
./scripts/fetch-emails.sh -n 5
Parse the output and summarize for the user.
Search / Filter (Pipe + grep/rg)
This is a lightweight way to "search" within the recent emails that fetch-emails.sh fetched (headers only: From/Subject/Date).
cd /Users/seven/Claude/.claude/skills/email
# 任意关键字（例如 github），同时保留邮件 ID 行（便于后续 read）
./scripts/fetch-emails.sh -n 200 | rg -i "github" -B 2
# 主题关键字（建议用 rg；没有 rg 就用 grep -E）
./scripts/fetch-emails.sh -n 200 | rg "主题:.*会议" -B 2
./scripts/fetch-emails.sh -n 200 | grep -E "主题:.*会议" -B 2
# 发件人关键字
./scripts/fetch-emails.sh -n 200 | rg "发件人:.*alice" -B 1
# 提取匹配到的邮件 ID，然后读取正文（取第一个匹配）
email_id="$(
./scripts/fetch-emails.sh -n 200 |
rg -i "github" -B 2 |
sed -nE 's/.*邮件 #([0-9]+).*/\1/p' |
head -n 1
)"
./scripts/read-email.sh "$email_id"
If email_id is empty, increase -n (fetch more recent emails) or adjust the keyword/regex.
3. Read Specific Email
When user says: "Read email #3" or "Show me the latest email"
cd /Users/seven/Claude/.claude/skills/email
./scripts/read-email.sh 3
4. Email Automation
Combine with other skills for automation:
- Check calendar → Send reminder emails
- Monitor inbox → Create system notifications
- Fetch emails → Parse and extract information
Error Handling
Common Issues
-
Authentication Failed
- Verify Keychain passwords are set correctly
- Check if IMAP/SMTP is enabled in email provider settings
- For Tencent Enterprise Mail, use app-specific password
-
Connection Timeout
- Verify network connectivity
- Check firewall settings for ports 993 (IMAP) and 465 (SMTP)
- Confirm host and port in accounts.yaml
-
TLS Handshake Failed
- This skill uses curl with OpenSSL/LibreSSL for better compatibility
- If issues persist, check email provider's TLS requirements
Security Considerations
- Never log or display passwords - they're in Keychain only
- Confirm before sending - especially for important emails
- Validate recipients - check email addresses before sending
- Respect privacy - don't read emails unless explicitly requested
Provider-Specific Notes
Tencent Enterprise Mail (exmail.qq.com)
- IMAP: imap.exmail.qq.com:993 (SSL/TLS)
- SMTP: smtp.exmail.qq.com:465 (SSL/TLS)
- Requires IMAP/SMTP enabled in settings
- Recommend using app-specific password
- Note: IMAP
SEARCH for string criteria (e.g. SUBJECT/FROM/HEADER) may be unreliable on some Tencent Exmail servers; prefer client-side filtering via fetch-emails.sh | rg/grep.
Gmail
- IMAP: imap.gmail.com:993
- SMTP: smtp.gmail.com:587 (STARTTLS)
- Requires "Less secure app access" or App Password
- May need OAuth2 for enhanced security
Outlook/Office 365
- IMAP: outlook.office365.com:993
- SMTP: smtp.office365.com:587
- Requires modern authentication
Technical Details
Why curl instead of rustls?
The rustls TLS library has compatibility issues with some email providers (notably Tencent Enterprise Mail). curl with OpenSSL/LibreSSL provides:
- Better TLS handshake compatibility
- Wider cipher suite support
- Proven reliability with enterprise email systems
IMAP vs POP3
This skill uses IMAP (not POP3) because:
- IMAP supports folder management
- Messages remain on server
- Better for multi-device access
- More flexible search and filtering
Future Enhancements
Potential improvements (not yet implemented):
- Server-side IMAP SEARCH (subject/sender/date; provider-dependent)
- Attachment handling
- HTML email composition
- Email filtering and rules
- OAuth2 authentication support
- Batch operations
References