{"id":21430164,"url":"https://github.com/cuba-platform/imap-addon","last_synced_at":"2025-07-14T11:31:16.132Z","repository":{"id":47957999,"uuid":"126821829","full_name":"cuba-platform/imap-addon","owner":"cuba-platform","description":"IMAP Integration CUBA component provides a readily available instrument that enables adding the capability to integrate email messaging into any application developed using CUBA Platform.","archived":false,"fork":false,"pushed_at":"2025-01-28T12:49:32.000Z","size":1606,"stargazers_count":6,"open_issues_count":6,"forks_count":2,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-08T07:24:36.993Z","etag":null,"topics":["apache2","cuba-component","cuba-platform","imap"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cuba-platform.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-26T11:57:47.000Z","updated_at":"2025-01-14T11:39:46.000Z","dependencies_parsed_at":"2025-01-14T12:44:02.121Z","dependency_job_id":"76ac2a4d-8a2d-4af5-8f40-8d7bfadf05c4","html_url":"https://github.com/cuba-platform/imap-addon","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/cuba-platform/imap-addon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fimap-addon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fimap-addon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fimap-addon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fimap-addon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cuba-platform","download_url":"https://codeload.github.com/cuba-platform/imap-addon/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cuba-platform%2Fimap-addon/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265285275,"owners_count":23740493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache2","cuba-component","cuba-platform","imap"],"created_at":"2024-11-22T22:21:08.200Z","updated_at":"2025-07-14T11:31:15.784Z","avatar_url":"https://github.com/cuba-platform.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IMAP\n\n\u003cp\u003e\n    \u003ca href=\"http://www.apache.org/licenses/LICENSE-2.0\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg?style=flat\" alt=\"license\" title=\"\"\u003e\u003c/a\u003e\n    \u003ca href=\"https://travis-ci.org/cuba-platform/imap-addon\"\u003e\u003cimg src=\"https://travis-ci.org/cuba-platform/imap-addon.svg?branch=master\" alt=\"Build Status\" title=\"\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n- [Overview](#overview)\n- [Installation](#installation)\n  - [From the Marketplace](#from-the-marketplace)\n  - [By Coordinates](#by-coordinates)\n- [Add-on Configuration](#add-on-configuration)\n- [Usage](#usage)\n  - [Predefined Roles](#predefined-roles)\n  - [Component Functionalities](#component-functionalities)\n    - [IMAP Configuration](#imap-configuration)\n    - [IMAP Message Browser](#imap-message-browser)\n  - [Registering EventListeners to Interact with IMAP Events](#registering-eventlisteners-to-interact-with-imap-events)\n  - [Creating Handlers for IMAP Events](#creating-handlers-for-imap-events)\n  - [Using API](#using-api)\n  - [Registering Custom IMAP Implementation Class](#registering-custom-imap-implementation-class)\n\n# Overview\n\nThe IMAP-addon provides a readily available instrument for integrating email messaging into any CUBA-based application\nvia the IMAP protocol. The main model of the component is designed to interact with incoming emails via Spring application events.\n\nThe component includes the following set of functionalities:\n* Integration between any IMAP servers and CUBA applications.\n* Basic API methods to work with the main email server functionalities:\n    * Connecting to servers;\n    * Retrieving and viewing emails;\n    * Searching for emails;\n    * Operating custom flags.\n* Predefined events for implementing custom business logic and processing various updates.\n* User interface for configuring IMAP connection settings and events.\n\nSee [sample application](https://github.com/cuba-platform/imap-addon-demo) using this component.\nSee [webinar](https://www.youtube.com/watch?v=u6U0Y4zNxMc) on the CUBA Platform channel.\n\n# Installation\n\nThe add-on can be added to your project in one of the ways described below. Installation from the Marketplace is the simplest way. The last version of the add-on compatible with the used version of the platform will be installed.\nAlso, you can install the add-on by coordinates choosing the required version of the add-on from the table.\n\nIn case you want to install the add-on by manual editing or by building from sources see the complete add-ons installation guide in [CUBA Platform documentation](https://doc.cuba-platform.com/manual-latest/manual.html#app_components_usage).\n\n## From the Marketplace\n\n1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the [CUBA Platform site](https://www.cuba-platform.com/download/previous-studio/).\n2. Go to *CUBA -\u003e Marketplace* in the main menu.\n\n ![marketplace](img/marketplace.png)\n\n3. Find the *IMAP* add-on there.\n\n ![addons](img/addons.png)\n\n4. Click *Install* and apply the changes.\nThe add-on corresponding to the used platform version will be installed.\n\n## By coordinates\n\n1. Open your application in CUBA Studio. Check the latest version of CUBA Studio on the [CUBA Platform site](https://www.cuba-platform.com/download/previous-studio/).\n2. Go to *CUBA -\u003e Marketplace* in the main menu.\n3. Click the icon in the upper-right corner.\n\n ![by-coordinates](img/by-coordinates.png)\n\n4. Paste the add-on coordinates in the corresponding field as follows:\n\n `com.haulmont.addon.imap:imap-global:\u003cadd-on version\u003e`\n\n where `\u003cadd-on version\u003e` is compatible with the used version of the CUBA platform.\n\n| Platform Version | Add-on Version |\n|------------------|----------------|\n| 7.2.x            | 1.5.1          |\n| 7.1.x            | 1.4.0          |\n| 7.0.x            | 1.3.1          |\n| 6.10.x           | 1.2.0          |\n| 6.9.x            | 1.1.1          |\n| 6.8.x            | 1.0.1          |\n\n5. Click *Install* and apply the changes. The add-on will be installed to your project.\n\n# Add-on Configuration\n\nBefore using the add-on do the following:\n\n1. Open `app.properties` file of your application and configure the following application properties:\n\n```xml\n#IMAP configuration\nimap.encryption.key = HBXv3Q70IlmBMiW4EMyPHw==\nimap.encryption.iv = DYOKud/GWV5boeGvmR/ttg==\n\n#Enable scheduling\ncuba.schedulingActive=true\n```\n\n2. Run the application and go to  *Administration -\u003e Scheduled tasks* screen. Configure `imap_ImapScheduler -\u003e syncImap` scheduled task.\n\n# Usage\n\n## Predefined Roles \u003ca name=\"predefined-roles\"\u003e\u003c/a\u003e\n\n**IMAP Admin role** - allows user to configure IMAP events.\n\n## Component Functionalities\n\n### IMAP Configuration \u003ca name=\"imap-configuration\"\u003e\u003c/a\u003e\n\n*IMAP Configuration Browser* is designed to add and manage mailboxes from which emails are retrieved. The browser is\navailable from *Menu: Administration → IMAP → IMAP Configuration*.\n\n![IMAP Configuration Menu Item](img/imap_conf_item.png)\n\nCreating a new configuration is available by clicking the *Create* button.\n\n![Creating IMAP Configuration](img/creating-IMAP-conf.png)\n\n#### IMAP Configuration Editor \u003ca name=\"imap-configuration-editor\"\u003e\u003c/a\u003e\n\n*IMAP Configuration Editor* comprises two main sections to fill in: *Basic* and *Advanced*.\n\n![IMAP Configuration Editor](img/IMAP-conf-editor.png)\n\n**Basic**\n\nThe *Basic* section enables to configure the main attributes for connecting to an email server via IMAP. The description of\nall fields is provided below.\n\n* *Name*: specify a name for connection.\n* *Host*: specify a host name or IP address of an email server.\n* *Port*: provide a port number to connect to an email server. The default value is *143*.\n* *Secure Connection*: select an option for secure connection if required. Available values: *STARTTLS*, *SSL/TLS*.\n* *Root Certificate*: upload a client certificate if required.\n* *Username*: provide a username to connect to an email server.\n* *Password*: provide a user password to connect to an email server.\n\nThe *Basic* section comprises the *Connect* button. After providing all required information, use the button to upload\na list of folders from the email server to work with.\n\n**Advanced**\n\nThe *Advanced* section provides a set of additional options for connecting to an email server.\n\n* *Custom Flag*: specify a custom flag.\n* *Use trash folder to remove emails*: if checked, then it is possible to specify a trash folder of a current mailbox\n(the *Trash Folder* field becomes available). The setting works as follows: if an email is moved to the specified folder on\nthe email server, `EmailDeletedImapEvent` occurs (for more details, see [Event Types](#event-types)).\n* *Use custom event generator class*: if checked, it is possible to specify a custom class that defines additional logic\nfor connecting to an IMAP server, handling events, etc. If the current setting is enabled, the *Event Generator Class*\nlookup field becomes available. To learn how to register a custom event generator class, please refer to\n[Registering Custom IMAP Implementation Class](#registering-custom-imap-implementation-class).\n* *Use proxy*: if checked, proxy settings become available (see the description below).\n\n **Proxy Configuration**\n\n* *Proxy Host*: provide a host name or IP address of a proxy server.\n* *Proxy Port*: provide a port to connect to a proxy server.\n* *Use web proxy*: if checked, web proxy is used.\n\n**Table of Folders**\n\nOnce connection to the provided email server is successfully established, the table of folders becomes available.\n\n![Table of Folders](img/folders.png)\n\nThe table shows a list of folders from the email server you are connected to. In order to enable/disable some folders,\nuse the checkboxes in the second column. If some folder is disabled, then messages from it are not retrieved.\n\nFor each folder you can select a set of IMAP events by using the *Events* table and register custom logic for them\n(for more details, please refer to [Configuration](#configuration)).\n\n### IMAP Message Browser\n\nAll emails from connected mailboxes are displayed in *IMAP Message Browser* (available from *Menu: Administration → IMAP → IMAP Message Browser*).\n\n![IMAP Message Browser](img/Imap-message-browser.png)\n\nSelecting an email and clicking *View* opens it for reading. Email Screen contains all general details of an email:\ndate, author, subject, etc., and two tabs: *Body* and *Attachments*.\n\nOn the *Body* tab, the whole text of an email is displayed.\n\nThe *Attachments* tab comprises the table of attachments and the button to download required elements.\n\n![Attachments](img/email-attachments.png)\n\n## Registering EventListeners to Interact with IMAP Events\n\nIn order to make your application react to IMAP events, you can register the `@Component` methods as Event listeners by using\nthe `@EventListener` annotation. The example of how to set up an event listener is provided below.\n\n```java\nimport org.springframework.context.event.EventListener;\n\n@Service(EmailReceiveService.NAME)\npublic class EmailReceiveServiceBean implements EmailReceiveService {\n\n    @EventListener\n    @Override\n    public void receiveEmail(NewEmailImapEvent event) {\n      // handles IMAP event\n    }\n}\n```\n\nAnother option is to create `@Component` with a method having the required event type as the only parameter.\n\n```java\npublic class EmailReceiver {\n    String NAME = \"ceuia_EmailReceiver\";\n\n    public void receiveEmail(NewEmailImapEvent event) {\n        // handle IMAP event\n    }\n}\n```\n\nOnce it is done, the selected method (in the example, it is `receiveEmail`) should be registered on a particular folder\nfor a given IMAP connection. This should be done at runtime using the IMAP configuration UI (see [Creating Handlers for\nIMAP Events](#imap-handlers)).\nAfter that, the method will be invoked every time, when the configured event occurs.\n\n## Creating Handlers for IMAP Events\n\nAfter registering EventListeners, it is required to create handlers for IMAP events related to a particular folder and\nmailbox (for more information see [IMAP Connection](#imap-configuration)). The table of folders comprises several columns,\neach representing a certain event type (e.g. New, Seen, Replied, etc.). Clicking gear icons opens *IMAP Folder Event Editor*.\n\n![IMAP Folder Event Editor](img/imap-folder-event-editor.png)\n\nThere you can specify required beans and methods for them.\n\n### Event types \u003ca name=\"event-types\"\u003e\u003c/a\u003e\n\nAll events contain the `ImapMessage` object that can be used to determine where an event occurs (mailbox, folder, message).\n\nThe application component supports the following kinds of IMAP events:\n\n* `NewEmailImapEvent` is triggered for a folder having an event of the `ImapEventType.NEW_EMAIL` type enabled,\nwhen a new message appears in the folder on the IMAP server.\n* `EmailSeenImapEvent` is triggered for a folder having an event of the `ImapEventType.EMAIL_SEEN` type enabled,\nwhen a message is marked with the `javax.mail.Flags.Flag.SEEN` IMAP flag.\n* `EmailAnsweredImapEvent` is triggered for a folder having an event of the `ImapEventType.NEW_ANSWER` type enabled,\nwhen a message is replied (usually it happens when a message is marked with the `javax.mail.Flags.Flag.ANSWERED` IMAP flag).\n* `EmailFlagChangedImapEvent` is triggered for a folder having an event of the `ImapEventType.FLAGS_UPDATED` type enabled,\nwhen a standard or custom IMAP flag is changed for a message.\nThe event contains a `Map` of all changed flags and their actual state (set or unset).\n* `EmailDeletedImapEvent` is triggered for a folder having an event of the `ImapEventType.EMAIL_DELETED` type enabled,\nwhen a message is completely deleted from a folder on the IMAP server side, it is **not** related to the IMAP flag `javax.mail.Flags.Flag.DELETED`.\nSuch events are also triggered when a message is moved to a trash folder (if it is configured for a mailbox) on the server.\n* `EmailMovedImapEvent` is triggered for a folder having an event of the `ImapEventType.EMAIL_MOVED` type enabled,\nwhen a message is moved to another folder on the IMAP server.\n**Note**: the standard implementation tracks only folders which are selected in the `ImapMailBox` configuration,\nbut does not count a trash folder, if one is configured.\n* `NewThreadImapEvent` is not implemented yet.\n\n## Using API\n\nThe component provides the following API to interact with the IMAP server:\n\n* `ImapAPI` methods:\n    * `Collection\u003cImapFolderDto\u003e fetchFolders(ImapMailBox)` — retrieves all folders preserving the tree structure.\n    * `Collection\u003cImapFolderDto\u003e fetchFolders(ImapMailBox, String...)` — retrieves folders with the specified names.\n    The result is not structured as a tree.\n    * `List\u003cImapFolderDto\u003e fetchMessage(ImapMessage)` — fetches a single message using a reference.\n    * `void moveMessage(ImapMessage, String)` — moves a message to a different folder on the IMAP server side.\n    * `void deleteMessage(ImapMessage)` — deletes a message from a folder.\n    * `void setFlag(ImapMessage, ImapFlag, boolean)` — sets or unsets a specified flag for a message.\n* `ImapAttachmentsAPI` methods:\n    * `Collection\u003cImapMessageAttachment\u003e fetchAttachments(ImapMessage)` — retrieves attachments included in a message.\n    The result contains only meta data, no content.\n    * `InputStream openStream(ImapMessageAttachment)` and `byte[] loadFile(ImapMessageAttachment` — retrieve the content\n    of a message attachment.\n\n## Registering Custom IMAP Implementation Class \u003ca name=\"registering-custom-imap-implementation-class\"\u003e\u003c/a\u003e\n\nIn order to configure custom logic for a specific mailbox (e.g for applying IMAP extensions and custom communication\nmechanisms), it is required to register a custom IMAP implementation class in the source code of your application.\nThe example of how to register such class is given below.\n\n```java\n@Component(\"demo_SimpleSingleFolderNewMessagesEventsGenerator\")\npublic class SimpleSingleFolderNewMessagesEventsGenerator implements ImapEventsGenerator {\n...\n}\n```\n\nAfter registering a class implementing `ImapEventsGenerator`, it appears in the dropdown list of the *Event Generator Class*\nfield in *IMAP Configuration Editor* (for more details, see [IMAP Configuration Editor](#imap-configuration-editor)).\n\n![Event Generator Class Field](img/event-generator-class.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Fimap-addon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcuba-platform%2Fimap-addon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcuba-platform%2Fimap-addon/lists"}