IMAP email

What it scans

By default only messages that have attachments are read, and only their attachment names and attachment files of supported types are classified; never message bodies. Subject lines are opt-in with the connection setting Also scan subject lines (slower): when it is on, every message's Subject line is classified together with its From, To and Date headers; sender and recipient address headers alone do not produce contact-information findings. Folders are opened read-only and section reads use PEEK so mail is not marked as read. PDF, DOCX, XLSX, PPTX and other full-support structured formats use the normal whole-file parser up to max_parse_bytes; supported text files use normal text sampling. Unsupported strings-only/binary types and nested message/rfc822 attachments are skipped with recorded reasons. For message body scanning, use Microsoft 365 or Google Workspace.

What you need

An agent that can reach an IMAP server with a trusted TLS certificate, and a username/password accepted by that server. Use a dedicated read-only mailbox account or a separately revocable app password. OAuth-only IMAP accounts cannot use this password-based connector.

Connection settings table

Explicitly check Port when changing types: the shared form may retain a previous value. The connector's default port is 993, including when STARTTLS is selected; set 143 yourself for STARTTLS.

Secret file

Save /srv/myrikeep/secrets/IMAP_MAIL:

{"username": "[email protected]", "password": "<MAILBOX_OR_APP_PASSWORD>"}

Merge this catalog entry:

{"version": 1, "credentials": {"IMAP_MAIL": {"type": "imap", "source": {"kind": "file_json", "path": "/run/secrets/IMAP_MAIL"}}}}

All values must be nonempty strings. Follow Agent credentials for file modes and the directory mount. Revoked app passwords can still report present until a scan attempts provider login.

Scope, exclusions and schedules

Folder prefix is a case-sensitive starts-with match: INBOX includes INBOX and INBOX/Receipts. There is no IMAP received-after console field. Exclude globs match pseudo-paths like INBOX 123.eml (subject/header block, only when subject-line scanning is on), INBOX 123.txt (attachment names, present for every message that has attachments), and INBOX 123/2-report.pdf (attachment file, with its MIME section as index and a sanitized filename). Messages without attachments produce no pseudo-files unless subject-line scanning is on. *.pdf prevents PDF file downloads and classification while retaining attachment-name classification. INBOX* skips all files in folders beginning INBOX; *.txt skips attachment-name metadata and TXT attachment files. Prefer Folder prefix to choose mail folders. Attachment locators are imap://<folder>/<uid>#att=<section> (e.g. #att=2.1); existing #headers and #attachments locators remain unchanged. See Getting started for schedules.

Large mailboxes and Gmail limits

Use Connections → View/edit → Advanced: IMAP attachments and throttling to tune each IMAP connection. The settings stay in non-secret connection config and travel to agents that advertise imap-throttle-v1; attachment options require imap-attachments-v1, and the daily-budget and subject-line options require imap-budget-v1. Older agents receive only settings they understand. New agents use the defaults below when an older server omits the keys. Leave a numeric field blank for its automatic default; an explicit zero keeps its documented meaning.

The preset applies to gmail.com and googlemail.com, including their subdomains such as imap.gmail.com: batches of 100, five reconnect attempts and a 1,500 MB daily download budget, because Google limits daily IMAP downloads per account. These are conservative scanner defaults, not Google's published quotas or a guarantee against throttling. Explicit settings override the preset individually. Older agents omit these options until upgraded.

By default the connector does not pace itself: pause and message ceiling are zero. Pacing starts only after the server first pushes back (BYE, a throttled or too-many response, an aborted session or a socket error); values you did not set explicitly then rise to a 250 ms batch pause and a 1,500-message ceiling for the rest of the scan. Values you set explicitly apply from the start and are never raised.

The daily download budget is per mailbox, in decimal MB, and is spent by every downloaded FETCH response, metadata included. When the remaining budget is smaller than an attachment's encoded size, that attachment is skipped with the recorded reason daily download budget reached; the next scan will pick it up; metadata keeps being fetched, so attachment names still classify. The budget recovers on a rolling 24-hour window: a new scan starts with the limit minus what this connection's finished scans reported downloading in the last 24 hours. Zero means no budget.

The scanner selects a folder once per session and fetches header fields, BODYSTRUCTURE and INTERNALDATE together for up to one batch. Unless subject-line scanning is on, only messages with attachments are enumerated: Gmail connections and servers advertising X-GM-EXT-1 search X-GM-RAW "has:attachment" (falling back to listing every message when the server refuses), and the cached BODYSTRUCTURE filters out messages without attachments on every server. It caches only that batch's responses and uses them for both header and attachment-name reads. It never requests message bodies. Attachment enumeration uses that same cached BODYSTRUCTURE. Supported files under the encoded-size cap are fetched separately with UID FETCH <uid> (BODY.PEEK[<section>]), decoded from base64, quoted-printable or unencoded 7bit/8bit/binary, and passed to the normal runner. No BODY[], BODY[TEXT] or body text sections are requested. Encoded sizes make the gate conservative (base64 files near the decoded cap can be skipped). Only one decoded attachment is cached at a time. Each attachment FETCH shares batch pauses, rate pacing, socket timeout and reconnect/backoff with metadata.

On BYE, an aborted session, socket/TLS errors, timeouts or throttling responses, the agent closes the broken socket, waits with exponential backoff and jitter (capped at 60 seconds), logs in again and reselects the folder. It retries the same UID batch or attachment section. If retries run out, that batch or file is recorded as a read error; the next operation starts with a fresh connection. Every pseudo-file still gets at most one classification observation. Long pacing waits renew the lease.

Review Scans for read-error totals and classes, reconnects and throttle waits. Agent warnings report only the error class, folder and UID: the first 20 errors, then every 500th. Subjects, addresses and server error text are excluded. A scan with read errors has incomplete coverage even if it completes.

"Who can see it" support

Sharing checks are not available for this source yet. No forwarding rules, mailbox delegates or message recipient access are assessed. INTERNALDATE gives received-age review; the sender's Date header is not the age basis. See Who can see it.

Troubleshooting

Limits

No message bodies, sending, deletion, mark-as-read or folder changes. By default reads attachment names and attachment files of supported types on messages that have them; Subject lines only when Also scan subject lines (slower) is on. Attachment files default to 10 MiB encoded size and 100 parts per message; larger files, unsupported types and embedded messages are skipped. Stats include attachments_scanned, attachments_skipped_too_large, attachments_skipped_type, attachments_skipped_nested, attachments_skipped_limit and attachments_skipped_budget. Attachment names remain classified even when attachment scanning is disabled or a file is skipped; headers only when subject-line scanning is on. No server or mailbox discovery. Metadata reads are capped at 64 KiB per part. Unselectable/newline-named folders are skipped. Review Coverage and account permissions if expected mail is missing.