imap

by ivangdavila

Install this Skill

curl -fsSL -o imap.zip https://skill.seembox.com/api/v1/skills/imap/download && unzip imap.zip

SKILL.md About

---
name: IMAP
slug: imap
version: 1.0.0
homepage: https://clawic.com/skills/imap
description: "Read, search, and sync IMAP mailboxes with UID-safe fetches, precise filters, and attachment-aware workflows."
changelog: "Built a deeper IMAP workflow for reliable mailbox review, incremental sync, safer flag handling, and attachment triage."
metadata: {"clawdbot":{"emoji":"📬","requires":{"bins":[]},"os":["linux","darwin","win32"]}}
---

## When to Use

Use this skill when the user needs to inspect or operate an IMAP mailbox across Gmail, Fastmail, ProtonMail Bridge, Exchange-compatible gateways, or self-hosted mail servers.

Activate it for inbox search, unread triage, header and body fetches, attachment handling, folder mapping, or incremental mailbox sync when correctness matters more than quick ad hoc scraping.

## Architecture

Memory lives in `~/imap/`. If `~/imap/` does not exist, run `setup.md`. See `memory-template.md` for the default structure and file templates.

```
~/imap/
├── memory.md       # activation defaults, mutation policy, preferred reporting style
├── accounts.md     # mailbox-specific endpoints, auth notes, and server capabilities
├── folder-map.md   # canonical folder mapping and provider quirks
├── sync-state.md   # UIDVALIDITY, last UID, MODSEQ, and sync checkpoints
└── playbooks.md    # saved mailbox workflows and reusable search recipes
```

## Quick Reference

Use these files when the current mailbox task needs more detail than the core rules provide.

| Topic | File |
|-------|------|
| Setup and activation defaults | `setup.md` |
| Memory and file templates | `memory-template.md` |
| Session planning and discovery | `session-strategy.md` |
| Search and fetch patterns | `search-and-fetch.md` |
| State, flags, and sync rules | `state-and-flags.md` |
| Attachment and MIME handling | `attachments.md` |
| Failure diagnosis and provider quirks | `troubleshooting.md` |

## Core Rules

### 1. Discover mailbox capabilities before making assumptions
- Identify server capabilities, namespace layout, delimiter behavior, and special-use folders before building commands or interpreting results.
- Check whether the server supports features such as `UIDPLUS`, `CONDSTORE`, `QRESYNC`, `MOVE`, or `XLIST` replacements.
- Folder names, archives, and flag behavior vary by provider, so do not hard-code Gmail semantics onto every mailbox.

### 2. Default to read-safe operations unless the user clearly wants mutation
- Start with safe inspection patterns such as capability discovery, folder listing, `EXAMINE`, header fetches, and targeted body retrieval.
- Treat delete, move, copy, expunge, and bulk flag updates as mutating actions that require either explicit user approval or a previously confirmed standing policy.
- If the user only asked to inspect or summarize mail, do not silently mark messages seen or alter mailbox state.

### 3. Use UIDs and durable sync markers, not volatile sequence numbers
- Sequence numbers shift as mail arrives or is removed, so they are unsafe for persistent tracking.
- For repeatable workflows, store `UIDVALIDITY`, last processed UID, and when available `HIGHESTMODSEQ` or related sync checkpoints in `~/imap/sync-state.md`.
- If `UIDVALIDITY` changes, treat prior cursors as invalid and rescan instead of trusting stale state.

### 4. Fetch the minimum data that answers the question
- Start with folder listing, counts, flags, and envelope or header data before downloading full bodies or attachments.
- Escalate to body sections, MIME structure, or attachments only when the user actually needs that detail.
- Smaller fetches reduce latency, bandwidth, and the chance of dragging sensitive content into unnecessary downstream processing.

### 5. Search with explicit server-side filters and report what they mean
- Prefer precise IMAP search constraints such as date ranges, sender, subject fragments, flags, size limits, or UID windows over broad mailbox scans.
- Be clear about whether the server search is header-only, text-oriented, charset-sensitive, or provider-specific in its matching behavior.
- When search semantics are ambiguous, explain the limitation and offer a narrower or confirmatory pass.

### 6. Treat MIME and attachments as structured data, not opaque blobs
- Read `BODYSTRUCTURE` or equivalent metadata before assuming where text lives or which parts are attachments.
- Distinguish inline parts from downloadable attachments, decode filenames safely, and preserve charset and transfer-encoding details.
- Avoid downloading large attachments unless needed, and report part identifiers, sizes, and media types first when triaging.

### 7. Keep credentials out of skill memory and scope network use tightly
- Store only non-secret connection notes, capabilities, and workflow preferences under `~/imap/`.
- Never ask the user to paste account passwords into memory files; use existing local auth flows, app passwords, OAuth-backed bridges, or other secure runtime mechanisms the environment already supports.
- Restrict network activity to the user-configured IMAP endpoint needed for the mailbox task at hand.

## IMAP Traps

- Treating message sequence numbers as stable identifiers -> follow-up fetches hit the wrong message after mailbox changes.
- Marking mail seen during a read-only review -> the user loses unread state without asking for it.
- Downloading entire folders to answer a narrow question -> latency, bandwidth, and privacy costs rise for no gain.
- Ignoring `UIDVALIDITY` resets -> incremental sync silently skips or duplicates messages.
- Assuming every server supports `MOVE`, `IDLE`, or Gmail-style special folders -> commands fail or behave differently across providers.
- Parsing attachments without checking MIME structure first -> inline parts, filenames, or charsets get misread.

## External Endpoints

| Endpoint | Data Sent | Purpose |
|----------|-----------|---------|
| User-configured IMAP or IMAPS server | authentication material handled by the runtime, mailbox commands, requested headers, bodies, flags, and attachments | list folders, search messages, fetch content, and update mailbox state when approved |

No other data is sent externally.

## Security & Privacy

Data that stays local:
- Activation defaults, provider quirks, sync checkpoints, and reusable playbooks stored under `~/imap/`
- Mailbox notes the user explicitly wants remembered for future sessions

Data that leaves your machine:
- Only the IMAP requests needed to talk to the configured mailbox server
- Message metadata, bodies, or attachments fetched from that mailbox when the current task requires them

This skill does NOT:
- store mailbox passwords or OAuth tokens in `~/imap/`
- assume mutating mailbox access is allowed by default
- send mailbox content to undeclared third parties
- treat sequence numbers as durable sync state

## Trust

By using this skill, data is exchanged with the user-configured mail provider or IMAP bridge.
Only use it with mailbox systems and local credential flows the user already trusts.

## Related Skills
Install with `clawhub install <slug>` if user confirms:
- `api` - use when the mailbox task is really an API integration or authenticated service wrapper problem.
- `http` - use when the work is request shaping, header debugging, or protocol inspection outside an IMAP session.
- `json` - use when mailbox results need structured transformation, normalization, or downstream machine-readable output.
- `code` - use when the user needs a full implementation, parser, or sync worker built and verified end to end.
- `bash` - use for shell-first mailbox tooling, local automation, and repeatable command wrappers.

## Feedback

- If useful: `clawhub star imap`
- Stay updated: `clawhub sync`

_meta.json Metadata

{
  "ownerId": "kn73vp5rarc3b14rc7wjcw8f8580t5d1",
  "publishedAt": 1773734912556,
  "slug": "imap",
  "version": "1.0.0"
}