codd-tech/imap-client

imap-client은(는) 무엇을 하나요?

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 never appear in commands you generate

Because env vars are injected by the runtime, the wrapper handles them internally. Do not generate commands like myl -p hunter2 or myl -p "$IMAP_PASSWORD" directly — both leak. The first lands in shell history; the second exposes the password in /proc/<pid>/cmdline while myl runs. Use the wrapper, which keeps the password inside its own process scope:

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

The wrapper passes credentials to myl via stdin where supported and otherwise via flags it constructs internally — same trade-off as direct myl use, but the password literal never appears in any command you wrote, logged, or showed the user.

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.