@twin.org/mailbox-connector-imap 0.9.3-next.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 IOTA Stiftung.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,29 @@
+# TWIN Mailbox Connector IMAP
+
+This package implements an IMAP connector for email mailbox ingestion.
+
+## Installation
+
+```shell
+npm install @twin.org/mailbox-connector-imap
+```
+
+## Docker
+
+To perform testing of this component it may be necessary to launch a local instance to communicate with.
+
+```shell
+docker run -p 53025:3025 -p 58027:8080 -p 53143:3143 --name twin-messaging-imap -d -e GREENMAIL_OPTS="-Dgreenmail.setup.test.all -Dgreenmail.hostname=0.0.0.0 -Dgreenmail.users=test:test@localhost -Dgreenmail.verbose" greenmail/standalone:2.1.3
+```
+
+## Examples
+
+Usage of the APIs is shown in the examples [docs/examples.md](docs/examples.md)
+
+## Reference
+
+Detailed reference documentation for the API can be found in [docs/reference/index.md](docs/reference/index.md)
+
+## Changelog
+
+The changes between each version can be found in [docs/changelog.md](docs/changelog.md)

package/dist/es/configSchema/imapEmailConnectorConfigSchema.js

@@ -0,0 +1,51 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+import { EntitySchemaPropertyType } from "@twin.org/entity";
+/**
+ * The configuration field schema for IMAP connectors.
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const ImapEmailConnectorConfigSchema = [
+    {
+        labelKey: "imapEmailConnectorConfigSchema.host",
+        propertyKey: "host",
+        type: EntitySchemaPropertyType.String
+    },
+    {
+        labelKey: "imapEmailConnectorConfigSchema.port",
+        propertyKey: "port",
+        type: EntitySchemaPropertyType.Integer,
+        defaultValue: 993
+    },
+    {
+        labelKey: "imapEmailConnectorConfigSchema.secure",
+        propertyKey: "secure",
+        type: EntitySchemaPropertyType.Boolean,
+        defaultValue: true
+    },
+    {
+        labelKey: "imapEmailConnectorConfigSchema.username",
+        propertyKey: "username",
+        type: EntitySchemaPropertyType.String
+    },
+    {
+        labelKey: "imapEmailConnectorConfigSchema.password",
+        propertyKey: "password",
+        type: EntitySchemaPropertyType.String,
+        isSecure: true
+    },
+    {
+        labelKey: "imapEmailConnectorConfigSchema.folders",
+        propertyKey: "folders",
+        type: EntitySchemaPropertyType.Array,
+        itemType: EntitySchemaPropertyType.String,
+        defaultValue: ["INBOX"]
+    },
+    {
+        labelKey: "imapEmailConnectorConfigSchema.pollingIntervalMinutes",
+        propertyKey: "pollingIntervalMinutes",
+        type: EntitySchemaPropertyType.Integer,
+        defaultValue: 2
+    }
+];
+//# sourceMappingURL=imapEmailConnectorConfigSchema.js.map

package/dist/es/configSchema/imapEmailConnectorConfigSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imapEmailConnectorConfigSchema.js","sourceRoot":"","sources":["../../../src/configSchema/imapEmailConnectorConfigSchema.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAG5D;;GAEG;AACH,gEAAgE;AAChE,MAAM,CAAC,MAAM,8BAA8B,GAA0B;IACpE;QACC,QAAQ,EAAE,qCAAqC;QAC/C,WAAW,EAAE,MAAM;QACnB,IAAI,EAAE,wBAAwB,CAAC,MAAM;KACrC;IACD;QACC,QAAQ,EAAE,qCAAqC;QAC/C,WAAW,EAAE,MAAM;QACnB,IAAI,EAAE,wBAAwB,CAAC,OAAO;QACtC,YAAY,EAAE,GAAG;KACjB;IACD;QACC,QAAQ,EAAE,uCAAuC;QACjD,WAAW,EAAE,QAAQ;QACrB,IAAI,EAAE,wBAAwB,CAAC,OAAO;QACtC,YAAY,EAAE,IAAI;KAClB;IACD;QACC,QAAQ,EAAE,yCAAyC;QACnD,WAAW,EAAE,UAAU;QACvB,IAAI,EAAE,wBAAwB,CAAC,MAAM;KACrC;IACD;QACC,QAAQ,EAAE,yCAAyC;QACnD,WAAW,EAAE,UAAU;QACvB,IAAI,EAAE,wBAAwB,CAAC,MAAM;QACrC,QAAQ,EAAE,IAAI;KACd;IACD;QACC,QAAQ,EAAE,wCAAwC;QAClD,WAAW,EAAE,SAAS;QACtB,IAAI,EAAE,wBAAwB,CAAC,KAAK;QACpC,QAAQ,EAAE,wBAAwB,CAAC,MAAM;QACzC,YAAY,EAAE,CAAC,OAAO,CAAC;KACvB;IACD;QACC,QAAQ,EAAE,uDAAuD;QACjE,WAAW,EAAE,wBAAwB;QACrC,IAAI,EAAE,wBAAwB,CAAC,OAAO;QACtC,YAAY,EAAE,CAAC;KACf;CACD,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport { EntitySchemaPropertyType } from \"@twin.org/entity\";\nimport type { IMailboxConfigField } from \"@twin.org/mailbox-models\";\n\n/**\n * The configuration field schema for IMAP connectors.\n */\n// eslint-disable-next-line @typescript-eslint/naming-convention\nexport const ImapEmailConnectorConfigSchema: IMailboxConfigField[] = [\n\t{\n\t\tlabelKey: \"imapEmailConnectorConfigSchema.host\",\n\t\tpropertyKey: \"host\",\n\t\ttype: EntitySchemaPropertyType.String\n\t},\n\t{\n\t\tlabelKey: \"imapEmailConnectorConfigSchema.port\",\n\t\tpropertyKey: \"port\",\n\t\ttype: EntitySchemaPropertyType.Integer,\n\t\tdefaultValue: 993\n\t},\n\t{\n\t\tlabelKey: \"imapEmailConnectorConfigSchema.secure\",\n\t\tpropertyKey: \"secure\",\n\t\ttype: EntitySchemaPropertyType.Boolean,\n\t\tdefaultValue: true\n\t},\n\t{\n\t\tlabelKey: \"imapEmailConnectorConfigSchema.username\",\n\t\tpropertyKey: \"username\",\n\t\ttype: EntitySchemaPropertyType.String\n\t},\n\t{\n\t\tlabelKey: \"imapEmailConnectorConfigSchema.password\",\n\t\tpropertyKey: \"password\",\n\t\ttype: EntitySchemaPropertyType.String,\n\t\tisSecure: true\n\t},\n\t{\n\t\tlabelKey: \"imapEmailConnectorConfigSchema.folders\",\n\t\tpropertyKey: \"folders\",\n\t\ttype: EntitySchemaPropertyType.Array,\n\t\titemType: EntitySchemaPropertyType.String,\n\t\tdefaultValue: [\"INBOX\"]\n\t},\n\t{\n\t\tlabelKey: \"imapEmailConnectorConfigSchema.pollingIntervalMinutes\",\n\t\tpropertyKey: \"pollingIntervalMinutes\",\n\t\ttype: EntitySchemaPropertyType.Integer,\n\t\tdefaultValue: 2\n\t}\n];\n"]}

package/dist/es/imapEmailConnector.js

@@ -0,0 +1,236 @@
+import { BaseError, ComponentFactory, GeneralError, Guards, Is, Mutex } from "@twin.org/core";
+import { MailHelper } from "@twin.org/mailbox-models";
+import { ImapFlow } from "imapflow";
+/**
+ * IMAP email protocol connector. Polls configured folders for new messages using imapflow.
+ */
+export class ImapEmailConnector {
+    /**
+     * The class name.
+     */
+    static CLASS_NAME = "ImapEmailConnector";
+    /**
+     * The protocol namespace identifier.
+     */
+    static NAMESPACE = "imap";
+    /**
+     * The logging component.
+     * @internal
+     */
+    _logging;
+    /**
+     * The task scheduler component used for polling.
+     * @internal
+     */
+    _taskScheduler;
+    /**
+     * The resolved configuration for this connector instance.
+     * @internal
+     */
+    _config;
+    /**
+     * The identifier of the currently active instance being polled.
+     * @internal
+     */
+    _instanceId;
+    /**
+     * Set when retrieve has been called and cleared when retrieveStop is called.
+     * @internal
+     */
+    _retrieving;
+    /**
+     * The last successfully persisted connector state, updated after each successful callback.
+     * @internal
+     */
+    _state;
+    /**
+     * Create a new instance of ImapEmailConnector.
+     * @param options The options for the connector.
+     */
+    constructor(options) {
+        Guards.object(ImapEmailConnector.CLASS_NAME, "options", options);
+        Guards.object(ImapEmailConnector.CLASS_NAME, "options.config", options.config);
+        Guards.stringValue(ImapEmailConnector.CLASS_NAME, "options.config.host", options.config.host);
+        Guards.stringValue(ImapEmailConnector.CLASS_NAME, "options.config.username", options.config.username);
+        Guards.stringValue(ImapEmailConnector.CLASS_NAME, "options.config.password", options.config.password);
+        this._logging = ComponentFactory.getIfExists(options.loggingComponentType);
+        this._taskScheduler = ComponentFactory.get(options.taskSchedulerComponentType ?? "task-scheduler");
+        const secure = options.config.secure ?? true;
+        this._config = {
+            host: options.config.host,
+            port: options.config.port ?? (secure ? 993 : 143),
+            secure,
+            username: options.config.username,
+            password: options.config.password,
+            folders: options.config.folders ?? ["INBOX"],
+            pollingIntervalMinutes: Math.max(1, options.config.pollingIntervalMinutes ?? 2),
+            mutexTimeoutMs: options.config.mutexTimeoutMs
+        };
+        this._retrieving = false;
+    }
+    /**
+     * Get the class name.
+     * @returns The class name.
+     */
+    className() {
+        return ImapEmailConnector.CLASS_NAME;
+    }
+    /**
+     * Start the internal polling loop for the given instance.
+     * @param instanceId The identifier of the mailbox instance being polled.
+     * @param state The current connector state for the instance.
+     * @param authCallback Callback invoked when authentication fails during a poll cycle.
+     * @param retrievalCallback Callback invoked with retrieved messages after each poll cycle.
+     * @returns A promise that resolves when the polling loop has been started.
+     */
+    async retrieve(instanceId, state, authCallback, retrievalCallback) {
+        await this.retrieveStop();
+        this._retrieving = true;
+        this._instanceId = instanceId;
+        this._state = state;
+        await this._taskScheduler.addTask(instanceId, [{ intervalMinutes: this._config.pollingIntervalMinutes }], async () => {
+            await this.poll(authCallback, retrievalCallback);
+        });
+    }
+    /**
+     * Stop the polling loop for this connector.
+     * @returns A promise that resolves when the polling loop has been stopped.
+     */
+    async retrieveStop() {
+        if (Is.stringValue(this._instanceId)) {
+            this._retrieving = false;
+            await this._taskScheduler.removeTask(this._instanceId);
+            this._instanceId = undefined;
+            this._state = undefined;
+        }
+    }
+    /**
+     * Poll each configured folder for new messages.
+     * @param authCallback Callback invoked when authentication fails.
+     * @param retrievalCallback Callback invoked with retrieved messages.
+     * @internal
+     */
+    async poll(authCallback, retrievalCallback) {
+        if (Is.empty(this._state) || !Is.stringValue(this._instanceId)) {
+            return;
+        }
+        // Capture the instance id and state for this poll cycle, retrieveStop can clear the
+        // instance fields while a poll is in progress and the mutex must still be released
+        // under the key it was locked with.
+        const instanceId = this._instanceId;
+        const state = this._state;
+        await Mutex.lock(instanceId, {
+            timeoutMs: this._config.mutexTimeoutMs,
+            throwOnTimeout: true
+        });
+        const client = new ImapFlow({
+            host: this._config.host,
+            port: this._config.port,
+            secure: this._config.secure,
+            auth: { user: this._config.username, pass: this._config.password },
+            logger: false
+        });
+        try {
+            await client.connect();
+            for (const folder of this._config.folders) {
+                const continued = await this.pollFolder(client, folder, retrievalCallback);
+                if (!continued) {
+                    break;
+                }
+            }
+        }
+        catch (error) {
+            const pollError = new GeneralError(ImapEmailConnector.CLASS_NAME, "pollFailed", undefined, BaseError.fromError(error));
+            const rawError = Is.object(error)
+                ? error
+                : undefined;
+            const isAuthFailure = rawError?.authenticationFailed === true;
+            if (isAuthFailure) {
+                await authCallback(instanceId, state, true, undefined, pollError);
+            }
+            else {
+                await retrievalCallback(instanceId, undefined, state, pollError);
+            }
+        }
+        finally {
+            try {
+                await client.logout();
+                client.close();
+            }
+            catch {
+                // ignore, not much we can do if the connection is already closed
+                // but don't want to prevent the mutex from being unlocked in the finally block below
+            }
+            Mutex.unlock(instanceId);
+        }
+    }
+    /**
+     * Poll a single folder for messages with UIDs beyond the last seen UID.
+     * Each parsed message is forwarded to the retrieval callback; returning false aborts processing.
+     * @param client The connected ImapFlow client.
+     * @param folder The folder path to poll.
+     * @param retrievalCallback Callback invoked for each parsed email; return false to abort.
+     * @returns True if all messages were processed, false if processing was aborted.
+     * @internal
+     */
+    async pollFolder(client, folder, retrievalCallback) {
+        if (Is.empty(this._state) || !Is.stringValue(this._instanceId)) {
+            return true;
+        }
+        this._state.folders ??= {};
+        const folderState = this._state.folders[folder] ?? {};
+        this._state.folders[folder] = folderState;
+        const lock = await client.getMailboxLock(folder);
+        try {
+            if (!client.mailbox) {
+                return true;
+            }
+            const uidValidity = client.mailbox.uidValidity.toString();
+            if (folderState.uidValidity !== uidValidity) {
+                folderState.uidValidity = uidValidity;
+                folderState.lastUid = 0;
+            }
+            const lastUid = folderState.lastUid ?? 0;
+            const searchQuery = lastUid > 0 ? { uid: `${lastUid + 1}:*` } : { all: true };
+            const uids = await client.search(searchQuery, { uid: true });
+            if (uids !== false && Is.arrayValue(uids)) {
+                const msgStream = client.fetch(uids, { uid: true, source: true, flags: true }, { uid: true });
+                // Any early exit from this loop (return, break or throw) must terminate the
+                // fetch iterator, otherwise imapflow leaves the FETCH command pending and the
+                // LOGOUT queued behind it in poll() never resolves, so the mutex is never
+                // released. for await calls the iterator's return() on every exit path.
+                for await (const msg of msgStream) {
+                    if (!this._retrieving) {
+                        return false;
+                    }
+                    const currentLastUid = folderState.lastUid ?? 0;
+                    if (Is.notEmpty(msg.uid) && msg.uid > currentLastUid) {
+                        if (Is.notEmpty(msg.source)) {
+                            const email = await MailHelper.parseEmail(msg.source.toString(), msg.flags ? [...msg.flags] : undefined);
+                            if (Is.notEmpty(email)) {
+                                await this._logging?.log({
+                                    level: "info",
+                                    source: ImapEmailConnector.CLASS_NAME,
+                                    ts: Date.now(),
+                                    message: "emailReceived",
+                                    data: { subject: email.subject }
+                                });
+                                folderState.lastUid = msg.uid;
+                                const shouldContinue = await retrievalCallback(this._instanceId, email, this._state);
+                                if (!shouldContinue) {
+                                    folderState.lastUid = currentLastUid;
+                                    return false;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            lock.release();
+        }
+        return true;
+    }
+}
+//# sourceMappingURL=imapEmailConnector.js.map

package/dist/es/imapEmailConnector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imapEmailConnector.js","sourceRoot":"","sources":["../../src/imapEmailConnector.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { ITaskSchedulerComponent } from \"@twin.org/background-task-models\";\nimport { BaseError, ComponentFactory, GeneralError, Guards, Is, Mutex } from \"@twin.org/core\";\nimport type { ILoggingComponent } from \"@twin.org/logging-models\";\nimport type {\n\tIEmailProtocolConnector,\n\tIEmailProtocolConnectorAuthCallback,\n\tIEmailProtocolConnectorRetrievalCallback\n} from \"@twin.org/mailbox-models\";\nimport { MailHelper } from \"@twin.org/mailbox-models\";\nimport { nameof } from \"@twin.org/nameof\";\nimport { ImapFlow } from \"imapflow\";\nimport type { IImapEmailConnectorConfig } from \"./models/IImapEmailConnectorConfig.js\";\nimport type { IImapEmailConnectorConstructorOptions } from \"./models/IImapEmailConnectorConstructorOptions.js\";\nimport type { IImapEmailConnectorFolderState } from \"./models/IImapEmailConnectorFolderState.js\";\nimport type { IImapEmailConnectorState } from \"./models/IImapEmailConnectorState.js\";\n\n/**\n * IMAP email protocol connector. Polls configured folders for new messages using imapflow.\n */\nexport class ImapEmailConnector implements IEmailProtocolConnector<IImapEmailConnectorState> {\n\t/**\n\t * The class name.\n\t */\n\tpublic static readonly CLASS_NAME: string = nameof<ImapEmailConnector>();\n\n\t/**\n\t * The protocol namespace identifier.\n\t */\n\tpublic static readonly NAMESPACE: string = \"imap\";\n\n\t/**\n\t * The logging component.\n\t * @internal\n\t */\n\tprivate readonly _logging?: ILoggingComponent;\n\n\t/**\n\t * The task scheduler component used for polling.\n\t * @internal\n\t */\n\tprivate readonly _taskScheduler: ITaskSchedulerComponent;\n\n\t/**\n\t * The resolved configuration for this connector instance.\n\t * @internal\n\t */\n\tprivate readonly _config: Required<\n\t\tPick<\n\t\t\tIImapEmailConnectorConfig,\n\t\t\t\"host\" | \"port\" | \"secure\" | \"username\" | \"password\" | \"folders\" | \"pollingIntervalMinutes\"\n\t\t>\n\t> &\n\t\tPick<IImapEmailConnectorConfig, \"mutexTimeoutMs\">;\n\n\t/**\n\t * The identifier of the currently active instance being polled.\n\t * @internal\n\t */\n\tprivate _instanceId?: string;\n\n\t/**\n\t * Set when retrieve has been called and cleared when retrieveStop is called.\n\t * @internal\n\t */\n\tprivate _retrieving: boolean;\n\n\t/**\n\t * The last successfully persisted connector state, updated after each successful callback.\n\t * @internal\n\t */\n\tprivate _state?: IImapEmailConnectorState;\n\n\t/**\n\t * Create a new instance of ImapEmailConnector.\n\t * @param options The options for the connector.\n\t */\n\tconstructor(options: IImapEmailConnectorConstructorOptions) {\n\t\tGuards.object(ImapEmailConnector.CLASS_NAME, nameof(options), options);\n\t\tGuards.object(ImapEmailConnector.CLASS_NAME, nameof(options.config), options.config);\n\t\tGuards.stringValue(\n\t\t\tImapEmailConnector.CLASS_NAME,\n\t\t\tnameof(options.config.host),\n\t\t\toptions.config.host\n\t\t);\n\t\tGuards.stringValue(\n\t\t\tImapEmailConnector.CLASS_NAME,\n\t\t\tnameof(options.config.username),\n\t\t\toptions.config.username\n\t\t);\n\t\tGuards.stringValue(\n\t\t\tImapEmailConnector.CLASS_NAME,\n\t\t\tnameof(options.config.password),\n\t\t\toptions.config.password\n\t\t);\n\n\t\tthis._logging = ComponentFactory.getIfExists<ILoggingComponent>(options.loggingComponentType);\n\n\t\tthis._taskScheduler = ComponentFactory.get<ITaskSchedulerComponent>(\n\t\t\toptions.taskSchedulerComponentType ?? \"task-scheduler\"\n\t\t);\n\n\t\tconst secure = options.config.secure ?? true;\n\t\tthis._config = {\n\t\t\thost: options.config.host,\n\t\t\tport: options.config.port ?? (secure ? 993 : 143),\n\t\t\tsecure,\n\t\t\tusername: options.config.username,\n\t\t\tpassword: options.config.password,\n\t\t\tfolders: options.config.folders ?? [\"INBOX\"],\n\t\t\tpollingIntervalMinutes: Math.max(1, options.config.pollingIntervalMinutes ?? 2),\n\t\t\tmutexTimeoutMs: options.config.mutexTimeoutMs\n\t\t};\n\t\tthis._retrieving = false;\n\t}\n\n\t/**\n\t * Get the class name.\n\t * @returns The class name.\n\t */\n\tpublic className(): string {\n\t\treturn ImapEmailConnector.CLASS_NAME;\n\t}\n\n\t/**\n\t * Start the internal polling loop for the given instance.\n\t * @param instanceId The identifier of the mailbox instance being polled.\n\t * @param state The current connector state for the instance.\n\t * @param authCallback Callback invoked when authentication fails during a poll cycle.\n\t * @param retrievalCallback Callback invoked with retrieved messages after each poll cycle.\n\t * @returns A promise that resolves when the polling loop has been started.\n\t */\n\tpublic async retrieve(\n\t\tinstanceId: string,\n\t\tstate: IImapEmailConnectorState,\n\t\tauthCallback: IEmailProtocolConnectorAuthCallback,\n\t\tretrievalCallback: IEmailProtocolConnectorRetrievalCallback\n\t): Promise<void> {\n\t\tawait this.retrieveStop();\n\n\t\tthis._retrieving = true;\n\t\tthis._instanceId = instanceId;\n\t\tthis._state = state;\n\n\t\tawait this._taskScheduler.addTask(\n\t\t\tinstanceId,\n\t\t\t[{ intervalMinutes: this._config.pollingIntervalMinutes }],\n\t\t\tasync () => {\n\t\t\t\tawait this.poll(authCallback, retrievalCallback);\n\t\t\t}\n\t\t);\n\t}\n\n\t/**\n\t * Stop the polling loop for this connector.\n\t * @returns A promise that resolves when the polling loop has been stopped.\n\t */\n\tpublic async retrieveStop(): Promise<void> {\n\t\tif (Is.stringValue(this._instanceId)) {\n\t\t\tthis._retrieving = false;\n\t\t\tawait this._taskScheduler.removeTask(this._instanceId);\n\t\t\tthis._instanceId = undefined;\n\t\t\tthis._state = undefined;\n\t\t}\n\t}\n\n\t/**\n\t * Poll each configured folder for new messages.\n\t * @param authCallback Callback invoked when authentication fails.\n\t * @param retrievalCallback Callback invoked with retrieved messages.\n\t * @internal\n\t */\n\tprivate async poll(\n\t\tauthCallback: IEmailProtocolConnectorAuthCallback,\n\t\tretrievalCallback: IEmailProtocolConnectorRetrievalCallback\n\t): Promise<void> {\n\t\tif (Is.empty(this._state) || !Is.stringValue(this._instanceId)) {\n\t\t\treturn;\n\t\t}\n\n\t\t// Capture the instance id and state for this poll cycle, retrieveStop can clear the\n\t\t// instance fields while a poll is in progress and the mutex must still be released\n\t\t// under the key it was locked with.\n\t\tconst instanceId = this._instanceId;\n\t\tconst state = this._state;\n\n\t\tawait Mutex.lock(instanceId, {\n\t\t\ttimeoutMs: this._config.mutexTimeoutMs,\n\t\t\tthrowOnTimeout: true\n\t\t});\n\n\t\tconst client = new ImapFlow({\n\t\t\thost: this._config.host,\n\t\t\tport: this._config.port,\n\t\t\tsecure: this._config.secure,\n\t\t\tauth: { user: this._config.username, pass: this._config.password },\n\t\t\tlogger: false\n\t\t});\n\n\t\ttry {\n\t\t\tawait client.connect();\n\n\t\t\tfor (const folder of this._config.folders) {\n\t\t\t\tconst continued = await this.pollFolder(client, folder, retrievalCallback);\n\t\t\t\tif (!continued) {\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t} catch (error) {\n\t\t\tconst pollError = new GeneralError(\n\t\t\t\tImapEmailConnector.CLASS_NAME,\n\t\t\t\t\"pollFailed\",\n\t\t\t\tundefined,\n\t\t\t\tBaseError.fromError(error)\n\t\t\t);\n\n\t\t\tconst rawError = Is.object<{ authenticationFailed?: unknown; response?: unknown }>(error)\n\t\t\t\t? error\n\t\t\t\t: undefined;\n\t\t\tconst isAuthFailure = rawError?.authenticationFailed === true;\n\t\t\tif (isAuthFailure) {\n\t\t\t\tawait authCallback(instanceId, state, true, undefined, pollError);\n\t\t\t} else {\n\t\t\t\tawait retrievalCallback(instanceId, undefined, state, pollError);\n\t\t\t}\n\t\t} finally {\n\t\t\ttry {\n\t\t\t\tawait client.logout();\n\t\t\t\tclient.close();\n\t\t\t} catch {\n\t\t\t\t// ignore, not much we can do if the connection is already closed\n\t\t\t\t// but don't want to prevent the mutex from being unlocked in the finally block below\n\t\t\t}\n\t\t\tMutex.unlock(instanceId);\n\t\t}\n\t}\n\n\t/**\n\t * Poll a single folder for messages with UIDs beyond the last seen UID.\n\t * Each parsed message is forwarded to the retrieval callback; returning false aborts processing.\n\t * @param client The connected ImapFlow client.\n\t * @param folder The folder path to poll.\n\t * @param retrievalCallback Callback invoked for each parsed email; return false to abort.\n\t * @returns True if all messages were processed, false if processing was aborted.\n\t * @internal\n\t */\n\tprivate async pollFolder(\n\t\tclient: ImapFlow,\n\t\tfolder: string,\n\t\tretrievalCallback: IEmailProtocolConnectorRetrievalCallback\n\t): Promise<boolean> {\n\t\tif (Is.empty(this._state) || !Is.stringValue(this._instanceId)) {\n\t\t\treturn true;\n\t\t}\n\n\t\tthis._state.folders ??= {};\n\t\tconst folderState: IImapEmailConnectorFolderState = this._state.folders[folder] ?? {};\n\t\tthis._state.folders[folder] = folderState;\n\n\t\tconst lock = await client.getMailboxLock(folder);\n\t\ttry {\n\t\t\tif (!client.mailbox) {\n\t\t\t\treturn true;\n\t\t\t}\n\n\t\t\tconst uidValidity = client.mailbox.uidValidity.toString();\n\n\t\t\tif (folderState.uidValidity !== uidValidity) {\n\t\t\t\tfolderState.uidValidity = uidValidity;\n\t\t\t\tfolderState.lastUid = 0;\n\t\t\t}\n\n\t\t\tconst lastUid = folderState.lastUid ?? 0;\n\t\t\tconst searchQuery = lastUid > 0 ? { uid: `${lastUid + 1}:*` } : { all: true };\n\t\t\tconst uids = await client.search(searchQuery, { uid: true });\n\n\t\t\tif (uids !== false && Is.arrayValue(uids)) {\n\t\t\t\tconst msgStream = client.fetch(\n\t\t\t\t\tuids,\n\t\t\t\t\t{ uid: true, source: true, flags: true },\n\t\t\t\t\t{ uid: true }\n\t\t\t\t);\n\t\t\t\t// Any early exit from this loop (return, break or throw) must terminate the\n\t\t\t\t// fetch iterator, otherwise imapflow leaves the FETCH command pending and the\n\t\t\t\t// LOGOUT queued behind it in poll() never resolves, so the mutex is never\n\t\t\t\t// released. for await calls the iterator's return() on every exit path.\n\t\t\t\tfor await (const msg of msgStream) {\n\t\t\t\t\tif (!this._retrieving) {\n\t\t\t\t\t\treturn false;\n\t\t\t\t\t}\n\t\t\t\t\tconst currentLastUid = folderState.lastUid ?? 0;\n\t\t\t\t\tif (Is.notEmpty(msg.uid) && msg.uid > currentLastUid) {\n\t\t\t\t\t\tif (Is.notEmpty(msg.source)) {\n\t\t\t\t\t\t\tconst email = await MailHelper.parseEmail(\n\t\t\t\t\t\t\t\tmsg.source.toString(),\n\t\t\t\t\t\t\t\tmsg.flags ? [...msg.flags] : undefined\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tif (Is.notEmpty(email)) {\n\t\t\t\t\t\t\t\tawait this._logging?.log({\n\t\t\t\t\t\t\t\t\tlevel: \"info\",\n\t\t\t\t\t\t\t\t\tsource: ImapEmailConnector.CLASS_NAME,\n\t\t\t\t\t\t\t\t\tts: Date.now(),\n\t\t\t\t\t\t\t\t\tmessage: \"emailReceived\",\n\t\t\t\t\t\t\t\t\tdata: { subject: email.subject }\n\t\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\t\tfolderState.lastUid = msg.uid;\n\t\t\t\t\t\t\t\tconst shouldContinue = await retrievalCallback(\n\t\t\t\t\t\t\t\t\tthis._instanceId,\n\t\t\t\t\t\t\t\t\temail,\n\t\t\t\t\t\t\t\t\tthis._state\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\tif (!shouldContinue) {\n\t\t\t\t\t\t\t\t\tfolderState.lastUid = currentLastUid;\n\t\t\t\t\t\t\t\t\treturn false;\n\t\t\t\t\t\t\t\t}\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t} finally {\n\t\t\tlock.release();\n\t\t}\n\t\treturn true;\n\t}\n}\n"]}

package/dist/es/index.js

@@ -0,0 +1,9 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export * from "./configSchema/imapEmailConnectorConfigSchema.js";
+export * from "./imapEmailConnector.js";
+export * from "./models/IImapEmailConnectorConfig.js";
+export * from "./models/IImapEmailConnectorConstructorOptions.js";
+export * from "./models/IImapEmailConnectorFolderState.js";
+export * from "./models/IImapEmailConnectorState.js";
+//# sourceMappingURL=index.js.map

package/dist/es/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,cAAc,kDAAkD,CAAC;AACjE,cAAc,yBAAyB,CAAC;AACxC,cAAc,uCAAuC,CAAC;AACtD,cAAc,mDAAmD,CAAC;AAClE,cAAc,4CAA4C,CAAC;AAC3D,cAAc,sCAAsC,CAAC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nexport * from \"./configSchema/imapEmailConnectorConfigSchema.js\";\nexport * from \"./imapEmailConnector.js\";\nexport * from \"./models/IImapEmailConnectorConfig.js\";\nexport * from \"./models/IImapEmailConnectorConstructorOptions.js\";\nexport * from \"./models/IImapEmailConnectorFolderState.js\";\nexport * from \"./models/IImapEmailConnectorState.js\";\n"]}

package/dist/es/models/IImapEmailConnectorConfig.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IImapEmailConnectorConfig.js.map

package/dist/es/models/IImapEmailConnectorConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IImapEmailConnectorConfig.js","sourceRoot":"","sources":["../../../src/models/IImapEmailConnectorConfig.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Configuration for the IMAP email connector.\n */\nexport interface IImapEmailConnectorConfig {\n\t/**\n\t * The hostname or IP address of the IMAP server.\n\t */\n\thost: string;\n\n\t/**\n\t * The port number to connect to.\n\t * @default 993\n\t */\n\tport?: number;\n\n\t/**\n\t * Whether to use a direct TLS connection.\n\t * Set to false to use a plain connection (STARTTLS may still be negotiated).\n\t * @default true\n\t */\n\tsecure?: boolean;\n\n\t/**\n\t * The username to authenticate with.\n\t */\n\tusername: string;\n\n\t/**\n\t * The password to authenticate with. Stored securely in the vault.\n\t */\n\tpassword: string;\n\n\t/**\n\t * The folder paths to poll for new messages.\n\t * Nested paths use the server's hierarchy delimiter, e.g. \"Work/Projects\".\n\t * @default [\"INBOX\"]\n\t */\n\tfolders?: string[];\n\n\t/**\n\t * How often to poll for new messages, in minutes.\n\t * @default 2\n\t */\n\tpollingIntervalMinutes?: number;\n\n\t/**\n\t * Maximum time in milliseconds to wait for the poll mutex before skipping the tick.\n\t * When not set, the mutex waits based on the system default.\n\t */\n\tmutexTimeoutMs?: number;\n}\n"]}

package/dist/es/models/IImapEmailConnectorConstructorOptions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IImapEmailConnectorConstructorOptions.js.map

package/dist/es/models/IImapEmailConnectorConstructorOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IImapEmailConnectorConstructorOptions.js","sourceRoot":"","sources":["../../../src/models/IImapEmailConnectorConstructorOptions.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IImapEmailConnectorConfig } from \"./IImapEmailConnectorConfig.js\";\n\n/**\n * Constructor options for the IMAP email connector.\n */\nexport interface IImapEmailConnectorConstructorOptions {\n\t/**\n\t * The configuration for the IMAP connector.\n\t */\n\tconfig: IImapEmailConnectorConfig;\n\n\t/**\n\t * The component type for the task scheduler used to manage polling intervals.\n\t * @default \"task-scheduler\"\n\t */\n\ttaskSchedulerComponentType?: string;\n\n\t/**\n\t * The component type for logging.\n\t */\n\tloggingComponentType?: string;\n}\n"]}

package/dist/es/models/IImapEmailConnectorFolderState.js

@@ -0,0 +1,4 @@
+// Copyright 2026 IOTA Stiftung.
+// SPDX-License-Identifier: Apache-2.0.
+export {};
+//# sourceMappingURL=IImapEmailConnectorFolderState.js.map

package/dist/es/models/IImapEmailConnectorFolderState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IImapEmailConnectorFolderState.js","sourceRoot":"","sources":["../../../src/models/IImapEmailConnectorFolderState.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\n\n/**\n * Per-folder polling state for the IMAP connector.\n */\nexport interface IImapEmailConnectorFolderState {\n\t/**\n\t * The UID validity value at the time of the last successful poll,\n\t * serialised as a string to survive JSON round-trips.\n\t * When this changes the connector resets lastUid to 0.\n\t */\n\tuidValidity?: string;\n\n\t/**\n\t * The highest UID successfully processed in the last poll cycle.\n\t * The next poll fetches UIDs strictly greater than this value.\n\t */\n\tlastUid?: number;\n}\n"]}

package/dist/es/models/IImapEmailConnectorState.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=IImapEmailConnectorState.js.map

package/dist/es/models/IImapEmailConnectorState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IImapEmailConnectorState.js","sourceRoot":"","sources":["../../../src/models/IImapEmailConnectorState.ts"],"names":[],"mappings":"","sourcesContent":["// Copyright 2026 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport type { IImapEmailConnectorFolderState } from \"./IImapEmailConnectorFolderState.js\";\n\n/**\n * Top-level polling state for the IMAP connector, keyed by folder path.\n */\nexport interface IImapEmailConnectorState {\n\t/**\n\t * Per-folder state, keyed by the folder path as configured.\n\t */\n\tfolders?: { [folderPath: string]: IImapEmailConnectorFolderState };\n}\n"]}

package/dist/types/configSchema/imapEmailConnectorConfigSchema.d.ts

@@ -0,0 +1,5 @@
+import type { IMailboxConfigField } from "@twin.org/mailbox-models";
+/**
+ * The configuration field schema for IMAP connectors.
+ */
+export declare const ImapEmailConnectorConfigSchema: IMailboxConfigField[];

package/dist/types/imapEmailConnector.d.ts

@@ -0,0 +1,40 @@
+import type { IEmailProtocolConnector, IEmailProtocolConnectorAuthCallback, IEmailProtocolConnectorRetrievalCallback } from "@twin.org/mailbox-models";
+import type { IImapEmailConnectorConstructorOptions } from "./models/IImapEmailConnectorConstructorOptions.js";
+import type { IImapEmailConnectorState } from "./models/IImapEmailConnectorState.js";
+/**
+ * IMAP email protocol connector. Polls configured folders for new messages using imapflow.
+ */
+export declare class ImapEmailConnector implements IEmailProtocolConnector<IImapEmailConnectorState> {
+    /**
+     * The class name.
+     */
+    static readonly CLASS_NAME: string;
+    /**
+     * The protocol namespace identifier.
+     */
+    static readonly NAMESPACE: string;
+    /**
+     * Create a new instance of ImapEmailConnector.
+     * @param options The options for the connector.
+     */
+    constructor(options: IImapEmailConnectorConstructorOptions);
+    /**
+     * Get the class name.
+     * @returns The class name.
+     */
+    className(): string;
+    /**
+     * Start the internal polling loop for the given instance.
+     * @param instanceId The identifier of the mailbox instance being polled.
+     * @param state The current connector state for the instance.
+     * @param authCallback Callback invoked when authentication fails during a poll cycle.
+     * @param retrievalCallback Callback invoked with retrieved messages after each poll cycle.
+     * @returns A promise that resolves when the polling loop has been started.
+     */
+    retrieve(instanceId: string, state: IImapEmailConnectorState, authCallback: IEmailProtocolConnectorAuthCallback, retrievalCallback: IEmailProtocolConnectorRetrievalCallback): Promise<void>;
+    /**
+     * Stop the polling loop for this connector.
+     * @returns A promise that resolves when the polling loop has been stopped.
+     */
+    retrieveStop(): Promise<void>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./configSchema/imapEmailConnectorConfigSchema.js";
+export * from "./imapEmailConnector.js";
+export * from "./models/IImapEmailConnectorConfig.js";
+export * from "./models/IImapEmailConnectorConstructorOptions.js";
+export * from "./models/IImapEmailConnectorFolderState.js";
+export * from "./models/IImapEmailConnectorState.js";

package/dist/types/models/IImapEmailConnectorConfig.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Configuration for the IMAP email connector.
+ */
+export interface IImapEmailConnectorConfig {
+    /**
+     * The hostname or IP address of the IMAP server.
+     */
+    host: string;
+    /**
+     * The port number to connect to.
+     * @default 993
+     */
+    port?: number;
+    /**
+     * Whether to use a direct TLS connection.
+     * Set to false to use a plain connection (STARTTLS may still be negotiated).
+     * @default true
+     */
+    secure?: boolean;
+    /**
+     * The username to authenticate with.
+     */
+    username: string;
+    /**
+     * The password to authenticate with. Stored securely in the vault.
+     */
+    password: string;
+    /**
+     * The folder paths to poll for new messages.
+     * Nested paths use the server's hierarchy delimiter, e.g. "Work/Projects".
+     * @default ["INBOX"]
+     */
+    folders?: string[];
+    /**
+     * How often to poll for new messages, in minutes.
+     * @default 2
+     */
+    pollingIntervalMinutes?: number;
+    /**
+     * Maximum time in milliseconds to wait for the poll mutex before skipping the tick.
+     * When not set, the mutex waits based on the system default.
+     */
+    mutexTimeoutMs?: number;
+}

package/dist/types/models/IImapEmailConnectorConstructorOptions.d.ts

@@ -0,0 +1,19 @@
+import type { IImapEmailConnectorConfig } from "./IImapEmailConnectorConfig.js";
+/**
+ * Constructor options for the IMAP email connector.
+ */
+export interface IImapEmailConnectorConstructorOptions {
+    /**
+     * The configuration for the IMAP connector.
+     */
+    config: IImapEmailConnectorConfig;
+    /**
+     * The component type for the task scheduler used to manage polling intervals.
+     * @default "task-scheduler"
+     */
+    taskSchedulerComponentType?: string;
+    /**
+     * The component type for logging.
+     */
+    loggingComponentType?: string;
+}

package/dist/types/models/IImapEmailConnectorFolderState.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Per-folder polling state for the IMAP connector.
+ */
+export interface IImapEmailConnectorFolderState {
+    /**
+     * The UID validity value at the time of the last successful poll,
+     * serialised as a string to survive JSON round-trips.
+     * When this changes the connector resets lastUid to 0.
+     */
+    uidValidity?: string;
+    /**
+     * The highest UID successfully processed in the last poll cycle.
+     * The next poll fetches UIDs strictly greater than this value.
+     */
+    lastUid?: number;
+}

package/dist/types/models/IImapEmailConnectorState.d.ts

@@ -0,0 +1,12 @@
+import type { IImapEmailConnectorFolderState } from "./IImapEmailConnectorFolderState.js";
+/**
+ * Top-level polling state for the IMAP connector, keyed by folder path.
+ */
+export interface IImapEmailConnectorState {
+    /**
+     * Per-folder state, keyed by the folder path as configured.
+     */
+    folders?: {
+        [folderPath: string]: IImapEmailConnectorFolderState;
+    };
+}

package/docs/changelog.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [0.9.3-next.1](https://github.com/iotaledger/twin-messaging/compare/mailbox-connector-imap-v0.9.3-next.0...mailbox-connector-imap-v0.9.3-next.1) (2026-09-04)
+
+
+### Features
+
+* add email ingestion ([#56](https://github.com/iotaledger/twin-messaging/issues/56)) ([390806d](https://github.com/iotaledger/twin-messaging/commit/390806d2690843f44de0b6a8a5e5de616b16c278))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/mailbox-models bumped from 0.9.3-next.0 to 0.9.3-next.1
+
+## Changelog

package/docs/examples.md

@@ -0,0 +1,98 @@
+# Mailbox Connector IMAP Examples
+
+A polling connector for email ingestion via the IMAP protocol, with per-folder UID tracking.
+
+## ImapEmailConnector
+
+```typescript
+import {
+  ImapEmailConnector,
+  ImapEmailConnectorConfigSchema
+} from '@twin.org/mailbox-connector-imap';
+import {
+  EmailProtocolConnectorFactory,
+  EmailProtocolConnectorSchemaFactory
+} from '@twin.org/mailbox-models';
+
+// Register the connector and its config schema with the shared factories
+EmailProtocolConnectorFactory.register(
+  ImapEmailConnector.NAMESPACE,
+  () =>
+    new ImapEmailConnector({
+      config: {
+        host: 'imap.example.com',
+        username: 'user@example.com',
+        password: 'secret'
+      }
+    })
+);
+
+EmailProtocolConnectorSchemaFactory.register(
+  ImapEmailConnector.NAMESPACE,
+  () => ImapEmailConnectorConfigSchema
+);
+
+const schema = EmailProtocolConnectorSchemaFactory.get(ImapEmailConnector.NAMESPACE);
+console.log(schema.find(f => f.isSecure)?.propertyKey); // "password"
+```
+
+```typescript
+import { ImapEmailConnector } from '@twin.org/mailbox-connector-imap';
+import type { IImapEmailConnectorState } from '@twin.org/mailbox-connector-imap';
+import type {
+  IEmailProtocolConnectorAuthCallback,
+  IEmailProtocolConnectorRetrievalCallback
+} from '@twin.org/mailbox-models';
+
+const connector = new ImapEmailConnector({
+  config: {
+    host: 'imap.example.com',
+    port: 993,
+    secure: true,
+    username: 'user@example.com',
+    password: 'secret',
+    folders: ['INBOX', 'Work/Projects'],
+    batchSize: 5,
+    pollingIntervalMinutes: 2
+  }
+});
+
+// State persisted between poll cycles; tracks the last UID seen per folder
+const state: IImapEmailConnectorState = {};
+
+const authCallback: IEmailProtocolConnectorAuthCallback = async (
+  mailboxId,
+  requiresAuth,
+  updatedState,
+  error,
+  authState
+) => {
+  if (requiresAuth) {
+    console.log(`Mailbox ${mailboxId} needs re-authentication`);
+  }
+};
+
+const retrievalCallback: IEmailProtocolConnectorRetrievalCallback = async (
+  mailboxId,
+  messages,
+  updatedState,
+  error
+) => {
+  console.log(messages.length); // number of messages in this batch
+  for (const message of messages) {
+    console.log(message.subject); // e.g. "Project update"
+    console.log(message.flags); // e.g. ["\\Seen"]
+    console.log(message.htmlContent !== undefined); // true when HTML part is present
+  }
+  if (error !== undefined) {
+    console.log(error.message); // description of the retrieval problem
+  }
+  // Persist updatedState to resume from the last seen UID on the next poll cycle
+};
+
+// Start the polling loop; the scheduler fires it every pollingIntervalMinutes
+await connector.retrieve('mailbox-abc', state, authCallback, retrievalCallback);
+
+// Stop polling when the mailbox is removed or disabled
+await connector.retrieveStop();
+```

package/docs/reference/classes/ImapEmailConnector.md

@@ -0,0 +1,123 @@
+# Class: ImapEmailConnector
+
+IMAP email protocol connector. Polls configured folders for new messages using imapflow.
+
+## Implements
+
+- `IEmailProtocolConnector`\<[`IImapEmailConnectorState`](../interfaces/IImapEmailConnectorState.md)\>
+
+## Constructors
+
+### Constructor
+
+> **new ImapEmailConnector**(`options`): `ImapEmailConnector`
+
+Create a new instance of ImapEmailConnector.
+
+#### Parameters
+
+##### options
+
+[`IImapEmailConnectorConstructorOptions`](../interfaces/IImapEmailConnectorConstructorOptions.md)
+
+The options for the connector.
+
+#### Returns
+
+`ImapEmailConnector`
+
+## Properties
+
+### CLASS\_NAME {#class_name}
+
+> `readonly` `static` **CLASS\_NAME**: `string`
+
+The class name.
+
+***
+
+### NAMESPACE {#namespace}
+
+> `readonly` `static` **NAMESPACE**: `string` = `"imap"`
+
+The protocol namespace identifier.
+
+## Methods
+
+### className() {#classname}
+
+> **className**(): `string`
+
+Get the class name.
+
+#### Returns
+
+`string`
+
+The class name.
+
+#### Implementation of
+
+`IEmailProtocolConnector.className`
+
+***
+
+### retrieve() {#retrieve}
+
+> **retrieve**(`instanceId`, `state`, `authCallback`, `retrievalCallback`): `Promise`\<`void`\>
+
+Start the internal polling loop for the given instance.
+
+#### Parameters
+
+##### instanceId
+
+`string`
+
+The identifier of the mailbox instance being polled.
+
+##### state
+
+[`IImapEmailConnectorState`](../interfaces/IImapEmailConnectorState.md)
+
+The current connector state for the instance.
+
+##### authCallback
+
+`IEmailProtocolConnectorAuthCallback`
+
+Callback invoked when authentication fails during a poll cycle.
+
+##### retrievalCallback
+
+`IEmailProtocolConnectorRetrievalCallback`
+
+Callback invoked with retrieved messages after each poll cycle.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the polling loop has been started.
+
+#### Implementation of
+
+`IEmailProtocolConnector.retrieve`
+
+***
+
+### retrieveStop() {#retrievestop}
+
+> **retrieveStop**(): `Promise`\<`void`\>
+
+Stop the polling loop for this connector.
+
+#### Returns
+
+`Promise`\<`void`\>
+
+A promise that resolves when the polling loop has been stopped.
+
+#### Implementation of
+
+`IEmailProtocolConnector.retrieveStop`

package/docs/reference/index.md

@@ -0,0 +1,16 @@
+# @twin.org/mailbox-connector-imap
+
+## Classes
+
+- [ImapEmailConnector](classes/ImapEmailConnector.md)
+
+## Interfaces
+
+- [IImapEmailConnectorConfig](interfaces/IImapEmailConnectorConfig.md)
+- [IImapEmailConnectorConstructorOptions](interfaces/IImapEmailConnectorConstructorOptions.md)
+- [IImapEmailConnectorFolderState](interfaces/IImapEmailConnectorFolderState.md)
+- [IImapEmailConnectorState](interfaces/IImapEmailConnectorState.md)
+
+## Variables
+
+- [ImapEmailConnectorConfigSchema](variables/ImapEmailConnectorConfigSchema.md)

package/docs/reference/interfaces/IImapEmailConnectorConfig.md

@@ -0,0 +1,94 @@
+# Interface: IImapEmailConnectorConfig
+
+Configuration for the IMAP email connector.
+
+## Properties
+
+### host {#host}
+
+> **host**: `string`
+
+The hostname or IP address of the IMAP server.
+
+***
+
+### port? {#port}
+
+> `optional` **port?**: `number`
+
+The port number to connect to.
+
+#### Default
+
+```ts
+993
+```
+
+***
+
+### secure? {#secure}
+
+> `optional` **secure?**: `boolean`
+
+Whether to use a direct TLS connection.
+Set to false to use a plain connection (STARTTLS may still be negotiated).
+
+#### Default
+
+```ts
+true
+```
+
+***
+
+### username {#username}
+
+> **username**: `string`
+
+The username to authenticate with.
+
+***
+
+### password {#password}
+
+> **password**: `string`
+
+The password to authenticate with. Stored securely in the vault.
+
+***
+
+### folders? {#folders}
+
+> `optional` **folders?**: `string`[]
+
+The folder paths to poll for new messages.
+Nested paths use the server's hierarchy delimiter, e.g. "Work/Projects".
+
+#### Default
+
+```ts
+["INBOX"]
+```
+
+***
+
+### pollingIntervalMinutes? {#pollingintervalminutes}
+
+> `optional` **pollingIntervalMinutes?**: `number`
+
+How often to poll for new messages, in minutes.
+
+#### Default
+
+```ts
+2
+```
+
+***
+
+### mutexTimeoutMs? {#mutextimeoutms}
+
+> `optional` **mutexTimeoutMs?**: `number`
+
+Maximum time in milliseconds to wait for the poll mutex before skipping the tick.
+When not set, the mutex waits based on the system default.

package/docs/reference/interfaces/IImapEmailConnectorConstructorOptions.md

@@ -0,0 +1,33 @@
+# Interface: IImapEmailConnectorConstructorOptions
+
+Constructor options for the IMAP email connector.
+
+## Properties
+
+### config {#config}
+
+> **config**: [`IImapEmailConnectorConfig`](IImapEmailConnectorConfig.md)
+
+The configuration for the IMAP connector.
+
+***
+
+### taskSchedulerComponentType? {#taskschedulercomponenttype}
+
+> `optional` **taskSchedulerComponentType?**: `string`
+
+The component type for the task scheduler used to manage polling intervals.
+
+#### Default
+
+```ts
+"task-scheduler"
+```
+
+***
+
+### loggingComponentType? {#loggingcomponenttype}
+
+> `optional` **loggingComponentType?**: `string`
+
+The component type for logging.

package/docs/reference/interfaces/IImapEmailConnectorFolderState.md

@@ -0,0 +1,22 @@
+# Interface: IImapEmailConnectorFolderState
+
+Per-folder polling state for the IMAP connector.
+
+## Properties
+
+### uidValidity? {#uidvalidity}
+
+> `optional` **uidValidity?**: `string`
+
+The UID validity value at the time of the last successful poll,
+serialised as a string to survive JSON round-trips.
+When this changes the connector resets lastUid to 0.
+
+***
+
+### lastUid? {#lastuid}
+
+> `optional` **lastUid?**: `number`
+
+The highest UID successfully processed in the last poll cycle.
+The next poll fetches UIDs strictly greater than this value.

package/docs/reference/interfaces/IImapEmailConnectorState.md

@@ -0,0 +1,15 @@
+# Interface: IImapEmailConnectorState
+
+Top-level polling state for the IMAP connector, keyed by folder path.
+
+## Properties
+
+### folders? {#folders}
+
+> `optional` **folders?**: `object`
+
+Per-folder state, keyed by the folder path as configured.
+
+#### Index Signature
+
+\[`folderPath`: `string`\]: [`IImapEmailConnectorFolderState`](IImapEmailConnectorFolderState.md)

package/docs/reference/variables/ImapEmailConnectorConfigSchema.md

@@ -0,0 +1,5 @@
+# Variable: ImapEmailConnectorConfigSchema
+
+> `const` **ImapEmailConnectorConfigSchema**: `IMailboxConfigField`[]
+
+The configuration field schema for IMAP connectors.

package/locales/en.json

@@ -0,0 +1,21 @@
+{
+	"error": {
+		"imapEmailConnector": {
+			"pollFailed": "Poll failed"
+		}
+	},
+	"info": {
+		"imapEmailConnector": {
+			"emailReceived": "Email received \"{subject}\""
+		}
+	},
+	"imapEmailConnectorConfigSchema": {
+		"host": "Host",
+		"port": "Port",
+		"secure": "Secure",
+		"username": "Username",
+		"password": "Password",
+		"folders": "Folders",
+		"pollingIntervalMinutes": "Polling Interval (Minutes)"
+	}
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+	"name": "@twin.org/mailbox-connector-imap",
+	"version": "0.9.3-next.1",
+	"description": "IMAP connector for email mailbox ingestion.",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/iotaledger/twin-messaging.git",
+		"directory": "packages/mailbox-connector-imap"
+	},
+	"author": "martyn.janes@iota.org",
+	"license": "Apache-2.0",
+	"type": "module",
+	"engines": {
+		"node": ">=24.0.0"
+	},
+	"dependencies": {
+		"@twin.org/background-task-models": "next",
+		"@twin.org/core": "next",
+		"@twin.org/entity": "next",
+		"@twin.org/logging-models": "next",
+		"@twin.org/mailbox-models": "0.9.3-next.1",
+		"@twin.org/nameof": "next",
+		"imapflow": "1.7.7"
+	},
+	"main": "./dist/es/index.js",
+	"types": "./dist/types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/types/index.d.ts",
+			"import": "./dist/es/index.js",
+			"default": "./dist/es/index.js"
+		}
+	},
+	"files": [
+		"dist/es",
+		"dist/types",
+		"locales",
+		"docs"
+	],
+	"keywords": [
+		"twin",
+		"trade",
+		"iota",
+		"framework",
+		"blockchain",
+		"messaging",
+		"mailbox",
+		"email",
+		"imap",
+		"connector"
+	],
+	"bugs": {
+		"url": "git+https://github.com/iotaledger/twin-messaging/issues"
+	},
+	"homepage": "https://twindev.org"
+}