IMAP SMTP Email

Read and send email via IMAP/SMTP using local Node scripts. Use when the agent needs to check inboxes, fetch email content, search messages, download attachm...

Security Scan

The skill's code, runtime instructions, and requested credentials are consistent with an IMAP/SMTP email tool — nothing appears malicious, but there are minor metadata/instruction mismatches and operational risks you should consider before installing.

Purpose & Capability

Name/description (IMAP/SMTP mail access) matches the actual files and behavior: Node scripts for IMAP reads, attachment parsing, and SMTP sending. Required binaries (node, npm) and the listed IMAP/SMTP environment variables are appropriate for this purpose.

Instruction Scope

SKILL.md and the scripts limit actions to mailbox operations, attachment parsing, contact lookups, and an optional inbox watcher that can forward alerts via the OpenClaw CLI. The watcher uses child_process.execFileSync to call the local OpenClaw CLI (default 'openclaw') to send alerts; this is coherent with the stated feature but means the skill may invoke local CLI/network actions when the watcher runs. The scripts read/write state and contact files under a workspace and enforce path whitelists for attachments; they do not embed unexpected external endpoints.

Install Mechanism

No external download/install script is embedded; dependencies are standard npm packages listed in package.json (imap, nodemailer, mailparser, pdf-parse, xlsx, dotenv). The repo includes a setup helper that runs npm install locally. Nothing in the install flow downloads arbitrary archives from untrusted URLs.

Credentials

The skill legitimately requires IMAP/SMTP credentials. However, the SKILL.md and scripts also rely on additional environment variables and files not listed in the registry metadata (ALLOWED_READ_DIRS, ALLOWED_WRITE_DIRS, EMAIL_ENV_FILE, EMAIL_CONTACTS_FILE, OPENCLAW_WORKSPACE). The credential file is plaintext and contains passwords; the skill recommends storing it at ~/.openclaw/credentials/imap-smtp-mail.env and uses dotenv. This is expected but means you should protect file permissions and prefer app-specific passwords where supported.

Persistence & Privilege

The skill does not request always:true and is user-invocable only. It writes a local state file under the workspace and may call the OpenClaw CLI to forward alerts; it does not modify other skills or system-wide settings. Autonomous invocation is permitted by platform default, which simply enables the watcher feature to run if invoked.

Assessment

This appears to be a genuine IMAP/SMTP helper. Before installing: 1) Be aware it requires your mail credentials (IMAP_USER/IMAP_PASS and SMTP_USER/SMTP_PASS) stored in a plaintext .env file by default — use app passwords and set file permissions (the setup.sh already sets chmod 600). 2) The skill relies on additional env/config values (ALLOWED_READ_DIRS, ALLOWED_WRITE_DIRS, EMAIL_ENV_FILE, EMAIL_CONTACTS_FILE) that are not listed in the registry metadata — review and set these to a minimal whitelist to prevent unexpected file access. 3) The inbox watcher can execute the local OpenClaw CLI to forward alerts (child_process.execFileSync) — if you enable the watcher, it can trigger outbound messages via your OpenClaw agent. 4) Run npm install in an isolated environment and review third-party npm package versions if you need higher assurance. 5) If you want to reduce risk, only enable the watcher when necessary and restrict ALLOWED_* dir lists to trusted directories. If you want me to, I can point to the precise lines where the watcher invokes the OpenClaw CLI and where environment variables are loaded so you can audit them.

IMAP/SMTP Email Tool

Use local Node scripts for inbox access and outbound mail:

• node scripts/imap.js ...
• node scripts/smtp.js ...

Published as imap-smtp-mail on ClawHub.

Configuration

Create ~/.openclaw/credentials/imap-smtp-mail.env with:

# IMAP
IMAP_HOST=imap.example.com
IMAP_PORT=993
IMAP_USER=[e-mail]
IMAP_PASS=your_password
IMAP_TLS=true
IMAP_REJECT_UNAUTHORIZED=true
IMAP_MAILBOX=INBOX
IMAP_SAVE_SENT=true
# Optional override if your provider does not expose the Sent folder cleanly
# IMAP_SENT_MAILBOX=Sent

# SMTP
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=[e-mail]
SMTP_PASS=your_password
SMTP_FROM=[e-mail]
SMTP_FROM_NAME=Your Name
SMTP_REPLY_TO=[e-mail]
SMTP_CLIENT_NAME=example.com
SMTP_REJECT_UNAUTHORIZED=true

# File access controls
ALLOWED_READ_DIRS=~/.openclaw/workspace,~/.openclaw/workspace/exports,~/.openclaw/workspace/out,~/.openclaw/workspace/tmp
ALLOWED_WRITE_DIRS=~/.openclaw/workspace/exports,~/.openclaw/workspace/tmp

This skill loads ~/.openclaw/credentials/imap-smtp-mail.env at runtime with dotenv. The credential file path can be overridden with the EMAIL_ENV_FILE environment variable. The IMAP/SMTP variables do not need to be exported globally in the OpenClaw service environment.

SMTP notes:

• SMTP_FROM_NAME sets a display name.
• SMTP_REPLY_TO is optional.
• SMTP_CLIENT_NAME controls the hostname used in EHLO/HELO. If omitted, the script derives it from the sender domain.
• When only plain text is provided, the tool also generates a simple HTML alternative part.
• For emails containing structured data, prefer well-formed HTML content over plain-text pseudo-layouts when readability matters.

IMAP Sent-copy notes:

• If IMAP is configured and IMAP_SAVE_SENT is not false, the tool appends a copy of each sent email to the IMAP Sent mailbox after successful SMTP delivery.
• The script tries to detect the Sent mailbox automatically using IMAP mailbox attributes and common folder names.
• If needed, set IMAP_SENT_MAILBOX explicitly (for example Sent, Sent Items, or INBOX.Sent).

Default contact file: contacts/email-contacts.json

Contact shape:

{
  "version": 1,
  "contacts": [
    {
      "id": "client-a",
      "name": "Client A",
      "email": "[e-mail]",
      "phone": "+000000000000",
      "aliases": ["client a", "achat client a"],
      "tags": ["client"],
      "notes": "Optional note"
    }
  ]
}

Install

Run once in the skill folder:

cd skills/imap-smtp-mail
npm install

Common commands

Check inbox

cd skills/imap-smtp-mail
node scripts/imap.js check --limit 10

Search email

cd skills/imap-smtp-mail
node scripts/imap.js search --subject "invoice" --recent 7d --limit 20

Fetch one message

cd skills/imap-smtp-mail
node scripts/imap.js fetch 123

Fetch output includes parsed recipient fields (from, to, cc, replyTo) and threading headers (messageId, inReplyTo, references).

Fetch message and read attachment content inline

cd skills/imap-smtp-mail
node scripts/imap.js fetch 123 --extract-attachments

Parses .xlsx, .csv, and .pdf attachments directly and returns their content in the JSON output. Each attachment entry includes a status field:

• parsed — content extracted. Excel/CSV: sheets[] with headers and rows. PDF: text and pages.
• skipped_large — over limit: raw file > 500 KB, or Excel > 200 rows / 10 000 cells, or PDF > 25 000 extracted chars. Includes a reason field.
• skipped_inline_image — image with inline disposition (logo, signature). Silently ignored.
• unsupported — file type not supported for extraction (e.g. attached JPEG, DOCX, ZIP).
• failed — parsing error. Includes a reason field.

Additional fields on parsed PDF results:

• warning: 'scanned_pdf_likely' — extracted text is under 20 chars despite the file having pages; the PDF is probably a scan and text extraction yielded nothing useful.

For multi-sheet workbooks, each sheet carries its own status. The attachment-level status is parsed if at least one sheet was successfully read; skipped_large if all sheets exceeded the limit.

Use fetch --extract-attachments when the email is known or suspected to contain a useful business document (price list, invoice, order). Use the standard download command instead when the file is too large or needs to be saved to disk.

Download attachments

cd skills/imap-smtp-mail
node scripts/imap.js download 123 --dir ~/.openclaw/workspace/tmp

Mark messages as read

cd skills/imap-smtp-mail
node scripts/imap.js mark-read 123 456

Mark messages as unread

cd skills/imap-smtp-mail
node scripts/imap.js mark-unread 123

List mailboxes

cd skills/imap-smtp-mail
node scripts/imap.js list-mailboxes

Test SMTP

Note: This command sends a real test email to your own address (SMTP_USER). It is not a passive connectivity check.

cd skills/imap-smtp-mail
node scripts/smtp.js test

Verbose SMTP debug:

cd skills/imap-smtp-mail
node scripts/smtp.js test --debug

List contacts

cd skills/imap-smtp-mail
node scripts/smtp.js contacts
node scripts/smtp.js contacts --query compta

Resolve one contact

cd skills/imap-smtp-mail
node scripts/smtp.js resolve-contact --contact "Client A"

Send email

cd skills/imap-smtp-mail
node scripts/smtp.js send --to [e-mail] --subject "Subject" --body "Message"

By default, send creates a draft preview only. Actual sending requires --approve.

cd skills/imap-smtp-mail
node scripts/smtp.js send --to [e-mail] --subject "Subject" --body "Message" --approve

Reply to an existing email

Preview a threaded reply to the sender (or Reply-To when present):

cd skills/imap-smtp-mail
node scripts/smtp.js send --reply-uid 123 --body "Hello,\n\nReceived, thanks.\n\nBest regards"

Reply-all while keeping the original To and Cc recipients (except own mailbox and duplicates):

cd skills/imap-smtp-mail
node scripts/smtp.js send --reply-uid 123 --reply-all --body "Hello,\n\nReceived, thanks.\n\nBest regards" --approve

With --reply-uid, the tool auto-fills the reply target, adds Re: to the subject when needed, and sets In-Reply-To / References for proper threading. Use --reply-all by default for normal business thread replies unless the user explicitly wants a sender-only reply.

Send email by contact name

cd skills/imap-smtp-mail
node scripts/smtp.js send --contact "Client A" --subject "Subject" --body "Message" --approve

Verbose send debug:

cd skills/imap-smtp-mail
node scripts/smtp.js send --contact "Client A" --subject "Subject" --body "Message" --approve --debug

When IMAP Sent-copy is active, the send result also includes:

• savedToSent
• sentMailbox
• sentCopyError if the SMTP send succeeded but the IMAP append failed

Draft email with attachment

cd skills/imap-smtp-mail
node scripts/smtp.js send --to [e-mail] --subject "Report" --body "Please find attached the report." --attach ~/.openclaw/workspace/exports/pdfs/report.pdf

Actual sending with attachment:

cd skills/imap-smtp-mail
node scripts/smtp.js send --to [e-mail] --subject "Report" --body "Please find attached the report." --attach ~/.openclaw/workspace/exports/pdfs/report.pdf --approve

Send styled HTML email

cd skills/imap-smtp-mail
node scripts/smtp.js send --to [e-mail] --subject "Stock status" --html "<p>Hello,</p><p>Here is the stock status.</p><table border=\"1\" cellpadding=\"6\" cellspacing=\"0\"><tr><th>Reference</th><th>Stock</th></tr><tr><td>REF-001</td><td>12</td></tr></table><p>Best regards</p>" --approve

Operational rules

• Use this skill for email only.
• Keep outbound email approval-based: never auto-send without user validation.
• Use attachments only from allowed workspace directories.
• Use contact aliases from contacts/email-contacts.json when the user refers to recipients by name.
• The contact list is for outbound convenience and recipient resolution; incoming email can come from any sender.
• The agent may summarize incoming email and prepare a draft reply, but must never auto-reply without user validation.
• For replies to an inbound email, prefer node scripts/smtp.js send --reply-uid <uid> --reply-all ...; omit --reply-all only when the user explicitly wants sender-only.
• node scripts/imap.js fetch <uid> exposes Cc, Reply-To, messageId, In-Reply-To, and References so reply behavior can be inspected before sending.
• Do not expose credentials in responses.
• Use --debug when delivery behavior needs investigation; it prints SMTP transport logs to stderr and returns envelope/accepted/rejected details in JSON.

Lightweight email watch (optional)

Note: This feature is optional and higher-trust than basic IMAP/SMTP usage. When enabled, email-watch-lite.js invokes the local openclaw CLI to analyze pending emails and may forward summarized email content to another OpenClaw channel (e.g. WhatsApp). Do not enable it unless you understand and accept this behavior.

For low-cost inbox polling, use the detector script instead of a recurring model cron:

cd skills/imap-smtp-mail
node scripts/email-watch-lite.js detect --state ../../memory/email-watch-state.json

To poll and trigger the agent only when pendingUids exist:

cd skills/imap-smtp-mail
node scripts/email-watch-lite.js detect-and-trigger --state ../../memory/email-watch-state.json --channel whatsapp --to +000000000000 --openclaw-bin ~/.npm-global/bin/openclaw --timeout 180 --thinking low

Customize the analysis prompt with --message "your custom instructions".

The email watcher requires the openclaw CLI binary. It is not needed for core IMAP/SMTP operations.