Gmail IMAP

Read, search, send, trash, move, and label Gmail via IMAP. Requires GMAIL_IMAP_USER (Gmail address) and GMAIL_IMAP_PASSWORD (Google App Password) environment...

Security Scan

The skill's code, README, and runtime instructions match the stated purpose (Gmail access via IMAP/SMTP) and only request the expected app-password and email address.

Purpose & Capability

Name/description ask for Gmail IMAP access and the skill only requires GMAIL_IMAP_USER and GMAIL_IMAP_PASSWORD. The script uses imap.gmail.com and smtp.gmail.com and implements listing, searching, reading, trashing, moving, labeling, and sending — all consistent with the description.

Instruction Scope

SKILL.md instructs the agent to run the included script and to set the two environment variables. The instructions and script operate on IMAP/SMTP only and don't instruct reading unrelated files, contacting other endpoints, or exfiltrating data to third-party servers.

Install Mechanism

No install spec is provided (instruction-only). The skill ships a Python script that uses only standard libraries (imaplib, smtplib, email). No external downloads or package installs are requested.

Credentials

The skill requires exactly two environment variables: an email address and a Google App Password (declared as the primary credential). Those are proportionate and necessary for IMAP/SMTP access. No unrelated secrets or config paths are requested.

Persistence & Privilege

always is false and disable-model-invocation is false (normal). The skill does not request system-wide config changes or persist credentials beyond using the provided env vars at runtime.

Assessment

This skill appears coherent and implements Gmail access using IMAP/SMTP as described. Before installing: (1) provide a dedicated Google App Password (not your main password) and enable 2FA; (2) prefer creating a separate app password for this skill so you can revoke it later; (3) review the included script yourself if you want to verify it won’t log or transmit credentials (the script does not print the password, but it will connect to Google servers and thus has access to your mail); (4) be aware that the agent can access and modify your email (read/delete/send) when invoked — only enable/use the skill for trusted agents and consider revoking the app password when no longer needed. If you want deeper assurance, provide the full (untruncated) script for a line-by-line review or run it in a controlled environment first.

Gmail IMAP Skill

All Gmail access uses IMAP. Credentials are read from environment variables — never printed.

Requirements

Set these environment variables before use:

Variable	Description
GMAIL_IMAP_USER	Your Gmail address (e.g. [e-mail])
GMAIL_IMAP_PASSWORD	A Google App Password (not your account password)

Generate an App Password at: https://myaccount.google.com/apppasswords (requires 2FA enabled)

Quick Reference

# Locate the script (adjust SKILL_DIR to match your install location):
# Default: ~/.openclaw/skills/gmail-imap
# Custom:  <workspace>/skills/gmail-imap
SCRIPT="$SKILL_DIR/scripts/gmail_imap.py"

# List inbox (most recent 20)
"$SCRIPT" list

# List with custom limit
"$SCRIPT" list --limit 50

# List unread only (shorthand)
"$SCRIPT" list --unread

# List unread with limit
"$SCRIPT" list --unread --limit 10

# Search by sender (IMAP header search)
"$SCRIPT" list --search 'FROM "[e-mail]"'

# Full-text search (Gmail X-GM-RAW — searches body + headers)
"$SCRIPT" search "invoice"
"$SCRIPT" search "from:[e-mail] is:unread" --limit 5
"$SCRIPT" search "subject:meeting this week"

# Read a message (by UID shown in list output)
"$SCRIPT" read <uid>

# Read from a specific folder
"$SCRIPT" read <uid> --folder "[Gmail]/All Mail"

# Delete (moves to [Gmail]/Trash — correct Gmail deletion)
"$SCRIPT" trash <uid>

# Move to a label/folder
"$SCRIPT" move <uid> "Work"

# Send email
"$SCRIPT" send --to [e-mail] --subject "Hello" --body "Message text"

Deletion Rule (Critical)

Never use the standard IMAP \Deleted flag on Gmail — it only archives, it does not delete. Always use trash <uid> which moves to [Gmail]/Trash. The script handles this correctly.

Credentials

Set in env (never output raw password):

• GMAIL_IMAP_USER — Gmail address
• GMAIL_IMAP_PASSWORD — App password (generate at myaccount.google.com/apppasswords)

Reference

For folder names, search syntax, direct Python IMAP usage, and connection details: → See references/gmail-imap-reference.md