{"id":50696302,"url":"https://github.com/codd-tech/imap-client","last_synced_at":"2026-06-09T06:32:47.574Z","repository":{"id":353849961,"uuid":"1221149854","full_name":"codd-tech/imap-client","owner":"codd-tech","description":" Agent skill: read \u0026 search IMAP mailboxes from the CLI via myl. For OpenClaw, Claude Code, AgentSkills. Gmail / Yandex / Mail.ru / autodiscovery.","archived":false,"fork":false,"pushed_at":"2026-04-25T21:59:34.000Z","size":26,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T22:29:25.024Z","etag":null,"topics":["agent-skill","agent-skills","claude-skill","clawhub","cli","email","email-client","gmail","imap","mail-ru","openclaw","yandex-mail"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/codd-tech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-25T20:21:49.000Z","updated_at":"2026-04-25T22:00:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/codd-tech/imap-client","commit_stats":null,"previous_names":["codd-tech/imap-client"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/codd-tech/imap-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codd-tech%2Fimap-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codd-tech%2Fimap-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codd-tech%2Fimap-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codd-tech%2Fimap-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codd-tech","download_url":"https://codeload.github.com/codd-tech/imap-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codd-tech%2Fimap-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34095244,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","agent-skills","claude-skill","clawhub","cli","email","email-client","gmail","imap","mail-ru","openclaw","yandex-mail"],"created_at":"2026-06-09T06:32:46.005Z","updated_at":"2026-06-09T06:32:47.569Z","avatar_url":"https://github.com/codd-tech.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# imap-client\n\n[![Install via ClawHub](https://img.shields.io/badge/install-clawhub-2563eb?style=flat-square)](https://clawhub.ai/aggrrrh/imap-client)\n[![License: MIT](https://img.shields.io/github/license/codd-tech/imap-client?style=flat-square)](./LICENSE)\n[![Maintained by codd.tech](https://img.shields.io/badge/maintained%20by-codd.tech-f97316?style=flat-square)](https://codd.tech)\n[![Stars](https://img.shields.io/github/stars/codd-tech/imap-client?style=flat-square)](https://github.com/codd-tech/imap-client/stargazers)\n\nAn agent skill for [OpenClaw](https://openclaw.ai), Claude Code, and other AgentSkills-compatible runtimes. Lets the agent read, search, and download email over IMAP from the command line via the [`myl`](https://github.com/pschmitt/myl) CLI client.\n\n`myl` is a small read-only IMAP client. This skill teaches the agent **when** to reach for it, **how** to install it, **how to source credentials safely** from the runtime's environment-injection mechanism, and **which** flags to use for common tasks — without ever asking for the password mid-session.\n\n## What this skill enables\n\nOnce installed and configured once, the agent will recognise prompts like:\n\n- *\"check my inbox\"*\n- *\"any new email from Acme today?\"*\n- *\"find the email with the AWS invoice and save the PDF\"*\n- *\"show me the HTML version of the newsletter from yesterday\"*\n- *\"download all unread messages as `.eml` files\"*\n- *\"проверь почту на Яндексе\"*\n- *\"найди письмо от налоговой\"*\n\n…and translate them into safe `myl` invocations through the wrapper at `scripts/imap.sh`, summarising the result back in chat.\n\n## Provider support\n\nFirst-class support, with `IMAP_PROVIDER` shortcuts:\n\n- **Gmail** / Google Workspace (`IMAP_PROVIDER=gmail`)\n- **Yandex Mail** — `@yandex.ru`, `@yandex.com`, Yandex 360 custom domains (`IMAP_PROVIDER=yandex`)\n- **Mail.ru** — `@mail.ru`, `@bk.ru`, `@inbox.ru`, `@list.ru` (`IMAP_PROVIDER=mailru`)\n\nPlus autodiscovery for most other providers (Fastmail, iCloud, ISPs) and explicit `manual` mode for self-hosted / corporate servers.\n\n## Quick start\n\n### 1. Install `myl`\n\n```bash\npipx install myl\n```\n\n(Or `pip install --user myl`, or `nix run github:pschmitt/myl`.)\n\n### 2. Get an app-specific password from your provider\n\nAccount settings → app passwords / external app passwords. Direct links per provider in [`references/authentication.md`](./references/authentication.md).\n\n### 3. Install the skill\n\n**Recommended — via ClawHub:**\n\n```bash\nclawhub install imap-client\n```\n\n**Or clone directly:**\n\n```bash\n# OpenClaw\ngit clone https://github.com/codd-tech/imap-client ~/.openclaw/skills/imap-client\n\n# Claude Code\ngit clone https://github.com/codd-tech/imap-client ~/.claude/skills/imap-client\n\n# Generic AgentSkills runtime — drop the folder anywhere the runtime scans for SKILL.md\n```\n\nRestart the session. OpenClaw picks the skill up automatically. The skill declares `requires.bins: [\"myl\"]` so it filters itself out if `myl` isn't on `PATH` — you'll never get a half-broken state.\n\n### 4. Configure credentials — pick the method for your runtime\n\n**OpenClaw** (recommended for OpenClaw users) — edit `~/.openclaw/openclaw.json`:\n\n```json\n{\n  \"skills\": {\n    \"entries\": {\n      \"imap-client\": {\n        \"enabled\": true,\n        \"env\": {\n          \"IMAP_USER\": \"you@yandex.ru\",\n          \"IMAP_PASSWORD\": \"app-specific-password-here\",\n          \"IMAP_PROVIDER\": \"yandex\"\n        }\n      }\n    }\n  }\n}\n```\n\n```bash\nchmod 600 ~/.openclaw/openclaw.json\n```\n\nOpenClaw injects these into `process.env` per agent run. You configure once; every subsequent session has them.\n\n**Claude Code / generic shell** — export in `~/.bashrc` / `~/.zshrc`:\n\n```bash\nexport IMAP_USER='you@yandex.ru'\nexport IMAP_PASSWORD='app-specific-password-here'\nexport IMAP_PROVIDER='yandex'\n```\n\n**Headless / cron / fallback** — create `~/.config/imap-client/credentials`:\n\n```bash\nmkdir -p ~/.config/imap-client\ncat \u003e ~/.config/imap-client/credentials \u003c\u003c'EOF'\nIMAP_USER='you@yandex.ru'\nIMAP_PASSWORD='app-specific-password-here'\nIMAP_PROVIDER='yandex'\nEOF\nchmod 600 ~/.config/imap-client/credentials\n```\n\nThe wrapper refuses to source this file if its permissions are not `600` or `400`.\n\n### 5. Verify\n\nAsk the agent something like *\"check the latest five emails\"* — or run the wrapper directly:\n\n```bash\nbash ~/.openclaw/skills/imap-client/scripts/imap.sh --count 5\n```\n\n## Repo layout\n\n```\nimap-client/\n├── SKILL.md                       # Frontmatter + workflow + principles\n├── README.md                      # This file\n├── LICENSE                        # MIT\n├── .gitignore\n├── references/\n│   ├── installation.md            # pipx / pip / nix / source install paths + sandbox\n│   ├── authentication.md          # OpenClaw env injection + fallbacks; provider table\n│   ├── operations.md              # Full myl flag reference + folder names per provider\n│   ├── recipes.md                 # 11 multi-step workflows, including Yandex/Mail.ru\n│   └── troubleshooting.md         # Symptom-first error guide\n└── scripts/\n    ├── imap.sh                    # Credential-aware wrapper around myl\n    └── check_myl.sh               # Fast install detection\n```\n\n## Security model\n\nThe skill is opinionated about credentials. The short version:\n\n- Passwords never appear as literals in commands the agent generates.\n- The runtime's environment-injection mechanism (OpenClaw `skills.entries.\u003ckey\u003e.env`, or shell `export`, or the `chmod 600` creds file) is the source of truth.\n- The `imap.sh` wrapper reads env vars and constructs `myl` flags internally — the password is in the wrapper's process scope, never in the agent's command history.\n- App-specific passwords from each provider are the default recommendation; the skill explains where to generate them (Gmail, Yandex, Mail.ru, iCloud, Fastmail, Yahoo).\n- The agent is instructed not to echo, summarise, or persist the password anywhere.\n- For OpenClaw users, `apiKey` with a `SecretRef` (`{ source, provider, id }`) keeps the literal password out of `openclaw.json` entirely.\n\nSee [`references/authentication.md`](./references/authentication.md) for the full ruleset.\n\n## Limitations of `myl` itself\n\n`myl` is intentionally minimal. The skill will tell the user explicitly when their request is out of scope and suggest alternatives:\n\n| Want to… | Use instead |\n|---|---|\n| Send mail | `msmtp`, `mutt`, scripted SMTP |\n| Move / delete / label | `imap-tools`, the provider's web UI |\n| Sync to local maildir | `mbsync` (`isync`), `offlineimap`, `getmail` |\n| OAuth2 to Gmail / Outlook | Proton Bridge, `mbsync` + XOAUTH2, or app password fallback |\n\n## Contributing\n\nBug reports and PRs welcome. The skill itself is markdown plus two shell scripts — easy to read, easy to fork.\n\nWhen proposing changes, prefer:\n\n- additions to `references/` over additions to `SKILL.md` (keep the always-loaded part lean)\n- examples that don't paste credentials anywhere\n- behaviour changes that fail safely if the user's `myl` version is older than the skill assumes\n\n## Credits\n\n- [`myl`](https://github.com/pschmitt/myl) by Philipp Schmitt — the underlying CLI this skill wraps.\n- [OpenClaw](https://openclaw.ai) for the AgentSkills runtime, env injection mechanism, and skills format documented at https://docs.openclaw.ai/tools/skills.\n- Anthropic's [Skills documentation](https://docs.claude.com/en/docs/build-with-claude/skills) — structure and best-practice patterns.\n\n## About the maintainer\n\nBuilt and maintained by **[codd.tech](https://codd.tech)** — a boutique technical consultancy specialising in AI agent infrastructure, distributed systems, and platform engineering. We help product teams ship reliable agentic workflows in production: integration design, custom skill packs, OpenClaw / Claude / MCP deployments, and DevOps audits.\n\nHave a use case for agent-driven email automation, or want a custom skill built for your stack? **[Get in touch](https://codd.tech)**.\n\n## License\n\nMIT — see [`LICENSE`](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodd-tech%2Fimap-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodd-tech%2Fimap-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodd-tech%2Fimap-client/lists"}