skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
tiangong-ai/agent-skills94 installs

email-imap-full-fetch

Fetch full email MIME content and attachment files from IMAP by message reference. Use when downstream steps already have a stage-1 mail_ref and need full headers/body/attachments for a specific message, with message_id_norm as the primary lookup key and uid only as fallback.

How do I install this agent skill?

npx skills add https://github.com/tiangong-ai/agent-skills --skill email-imap-full-fetch
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill fetches email content and attachments from an IMAP server. It includes robust security practices such as filename sanitization to prevent path traversal, attachment size limits, and extension filtering. Like all skills that ingest external data, it is susceptible to indirect prompt injection if the fetched email content contains malicious instructions designed to influence the agent's behavior.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 1 issue

What does this agent skill do?

Email IMAP Full Fetch

Core Goal

  • Fetch one target email by stable message reference from IMAP.
  • Enforce lookup order: HEADER Message-Id exact match first, then uid fallback.
  • Download full raw MIME via BODY.PEEK[].
  • Parse and return headers, full text body, html body, and attachment metadata.
  • Save .eml and attachment files to disk with filename safety and idempotent indexing.

Standard Flow

  1. Input must include message_id_norm from stage-1 routing output (mail_ref.message_id_norm).
  2. Use fetch --message-id "<message_id_norm or raw Message-Id>" as the default path.
  3. Use fetch --uid "<uid>" only when no usable message-id is available.
  4. Keep mailbox selection consistent with stage-1 (--mailbox or IMAP_MAILBOX).
  5. Read JSON output and continue downstream processing with returned mail_ref.

Commands

Fetch by Message-Id (preferred):

python3 scripts/imap_full_fetch.py fetch --message-id "<caa123@example.com>"

Fetch by UID (fallback only):

python3 scripts/imap_full_fetch.py fetch --uid "123456"

Use both when needed (message-id lookup first, uid fallback second):

python3 scripts/imap_full_fetch.py fetch --message-id "<caa123@example.com>" --uid "123456"

Output Contract

  • Output is a single JSON object.
  • Required top-level fields:
    • mail_ref
    • headers
    • text_plain
    • text_html
    • attachments
    • saved_eml_path
  • mail_ref contains:
    • account, mailbox, uid, message_id_raw, message_id_norm, date
  • attachments[] contains per-file metadata and persistence result:
    • filename, content_type, bytes, disposition, saved_path, skipped_reason

Storage And Idempotency

  • saved_eml_path points to local .eml file saved from BODY.PEEK[].
  • Attachments are saved without returning attachment binary content in JSON.
  • Filenames are sanitized to remove path separators and unsafe characters.
  • Duplicate attachment names are deduped with content-hash suffix.
  • Repeated requests are idempotent by message_id_norm index and return existing persisted JSON record directly.

Parameters

  • --message-id: primary lookup key.
  • --uid: fallback lookup key.
  • --mailbox: mailbox to query (default IMAP_MAILBOX or INBOX).
  • --save-eml-dir: target dir for .eml files (env IMAP_FULL_SAVE_EML_DIR).
  • --index-dir: target dir for idempotency index JSON files (env IMAP_FULL_INDEX_DIR, default <save-eml-dir>/.index).
  • --save-attachments-dir: target dir for attachments (env IMAP_FULL_SAVE_ATTACHMENTS_DIR).
  • --max-attachment-bytes: max saved attachment size (env IMAP_FULL_MAX_ATTACHMENT_BYTES).
  • --allow-ext: allowed attachment extensions, comma-separated (env IMAP_FULL_ALLOW_EXT).
  • --connect-timeout: IMAP connect timeout seconds (default from IMAP_CONNECT_TIMEOUT).

Required Environment

  • IMAP_HOST
  • IMAP_USERNAME
  • IMAP_PASSWORD

Optional account defaults:

  • IMAP_NAME
  • IMAP_PORT
  • IMAP_SSL
  • IMAP_MAILBOX

Scripts

  • scripts/imap_full_fetch.py

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/tiangong-ai/agent-skills/email-imap-full-fetch">View email-imap-full-fetch on skillZs</a>