imap-mail

Files (1)

• SKILL.md

SKILL.md (first lines)

# IMAP Mail Skill

Read and manipulate email via IMAP using Python stdlib only — no external packages. Any IMAP server works; examples below assume TLS on port 993.

## Prerequisites

Four environment variables (configure from the portal Settings → Skills → IMAP Mail):

- `IMAP_HOST` — e.g. `imap.gmail.com`, `imap.mail.me.com`, `127.0.0.1` (Proton Bridge), `imap.fastmail.com`
- `IMAP_USER` — full email address
- `IMAP_PASSWORD` — an app-specific password, NOT the main account password
  - Gmail: https://myaccount.google.com/apppasswords (requires 2FA enabled)
  - iCloud: https://appleid.apple.com → App-Specific Passwords
  - Proton: Proton Bridge generates a local password
  - Fastmail: Settings → Privacy & Security → App Passwords
- `IMAP_PORT` — optional, defaults to 993 (TLS)

## List recent messages

```bash
python3 - <<'PY'
import os, imaplib, email
from email.header import decode_header

M = imaplib.IMAP4_SSL(os.environ["IMAP_HOST"], int(os.environ.get("IMAP_PORT", 993)))
M.login(os.environ["IMAP_USER"], os.environ["IMAP_PASSWORD"])
M.select("INBOX", readonly=True)

typ, data = M.search(None, "ALL")
ids = data[0].split()[-20:]  # last 20 messages

for mid in reversed(ids):
    typ, d = M.fetch(mid, "(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE)])")
    hdr = email.message_from_bytes(d[0][1])
    def dec(v):
        parts = decode_header(v or "")
        return "".join(p.decode(c or "utf-8", "replace") if isinstance(p, bytes) else p for p, c in parts)
    print(f"[{mid.decode()}] {dec(hdr['Date']):25} | {dec(hdr['From']):40} | {dec(hdr['Subject'])}")

M.logout()
PY
```

Use `readonly=True` on SELECT whenever you are not modifying state — it prevents \Seen flag changes.

## List unread only

```bash
python3 - <<'PY'
import os, imaplib, email
from email.header import decode_header

M = imaplib.IMAP4_SSL(os.environ["IMAP_HOST"], int(os.environ.get("IMAP_PORT", 993)))
M.login(os.environ["IMAP_USER"], os.environ["IMAP_PASSWORD"])
M.select("INBOX", readonly=True)
typ, data = M.search(None, "UNSEEN")
unread_ids = data[0].split()
print(f"{len(unread_ids)} unread")

for mid in unread_ids[-30:]:
    typ, d = M.fetch(mid, "(BODY.PEEK[HEADER.FIELDS (FROM SUBJECT DATE)])")
    hdr = email.message_from_bytes(d[0][1])
    def dec(v):
        parts = decode_header(v or "")
        return "".join(p.decode(c or "utf-8", "replace") if isinstance(p, bytes) else p for p, c in parts)
    print(f"[{mid.decode()}] {dec(hdr['From']):40} | {dec(hdr['Subject'])}")

M.logout()
PY
```

## Search

IMAP search syntax — no quotes around field tokens, quoted strings only for values containing spaces:

```bash
python3 - <<'PY'
import os, imaplib
M = imaplib.IMAP4_SSL(os.environ["IMAP_HOST"], int(os.environ.get("IMAP_PORT", 993)))
M.login(os.environ["IMAP_USER"], os.environ["IMAP_PASSWORD"])
M.select("INBOX", readonly=True)

# Examples — replace criteria as needed:
# - FROM "alice@example.com"
# - SUBJECT "invoice"
# - SINCE 01-Jan-2025
# - UNSEEN
# - TEXT "refund"
# - LARGER 5000000  (bytes)

typ, data = M.search(None, 'FROM "notifications@github.com"', 'SINCE', '01-Jan-2026')
ids = data[0].split()
print(f"{len(ids)} matches")
print([i.decode() for i in ids[-20:]])
M.logout()
PY
```

Combine criteria by passing them as separate positional args (implicit AND). For OR, prefix with `OR`:
```python
M.search(None, 'OR', 'FROM', '"alice@example.com"', 'FROM', '"bob@example.com"')
```

## Read a message (full body, including HTML + attachments list)

```bash
python3 - <<'PY'
import os, imaplib, email, sys
from email.header import decode_header

MSG_ID = sys.argv[1] if len(sys.argv) > 1 else "1"

M = imaplib.IMAP4_SSL(os.environ["IMAP_HOST"], int(os.environ.get("IMAP_PORT", 993)))
M.login(os.environ["IMAP_USER"], os.environ["IMAP_PASSWORD"])
M.select("INBOX", readonly=True)
typ, data = M.fetch(MSG_ID.encode(), "(RFC822)")
msg = email.message_from_bytes(data[0][1])

def dec(v):

From HaraldeRoessler/ownify-microclaw, MIT.

More from HaraldeRoessler/ownify-microclaw