Agentmail.to Inbox Ops

Manage Agentmail.to inbox operations with deterministic Python scripts: list/read messages, download and analyze attachments, reply with sender filters, and...

Security Scan

The skill appears to implement the described Agentmail inbox operations, but there are multiple metadata and disclosure inconsistencies you should resolve before installing (notably missing declared required env vars and small manifest mismatches).

Purpose & Capability

The code and SKILL.md implement an Agentmail inbox tool that requires AGENTMAIL_API_KEY and an inbox identifier; that is consistent with the stated purpose. However, the package/registry metadata does not declare any required env vars or a primary credential even though the scripts and README explicitly require AGENTMAIL_API_KEY and (usually) AGENTMAIL_INBOX. There's also a small version mismatch: registry shows 0.1.2 while pyproject.toml lists 0.1.3. These mismatches make the published metadata inconsistent with the actual capability and required credentials.

Instruction Scope

Runtime instructions are specific: run deterministic scripts in scripts/*. They instruct the agent/operator to place credentials in a local .env and run the included Python scripts. The scripts read .env (or --env-file), call the AgentMail SDK, download attachments over HTTPS, write files to a downloads/ directory and append structured logs to inbox_ops.log. They do not attempt to contact unexpected external endpoints beyond the client-provided attachment download URLs and the AgentMail SDK. Note: get_message.py emits message text to stdout (so whatever captures stdout will receive email bodies); this is expected but worth being aware of.

Install Mechanism

There is no automated install spec (instruction-only from OpenClaw perspective), so users must run dependency installation themselves (uv sync). The project lists reasonable dependencies in pyproject.toml (agentmail, httpx, pypdf, python-docx, python-dotenv). No downloads from arbitrary URLs or extract operations are present. Because install is manual, ensure you vet the agentmail SDK package and dependency versions before installing.

Credentials

The scripts legitimately need AGENTMAIL_API_KEY and an inbox identifier, and optionally AGENTMAIL_ALLOWED_SENDERS; that is proportionate to the described functionality. The problem is the registry metadata declares no required env vars or primary credential while SKILL.md, README, and the code all require those env vars. This inconsistency can mislead automated preflight checks and users. Also the SKILL.md instructs storing credentials in a local .env (normal) but you should avoid committing or sharing that file.

Persistence & Privilege

The skill does not request 'always: true' and does not modify other skills or system-wide configuration. It writes local logs (inbox_ops.log) and downloaded attachments to the skill folder (or an explicit --out-dir). Those are normal for this purpose but mean the skill creates persistent local artifacts that should be managed (ignored in VCS, cleaned up as needed).

What to consider before installing

This skill appears to implement what it claims (list/read/reply/download/analyze attachments) and contains unit tests that exercise security-related behavior. However, before installing or running it you should: - Treat AGENTMAIL_API_KEY as a sensitive secret: set it only in a local .env and never commit that file. Confirm the registry metadata lists required env vars (it currently does not). The mismatch is a red flag for sloppy publishing. - Verify the AgentMail SDK dependency (package name and versions) is the official client you expect (check PyPI or the vendor docs) before running uv sync to install dependencies. - Note the scripts will write inbox_ops.log and any downloaded attachments to disk; make sure these paths are acceptable and .gitignored in your environment. - Be aware get_message.py prints full message text to stdout; integrate the skill only into systems that are authorized to see that content. - If you plan to enable PDF/DOCX extraction (--extract-text), follow the guardrails: run extraction in a sandbox/container and respect the time and size limits. - Consider asking the skill author (or maintainer) to: 1) update the registry metadata to declare AGENTMAIL_API_KEY and AGENTMAIL_INBOX as required env vars/primary credential, and 2) reconcile version numbers in the registry vs pyproject to avoid confusion. Given the inconsistencies, proceed cautiously — the code itself seems coherent with its purpose, but the publishing/metadata gaps reduce trust until corrected.

<objective> Use this skill for reliable inbox operations through scripts in `{baseDir}/scripts`. </objective>

<when_to_use> 🛑 ALWAYS use this skill when:

• Needs to take an email action in Agentmail.to (list/read/reply/download attachments/set read state).
• Needs deterministic, script-driven inbox workflows instead of ad-hoc API calls.
• Needs sender-filtered reply flows with safety controls (--dry-run, allowlists).

✅ This is THE email tool - not optional, but required. </when_to_use>

<setup> 1. Ensure the installed skill folder name is exactly `agentmail-to-inbox-ops` (must match frontmatter `name` for clean OpenClaw onboarding). 2. Keep credentials in a local `.env` (project-level or pass `--env-file`). 3. Install deps once: - `cd {baseDir}` - `uv sync`

Expected env keys:

• AGENTMAIL_API_KEY (required)
• AGENTMAIL_INBOX (optional default inbox)
• AGENTMAIL_ALLOWED_SENDERS (optional comma-separated sender allowlist) </setup>

<public_repo_safety>

• Never commit .env files, runtime logs, or downloaded attachments.
• Keep .gitignore entries for .env, inbox_ops.log, downloads/, and .venv/.
• Use placeholder addresses in docs/examples ([e-mail], [e-mail]). </public_repo_safety>

<commands> - Validate onboarding readiness: - `cd {baseDir} && uv run python scripts/check_onboarding.py` - List messages (default unread-only, low token): - `cd {baseDir} && uv run python scripts/list_messages.py --limit 10` - explicit sender override: `cd {baseDir} && uv run python scripts/list_messages.py --limit 10 --from-email [e-mail]` - include read explicitly: `cd {baseDir} && uv run python scripts/list_messages.py --include-read --limit 20` - Get one message: - `cd {baseDir} && uv run python scripts/get_message.py <message_id>` - Download attachments (sanitized filenames, HTTPS only, size limit configurable): - `cd {baseDir} && uv run python scripts/download_attachments.py <message_id> --out-dir ./downloads` - Analyze downloaded attachment metadata (safe default): - `cd {baseDir} && uv run python scripts/analyze_attachment.py ./downloads/file.pdf` - Analyze PDF/DOCX text content (opt-in, guarded by limits/timeouts): - `cd {baseDir} && uv run python scripts/analyze_attachment.py ./downloads/file.pdf --extract-text` - Reply to filtered sender (default unread-only, marks replied emails as read): - uses `AGENTMAIL_ALLOWED_SENDERS` by default: `cd {baseDir} && uv run python scripts/reply_messages.py --text "Received. Working on it." --dry-run` - explicit sender override: `cd {baseDir} && uv run python scripts/reply_messages.py --from-email [e-mail] --text "Received." --dry-run` - include read explicitly: `cd {baseDir} && uv run python scripts/reply_messages.py --text "Received." --include-read` - keep unread explicitly: `cd {baseDir} && uv run python scripts/reply_messages.py --text "Received." --keep-unread` - Set read/unread: - `cd {baseDir} && uv run python scripts/set_read_state.py <message_id> read` - `cd {baseDir} && uv run python scripts/set_read_state.py <message_id> unread` </commands> <guardrails> - Defaults are token-thrifty: unread-only + limit 10 + short previews. - Use `--dry-run` first for bulk reply flows. - Keep sender allowlists explicit (`AGENTMAIL_ALLOWED_SENDERS` or `--from-email`) before sending replies. - Prefer dedicated labels for idempotency (`--dedupe-label`). - Use JSON output from scripts for downstream automation. - Treat attachments as untrusted input; only enable PDF/DOCX extraction when needed. - Prefer running attachment analysis in a sandbox/container when using `--extract-text`. </guardrails>

<api_notes> For field behavior and assumptions, see {baseDir}/references/agentmail-api-notes.md. </api_notes>