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:

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

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//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-.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.