Sales Email Automation (IMAP/SMTP)

Read and send email via IMAP/SMTP. Check for new/unread messages, fetch content, search mailboxes, mark as read/unread, and send emails with attachments. Wor...

Security Scan

The skill largely does what its name says (IMAP/SMTP automation) but it also reads extra environment/files and executes local scripts (Discord, OKKI, vector search) beyond the declared requirements — some of those behaviors are reasonable for this workflow but several mismatches merit caution.

Purpose & Capability

Stated purpose (read/send email via IMAP/SMTP) matches the majority of code: imap CLI, smtp CLI, auto-capture, attachment handling, and sending. Additional features — OKKI customer matching, LanceDB/vector search, Discord review, quotation-workflow integration — are plausible for a sales-email automation tool but expand scope beyond a minimal IMAP/SMTP helper. Declared required env vars (IMAP_*/SMTP_*) are appropriate; other capabilities (Discord, OKKI) explain extra files but were not listed in requires.env.

Instruction Scope

SKILL.md instructs to create a local .env and documents many optional envs and file paths, but the runtime code reads additional environment variables and paths beyond the declared required set (e.g., IMAP_PORT, IMAP_TLS, MAIL_OUTPUT_DIR, OKKI_CLI_PATH, VECTOR_SEARCH_PATH, DISCORD_BOT_TOKEN). Notably, discord-review.js attempts to load an ENV_PATH at path.join(__dirname, '..', '..', '.env') (two levels up), which may read a global .env outside the skill folder. The code executes local Python scripts and spawns child processes (execSync/execFile) to call vector search and OKKI CLI — these operations can read arbitrary local data, call external services, and transmit data (Discord API).

Install Mechanism

No install spec (instruction-only skill) and required runtime binaries are just node/npm. No remote downloads or archive extraction. This is lower installation risk, though the bundled code will be written to disk if the skill files are installed by the platform.

Credentials

Declared required env vars (IMAP_HOST/USER/PASS and SMTP_HOST/USER/PASS) are proportional to the email function. However, the code also expects or reads other secrets/paths that were not declared (DISCORD_BOT_TOKEN via a global .env, OKKI and vector-search CLI paths, MAIL_OUTPUT_DIR). The attempt to read ../../.env and to use child_process to run python scripts increases the effective credential and data-access footprint beyond the declared requirements.

Persistence & Privilege

always:false and default autonomous invocation are sensible. The skill writes archives and drafts to local directories and can create cron jobs per documentation (user-added). It does not claim or request permanent platform-level privileges, but its file writes, reading of a global .env, and ability to spawn external commands increase its blast radius if run with broader environment privileges.

What to consider before installing

This skill appears to implement a full sales-email workflow (IMAP/SMTP, auto-archiving, OKKI matching, Discord review, quotation generation). That is plausible, but you should not install it blindly. Before using: 1) Review the code files (auto-capture.js, discord-review.js, scripts/*.js) yourself or with a dev you trust; pay special attention to any child_process.exec/execSync/execFile usage and the places where .env files are read. 2) Ensure you do NOT keep sensitive global credentials in a workspace-level .env two directories above the skill (discord-review tries to read ../../.env). 3) Remove or sandbox integrations you don't need (Discord bot token, OKKI CLI, vector search) or provide them via isolated, limited accounts. 4) Run the skill in an isolated container or dedicated system account with minimal permissions and with only the exact IMAP/SMTP credentials it needs. 5) If you need to allow automated sending, enforce human review for high-risk intents (complaints/partnership) and audit mail-sending logs. If you cannot review the code, consider not installing or restricting the environment and file access the skill can see.

IMAP/SMTP Email Tool

Read, search, and manage email via IMAP protocol. Send email via SMTP. Supports Gmail, Outlook, 163.com, and any standard IMAP/SMTP server.

Configuration

Create .env in the skill folder or set environment variables:

# IMAP Configuration (receiving email)
IMAP_HOST=imap.gmail.com          # Server hostname
IMAP_PORT=993                     # Server port
IMAP_USER=[e-mail]
IMAP_PASS=your_password
IMAP_TLS=true                     # Use TLS/SSL connection
IMAP_REJECT_UNAUTHORIZED=true     # Set to false for self-signed certs
IMAP_MAILBOX=INBOX                # Default mailbox

# SMTP Configuration (sending email)
SMTP_HOST=smtp.gmail.com          # SMTP server hostname
SMTP_PORT=587                     # SMTP port (587 for STARTTLS, 465 for SSL)
SMTP_SECURE=false                 # true for SSL (465), false for STARTTLS (587)
SMTP_USER=[e-mail]          # Your email address
SMTP_PASS=your_password           # Your password or app password
SMTP_FROM=[e-mail]          # Default sender email (optional)
SMTP_REJECT_UNAUTHORIZED=true     # Set to false for self-signed certs

Common Email Servers

Provider	IMAP Host	IMAP Port	SMTP Host	SMTP Port
163.com	imap.163.com	993	smtp.163.com	465
Gmail	imap.gmail.com	993	smtp.gmail.com	587
Outlook	outlook.office365.com	993	smtp.office365.com	587
QQ Mail	imap.qq.com	993	smtp.qq.com	587

Important for Gmail:

• Gmail does not accept your regular account password
• You must generate an App Password: https://myaccount.google.com/apppasswords
• Use the generated 16-character App Password as IMAP_PASS / SMTP_PASS
• Requires Google Account with 2-Step Verification enabled

Important for 163.com:

• Use authorization code (授权码), not account password
• Enable IMAP/SMTP in web settings first

IMAP Commands (Receiving Email)

check

Check for new/unread emails.

node scripts/imap.js check [--limit 10] [--mailbox INBOX] [--recent 2h]

Options:

• --limit <n>: Max results (default: 10)
• --mailbox <name>: Mailbox to check (default: INBOX)
• --recent <time>: Only show emails from last X time (e.g., 30m, 2h, 7d)

fetch

Fetch full email content by UID.

node scripts/imap.js fetch <uid> [--mailbox INBOX]

download

Download all attachments from an email, or a specific attachment.

node scripts/imap.js download <uid> [--mailbox INBOX] [--dir <path>] [--file <filename>]

Options:

• --mailbox <name>: Mailbox (default: INBOX)
• --dir <path>: Output directory (default: current directory)
• --file <filename>: Download only the specified attachment (default: download all)

search

Search emails with filters.

node scripts/imap.js search [options]

Options:
  --unseen           Only unread messages
  --seen             Only read messages
  --from <email>     From address contains
  --subject <text>   Subject contains
  --recent <time>    From last X time (e.g., 30m, 2h, 7d)
  --since <date>     After date (YYYY-MM-DD)
  --before <date>    Before date (YYYY-MM-DD)
  --limit <n>        Max results (default: 20)
  --mailbox <name>   Mailbox to search (default: INBOX)

mark-read / mark-unread

Mark message(s) as read or unread.

node scripts/imap.js mark-read <uid> [uid2 uid3...]
node scripts/imap.js mark-unread <uid> [uid2 uid3...]

list-mailboxes

List all available mailboxes/folders.

node scripts/imap.js list-mailboxes

SMTP Commands (Sending Email)

send

Send email via SMTP.

node scripts/smtp.js send --to <email> --subject <text> [options]

Required:

• --to <email>: Recipient (comma-separated for multiple)
• --subject <text>: Email subject, or --subject-file <file>

Optional:

• --body <text>: Plain text body
• --html: Send body as HTML
• --body-file <file>: Read body from file
• --html-file <file>: Read HTML from file
• --cc <email>: CC recipients
• --bcc <email>: BCC recipients
• --attach <file>: Attachments (comma-separated)
• --from <email>: Override default sender

Examples:

# Simple text email
node scripts/smtp.js send --to [e-mail] --subject "Hello" --body "World"

# HTML email
node scripts/smtp.js send --to [e-mail] --subject "Newsletter" --html --body "<h1>Welcome</h1>"

# Email with attachment
node scripts/smtp.js send --to [e-mail] --subject "Report" --body "Please find attached" --attach report.pdf

# Multiple recipients
node scripts/smtp.js send --to "[e-mail],[e-mail]" --cc "[e-mail]" --subject "Update" --body "Team update"

Development Email Workflow

Important Principles

Template is for structure reference only - always customize content for each recipient.

Wrong (avoid):

• ❌ Sending template email directly without customization
• ❌ Using hardcoded customer names, locations, or company info from templates
• ❌ Sending location-specific content to wrong regions

Correct approach:

• ✅ Use template structure only (greeting → company intro → attachments → call-to-action → signature)
• ✅ Customize content based on customer info (company name, country, industry)
• ✅ Generate dynamic HTML content for each recipient

Pre-send Checklist

1. [ ] **Collect customer information**
   - Company name
   - Country/region
   - Industry/business type
   - Contact person name (if available)
   - Email address

2. [ ] **Generate personalized email content**
   - Customize greeting with customer location/industry
   - Adjust tone and focus for different markets
   - Generate HTML file or prepare `--body` content

3. [ ] **Prepare attachments**
   - Product catalog PDF
   - Custom quotation (if applicable)
   - Verify all file paths are correct

4. [ ] **Send complete email in one message**
   - Include all attachments
   - Personalized content
   - Professional signature

Complete Send Command Example

cd $WORKSPACE/skills/imap-smtp-email

node scripts/smtp.js send \
  --to "[e-mail]" \
  --subject "Product Catalog from Your Company" \
  --html \
  --body-file "/path/to/customized-email.html" \
  --attach "/path/to/catalogue.pdf,/path/to/quotation.pdf"

OKKI CRM Integration (Optional)

This skill supports automatic sync with OKKI CRM for tracking email communications.

Configuration

Set environment variables in .env:

# OKKI CRM Integration
OKKI_CLI_PATH=/path/to/okki.py
VECTOR_SEARCH_PATH=/path/to/search-customers.py
PYTHON_VENV_PATH=python3

Features

• Automatic customer matching via domain or vector search
• Email trail creation in OKKI (trail_type=102)
• Quotation trail creation (trail_type=101)
• Deduplication via /tmp/okki-sync-processed.json
• Unmatched email logging to /tmp/okki-unmatched-emails.log

Manual Sync Command

node okki-sync.js quotation '{"dataFile":"/path/to/data.json","quotationNo":"QT-xxx"}'

Discord Review Integration (Optional)

Configure Discord channel for email review workflow.

Configuration

Edit config/discord-config.json:

{
  "channel_id": "<your-discord-channel-id>",
  "guild_id": "",
  "review_channel": "email-review",
  "timeout_minutes": 30
}

Set environment variable:

DISCORD_BOT_TOKEN=your-discord-bot-token

Dependencies

npm install

Security Notes

• Store credentials in .env (add to .gitignore)
• Gmail: regular password is rejected — generate an App Password at https://myaccount.google.com/apppasswords
• For 163.com: use authorization code (授权码), not account password

Troubleshooting

Connection timeout:

• Verify server is running and accessible
• Check host/port configuration

Authentication failed:

• Verify username (usually full email address)
• Check password is correct
• For 163.com: use authorization code, not account password
• For Gmail: regular password won't work — generate an App Password

TLS/SSL errors:

• Match IMAP_TLS/SMTP_SECURE setting to server requirements
• For self-signed certs: set IMAP_REJECT_UNAUTHORIZED=false or SMTP_REJECT_UNAUTHORIZED=false

Related Files

• Main scripts: scripts/imap.js, scripts/smtp.js
• OKKI sync: okki-sync.js
• Discord review: discord-review.js
• Configuration: config/discord-config.json, profiles/user-map.json