IMAP Client

Read, search, and download email over IMAP from the command line using the `myl` CLI client. Use this skill whenever the user wants to interact with their ma...

Security Scan

The skill's requests, files, and runtime instructions match its stated purpose: a read-only IMAP wrapper around the third‑party myl CLI and it only asks for mailbox credentials needed to do that.

Purpose & Capability

Name, description, required binary (myl), and required env vars (IMAP_USER, IMAP_PASSWORD) align with a CLI IMAP client. The skill does not request unrelated cloud keys, platform credentials, or system-wide access.

Instruction Scope

SKILL.md and the scripts confine behavior to discovering/using myl, sourcing credentials (env or a local creds file), and forwarding flags to myl. The wrapper and docs explicitly limit actions (read-only, optional mark-seen only when requested) and warn about not pasting passwords into chat.

Install Mechanism

No automatic remote download or installer; installation guidance recommends pipx/pip/nix for the upstream myl package. The skill contains small shell scripts only (wrapper + check script). This is low-risk compared with arbitrary URL downloads.

Credentials

The skill requires only IMAP_USER and IMAP_PASSWORD — exactly the credentials needed to log into IMAP. Note: the wrapper passes the password to myl via command-line flags, so the secret will be briefly visible in process args (/proc/<pid>/cmdline and ps) on the host; the docs acknowledge this and recommend app-specific passwords and OpenClaw secret injection to reduce exposure.

Persistence & Privilege

The skill does not request always:true, does not modify other skills or system-wide settings, and is user-invocable. It relies on the runtime to inject env vars per run or a local creds file with restrictive permissions.

Assessment

This skill is internally consistent: it wraps the third-party myl CLI and only asks for your IMAP username and an app-specific password. Before installing, consider: 1) Prefer OpenClaw's secret injection (apiKey/SecretRef) or a credentials file with 600 perms rather than exporting your mailbox password globally. 2) Use provider app-specific passwords (rotate if accidentally pasted into chat). 3) Be aware the wrapper passes the password to myl on the command line so it may be briefly visible to other local processes via /proc or ps — avoid running on multi-user hosts where untrusted users can inspect process lists. 4) Confirm you trust the upstream myl package (pipx install myl) since that is the third-party binary this skill requires. If you want stronger guarantees, inspect the installed myl binary and run the wrapper locally once to verify behavior before granting runtime access.

Read mailboxes over IMAP from the terminal using myl, a small Python CLI client. Maintained and distributed by codd-tech. Designed to drop into OpenClaw and any other AgentSkills-compatible runtime (Claude Code, generic).

myl is read-only and intentionally minimal: it lists, searches, and fetches messages and attachments. It does not send mail, manage folders, or modify state beyond optionally marking messages as seen.

How credentials reach this skill

This is the most important section. You do not type passwords on the command line. Credentials live in environment variables that the runtime injects per agent run. The skill reads them and assembles the right myl flags through the wrapper at {baseDir}/scripts/imap.sh.

The variables the wrapper expects:

Variable	Required	Purpose
IMAP_USER	yes	Login (usually full email address)
IMAP_PASSWORD	yes	App-specific password (see references/authentication.md)
IMAP_PROVIDER	no	One of auto (default), gmail, yandex, mailru, manual
IMAP_SERVER	only with manual	IMAP host
IMAP_PORT	no	Defaults to 993
IMAP_STARTTLS	no	1 to add --starttls (use only with port 143)

Set them once, use them every session. How depends on the runtime — references/authentication.md covers OpenClaw's skills.entries.imap-client.env, generic shell export, and a ~/.config/imap-client/credentials fallback file. Do not invent your own scheme; use one of those three.

If the wrapper detects IMAP_USER or IMAP_PASSWORD is missing, it prints the setup instructions and exits without contacting any server. That's the signal to stop and walk the user through credential setup before retrying.

Workflow at a glance

1. Check that myl is installed. OpenClaw gates this skill on requires.bins: ["myl"], so it shouldn't load without it. For non-OpenClaw runtimes, run bash {baseDir}/scripts/check_myl.sh. If missing, follow references/installation.md.
2. Confirm credentials are configured. Run bash {baseDir}/scripts/imap.sh --count 1 >/dev/null once. Success means the env vars are wired and the connection works. Failure means walk the user through references/authentication.md.
3. Run the requested operation through the wrapper. Listing, searching, fetching by ID, getting HTML, saving raw .eml, or pulling an attachment.
4. Summarise the result. Don't dump full raw email bodies into the chat unless the user asked.

Every myl example in this skill goes through {baseDir}/scripts/imap.sh, which expands env vars into the right myl flags. You do not need to remember --google vs --auto vs --server/--port; the wrapper picks based on IMAP_PROVIDER.

When to read what

Task involves…	Read
Detecting or installing myl, OpenClaw requires.bins gating	references/installation.md
Setting up credentials, choosing connection mode, app passwords for Gmail / Yandex / Mail.ru / iCloud / Fastmail	references/authentication.md
Any specific CLI flag, listing, searching, fetching, attachments, provider-specific folder names	references/operations.md
Multi-step recipes (e.g. "find the invoice from Acme last month and save the PDF")	references/recipes.md
Errors like SSL failures, "command not found", autodiscovery failing, "AUTHENTICATIONFAILED", env vars not visible to the wrapper	references/troubleshooting.md

Principles

1. Credentials must not appear in agent-generated commands or logs

Do not generate commands like myl --password hunter2 or myl --password "$IMAP_PASSWORD" directly — the first hardcodes the secret in shell history and conversation logs; the second exposes it there too and adds no benefit over the wrapper. Always use the wrapper:

bash {baseDir}/scripts/imap.sh --count 5

The wrapper reads credentials from env vars and passes them to myl via --username/--password flags. This means the password is briefly visible in /proc/<pid>/cmdline and ps output to other processes on the same host while myl runs — the same exposure as running myl directly with env-var expansion. The wrapper's benefit is narrower: the password value never appears in commands the agent generates, in shell history, or in conversation logs. On shared or multi-user machines this argv exposure should be understood as a residual risk.

2. Default to small result sets

When the user's intent is exploratory ("any new mail?"), pass --count 5 or --count 10. Only fetch larger windows on explicit request. This keeps output readable and avoids dumping sensitive content the user didn't ask to see.

3. Don't mark as seen by accident

--mark-seen mutates state on the server. Only pass it when the user explicitly asked to mark messages read. Listing or reading without this flag is non-destructive.

4. Render long bodies to a file, summarise in chat

When the user fetches a long message or HTML email, save the raw output to a file (e.g. /tmp/email-<id>.eml or .html) and give the user a 2–4 sentence summary plus the file path. Do not paste a 500-line HTML body into the conversation.

5. Search syntax is server-side IMAP, not Gmail's web UI

--search "important" issues an IMAP SEARCH command. It does not understand Gmail's from:, has:attachment, or label: operators. For complex filtering, fetch a reasonable window with --count and filter the listing locally. See references/operations.md for what IMAP SEARCH supports.

6. Never echo, summarise, or persist the password

When summarising what you did, refer to the credential as IMAP_PASSWORD or "the password from your OpenClaw config", never the literal value. If the user pastes a password into chat by mistake, treat it as compromised: tell them to rotate it and update their config. Do not write it to any artifact.

Quick decision tree

User asked something email-related from the CLI
  │
  ├─ Is `myl` installed and on PATH?  ── No  ──► references/installation.md
  │   │
  │   Yes
  │   ▼
  ├─ Does the wrapper smoke-test pass?
  │     bash {baseDir}/scripts/imap.sh --count 1 >/dev/null
  │   │                       No  ──► references/authentication.md
  │   Yes
  │   ▼
  ├─ What does the user want?
  │   ├─ Browse / list           ──► imap.sh --count N [--folder F]
  │   ├─ Search                  ──► imap.sh --search "TERM" [--count N]
  │   ├─ Read one message        ──► imap.sh "$MAILID"
  │   ├─ Read HTML version       ──► imap.sh --html "$MAILID"  → save to file
  │   ├─ Save raw .eml           ──► imap.sh --raw "$MAILID" > file.eml
  │   ├─ Get attachment          ──► imap.sh "$MAILID" "$ATT_NAME" > file
  │   └─ Anything multi-step     ──► references/recipes.md
  │
  └─ Errors? ─────────────────────► references/troubleshooting.md

Output style

After running the wrapper, present results in this shape:

• One-line status of what just ran (e.g. "Listed the 10 most recent messages in INBOX").
• A compact table or bullet list of message metadata (date, from, subject, ID).
• Any file paths where larger output was saved.
• Suggested next actions (e.g. "Want me to open #4582 or save its attachments?").

Keep it scannable.