email-suite (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, mar...

Security Scan

The skill's code and docs implement an IMAP/SMTP email client (matching its name), but the registry metadata does not declare the many sensitive environment variables it requires and there are a few implementation and packaging inconsistencies you should understand before installing.

Purpose & Capability

The name/description (IMAP/SMTP read/send, attachments, markdown) match the provided files: imap.js, smtp.js, check-inbox.js, setup.sh and README. Dependencies (nodemailer, imapflow, mailparser, marked) are appropriate for the stated functionality.

Instruction Scope

SKILL.md and README explicitly instruct creating a .env with IMAP_/SMTP_ credentials and running the included node scripts. Instructions stay within the email client scope and do not request unrelated system data, but they do instruct creating/storing sensitive credentials in a local .env file and running network-accessing scripts.

Install Mechanism

No install script is provided (no remote downloads). The project includes a package.json with typical npm dependencies; installing via npm install is expected. No external or obfuscated download URLs were found.

Credentials

The skill requires IMAP/SMTP credentials at runtime, but the registry metadata lists no required environment variables or primary credential—this mismatch is material. The repository includes a sample .env and a setup.sh that will write a .env containing sensitive credentials (passwords/app passwords). The skill therefore needs high-sensitivity secrets, and the metadata should have declared them.

Persistence & Privilege

always is false and the skill does not request system-wide privileges. The only persistent artifact is a local .env file the setup helper creates; it does not attempt to modify other skills or system-wide agent config.

What to consider before installing

This package appears to be a legitimate IMAP/SMTP CLI, but treat it carefully because it needs your email credentials. Before installing or running it: 1) Confirm the skill’s origin/author — the registry metadata gives no homepage and the owner is unknown. 2) Don’t enter your main account password — use app-specific passwords or authorization codes where supported. 3) Inspect the repository locally and review scripts (imap.js, smtp.js, setup.sh) yourself; they perform network access to the IMAP/SMTP hosts shown. 4) Keep the created .env out of version control (setup.sh suggests adding .env to .gitignore and chmod 600 — do that). 5) Consider running the code in an isolated environment (container or VM) first. 6) Request the publisher to update registry metadata to declare required environment variables (IMAP_HOST, IMAP_USER, IMAP_PASS, SMTP_HOST, SMTP_USER, SMTP_PASS, etc.) so the credential needs are explicit. 7) Run npm audit / check dependency versions for known vulnerabilities. If you cannot verify the author or are uncomfortable providing email credentials to this package, do not install it.

Read, search, and manage email via IMAP protocol. Send email via SMTP with markdown support, automatic signatures, and professional display names. Supports Gmail, Outlook, Hostinger, 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

# Sender Display Name (optional)
FROM_NAME="Your Name"             # Display name shown to recipients

# Email Signatures (optional)
EMAIL_SIGNATURE="<p><br>--<br><strong>Your Name</strong><br>[e-mail]</p>"
EMAIL_SIGNATURE_TEXT="--\nYour Name\[e-mail]"

Common Email Servers

Provider	IMAP Host	IMAP Port	SMTP Host	SMTP Port
Gmail	imap.gmail.com	993	smtp.gmail.com	587
Outlook	outlook.office365.com	993	smtp.office365.com	587
Hostinger	imap.hostinger.com	993	smtp.hostinger.com	465

Gmail Setup

Gmail requires an App Password instead of your regular account password:

1. Enable 2-Step Verification in your Google Account settings
2. Go to Google Account > Security > App passwords
3. Generate a new app password for "Mail" or "Other"
4. Copy the 16-character password (e.g., abcd efgh ijkl mnop)
5. Use this as your IMAP_PASS and SMTP_PASS (spaces are optional)

Gmail Configuration:

IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=[e-mail]
IMAP_PASS=your_16_char_app_password
IMAP_TLS=true

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=[e-mail]
SMTP_PASS=your_16_char_app_password

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
• --markdown: Convert Markdown to HTML before sending
• --body-file <file>: Read body from file (auto-detects Markdown from .md extension)
• --html-file <file>: Read HTML from file
• --cc <email>: CC recipients
• --bcc <email>: BCC recipients
• --attach <file>: Attachments (can use multiple times)
• --from <email>: Override default sender

Markdown Support:

• Markdown files (.md) are automatically converted to styled HTML
• Use --markdown flag to force conversion of inline text
• Supports headers, bold, italic, links, tables, lists, code blocks

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>"

# Markdown to HTML (auto-detected from .md files or patterns)
node scripts/smtp.js send --to [e-mail] --subject "Report" --body-file report.md
node scripts/smtp.js send --to [e-mail] --subject "Notes" --markdown --body "**Bold** and *italic* text"

# Email with attachment (multiple --attach flags supported)
node scripts/smtp.js send --to [e-mail] --subject "Report" --body "Please find attached" --attach report.pdf
node scripts/smtp.js send --to [e-mail] --subject "Files" --body "Attached files" --attach file1.pdf --attach image.jpg

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

test

Test SMTP connection by sending a test email to yourself.

node scripts/smtp.js test

Dependencies

npm install

Security Notes

⚠️ IMPORTANT - Credential Handling:

1. Protect your .env file: The .env file contains sensitive credentials. Never commit it to version control.

   # Add to .gitignore
   echo ".env" >> .gitignore
   echo ".env.local" >> .gitignore
   

2. Use App Passwords: For Gmail and other providers with 2FA, always use App Passwords instead of your main account password.

3. File permissions: Restrict access to your .env file:

   chmod 600 .env
   

4. No real passwords in examples: The .env file in this repository contains only placeholder/example values. Create your own .env.local or use environment variables for real credentials.

5. setup.sh creates .env: The setup helper script will create a .env file with your credentials. Review the file contents before running scripts.

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 Gmail: use App Password if 2FA enabled

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