IMAP mail

The scheduler checks every five minutes and each connection polls when its configured interval has elapsed. Another Collect now queues a poll for that connection; manual actions and scheduled runs both respect the interval from the last attempt, including failed attempts, and a request made too early is skipped. Changing the interval retains the mailbox checkpoint. Actual collection can occur on a later scheduler tick or after a queue delay, and busy queues can delay polling beyond five minutes; connection order rotates to share worker capacity.

Admin → Ingest runners → Run IMAP polls all enabled IMAP connections. It queues background work, so the confirmation means the work was queued; inspect each connection's collection health for results. The button is hidden when IMAP is disabled, and paused ingestion must be resumed first. Providers requiring OAuth-only authentication need another supported collection route.

Only verified implicit TLS is supported; fix an invalid or expired certificate at the server, because verification cannot be disabled. Private destinations require explicit entries in KEEN_INGESTION_ALLOWED_CIDRS, and loopback and link-local addresses remain prohibited. Passwords are encrypted; blank password fields preserve an existing credential, and changing the host, port or username requires re-entering it.

File-managed connections use type imap, configuration fields host, port, username, folder, fetch_body, body_max_chars and poll_interval_minutes, an empty inputs object, and a password secret reference. Store configuration values as strings, including "true" or "false".

Each poll handles at most ten messages within a 100-UID window, up to 4 MiB of responses, and a 45-second collection alarm that also stops slow-drip responses; the parent terminates a stalled collector subprocess after 55 seconds. Headers and MIME metadata have separate bounds. The collector may return fewer messages to keep its serialised JSON output within 5 MiB, and remaining messages are picked up by a later poll; Unicode escaping can use more output bytes than the original text. Unsolicited literals and additional literals within one fetch are rejected before their payload is read, and contradictory mailbox UID metadata stops the poll.

Only a bounded partial body is fetched; mail.body_truncated records truncation and mail.body_omitted_reason explains omissions. Related MIME resources are excluded, and a related body whose root cannot be identified is omitted. Supported body charsets are UTF-8, ASCII, Latin-1 and Windows-1252; unsupported charsets or invalid transfer encodings omit the body with reason invalid_or_unsupported_body_encoding while headers are retained. Headers-only polling avoids MIME body structure entirely. The JSON artifact contains selected headers and the optional body; the actor and system display labels are limited to 128 characters after redaction and masking, and fuller bounded header values remain in the payload and artifact.

Failed polls keep their checkpoint and use exponential backoff from two minutes to one hour; the next attempt waits for both that backoff and the configured interval. Inspect the worker result and logs, verify credentials and TLS, and investigate oversized headers or malformed MIME structure in the mailbox. Disabling body collection avoids BODYSTRUCTURE failures while continuing to collect headers; protocol identity or size failures still stop the poll. The dedicated worker must be running to consume the imap queue; the ordinary worker does not.

If the server changes UIDVALIDITY, collection pauses: review the mailbox, disable the old connection and create a replacement to establish a new baseline. Replacing or changing the account or folder can leave earlier uncollected mail outside that baseline, and there is no automatic historical backfill.