The IMAP-addon provides a readily available instrument for integrating email messaging into any CUBA-based application via the IMAP protocol. The main model of the component is designed to interact with incoming emails via Spring application events.
The component includes the following set of functionalities:
- Integration between any IMAP servers and CUBA applications.
- Basic API methods to work with the main email server functionalities:
- Connecting to servers;
- Retrieving and viewing emails;
- Searching for emails;
- Operating custom flags.
- Predefined events for implementing custom business logic and processing various updates.
- User interface for configuring IMAP connection settings and events.
See sample application using this component. See webinar on the CUBA Platform channel.
The 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. Also, you can install the add-on by coordinates choosing the required version of the add-on from the table.
In 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.
- Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.
- Go to CUBA -> Marketplace in the main menu.
- Find the IMAP add-on there.
- Click Install and apply the changes. The add-on corresponding to the used platform version will be installed.
- Open your application in CUBA Studio. Check the latest version of CUBA Studio on the CUBA Platform site.
- Go to CUBA -> Marketplace in the main menu.
- Click the icon in the upper-right corner.
- Paste the add-on coordinates in the corresponding field as follows:
com.haulmont.addon.imap:imap-global:<add-on version>
where <add-on version> is compatible with the used version of the CUBA platform.
| Platform Version | Add-on Version |
|---|---|
| 7.2.x | 1.5.1 |
| 7.1.x | 1.4.0 |
| 7.0.x | 1.3.1 |
| 6.10.x | 1.2.0 |
| 6.9.x | 1.1.1 |
| 6.8.x | 1.0.1 |
- Click Install and apply the changes. The add-on will be installed to your project.
Before using the add-on do the following:
- Open
app.propertiesfile of your application and configure the following application properties:
#IMAP configuration
imap.encryption.key = HBXv3Q70IlmBMiW4EMyPHw==
imap.encryption.iv = DYOKud/GWV5boeGvmR/ttg==
#Enable scheduling
cuba.schedulingActive=true- Run the application and go to Administration -> Scheduled tasks screen. Configure
imap_ImapScheduler -> syncImapscheduled task.
IMAP Admin role - allows user to configure IMAP events.
IMAP Configuration Browser is designed to add and manage mailboxes from which emails are retrieved. The browser is available from Menu: Administration → IMAP → IMAP Configuration.
Creating a new configuration is available by clicking the Create button.
IMAP Configuration Editor comprises two main sections to fill in: Basic and Advanced.
Basic
The Basic section enables to configure the main attributes for connecting to an email server via IMAP. The description of all fields is provided below.
- Name: specify a name for connection.
- Host: specify a host name or IP address of an email server.
- Port: provide a port number to connect to an email server. The default value is 143.
- Secure Connection: select an option for secure connection if required. Available values: STARTTLS, SSL/TLS.
- Root Certificate: upload a client certificate if required.
- Username: provide a username to connect to an email server.
- Password: provide a user password to connect to an email server.
The Basic section comprises the Connect button. After providing all required information, use the button to upload a list of folders from the email server to work with.
Advanced
The Advanced section provides a set of additional options for connecting to an email server.
- Custom Flag: specify a custom flag.
- Use trash folder to remove emails: if checked, then it is possible to specify a trash folder of a current mailbox
(the Trash Folder field becomes available). The setting works as follows: if an email is moved to the specified folder on
the email server,
EmailDeletedImapEventoccurs (for more details, see Event Types). - Use custom event generator class: if checked, it is possible to specify a custom class that defines additional logic for connecting to an IMAP server, handling events, etc. If the current setting is enabled, the Event Generator Class lookup field becomes available. To learn how to register a custom event generator class, please refer to Registering Custom IMAP Implementation Class.
- Use proxy: if checked, proxy settings become available (see the description below).
Proxy Configuration
- Proxy Host: provide a host name or IP address of a proxy server.
- Proxy Port: provide a port to connect to a proxy server.
- Use web proxy: if checked, web proxy is used.
Table of Folders
Once connection to the provided email server is successfully established, the table of folders becomes available.
The table shows a list of folders from the email server you are connected to. In order to enable/disable some folders, use the checkboxes in the second column. If some folder is disabled, then messages from it are not retrieved.
For each folder you can select a set of IMAP events by using the Events table and register custom logic for them (for more details, please refer to Configuration).
All emails from connected mailboxes are displayed in IMAP Message Browser (available from Menu: Administration → IMAP → IMAP Message Browser).
Selecting an email and clicking View opens it for reading. Email Screen contains all general details of an email: date, author, subject, etc., and two tabs: Body and Attachments.
On the Body tab, the whole text of an email is displayed.
The Attachments tab comprises the table of attachments and the button to download required elements.
In order to make your application react to IMAP events, you can register the @Component methods as Event listeners by using
the @EventListener annotation. The example of how to set up an event listener is provided below.
import org.springframework.context.event.EventListener;
@Service(EmailReceiveService.NAME)
public class EmailReceiveServiceBean implements EmailReceiveService {
@EventListener
@Override
public void receiveEmail(NewEmailImapEvent event) {
// handles IMAP event
}
}Another option is to create @Component with a method having the required event type as the only parameter.
public class EmailReceiver {
String NAME = "ceuia_EmailReceiver";
public void receiveEmail(NewEmailImapEvent event) {
// handle IMAP event
}
}Once it is done, the selected method (in the example, it is receiveEmail) should be registered on a particular folder
for a given IMAP connection. This should be done at runtime using the IMAP configuration UI (see Creating Handlers for
IMAP Events).
After that, the method will be invoked every time, when the configured event occurs.
After registering EventListeners, it is required to create handlers for IMAP events related to a particular folder and mailbox (for more information see IMAP Connection). The table of folders comprises several columns, each representing a certain event type (e.g. New, Seen, Replied, etc.). Clicking gear icons opens IMAP Folder Event Editor.
There you can specify required beans and methods for them.
All events contain the ImapMessage object that can be used to determine where an event occurs (mailbox, folder, message).
The application component supports the following kinds of IMAP events:
NewEmailImapEventis triggered for a folder having an event of theImapEventType.NEW_EMAILtype enabled, when a new message appears in the folder on the IMAP server.EmailSeenImapEventis triggered for a folder having an event of theImapEventType.EMAIL_SEENtype enabled, when a message is marked with thejavax.mail.Flags.Flag.SEENIMAP flag.EmailAnsweredImapEventis triggered for a folder having an event of theImapEventType.NEW_ANSWERtype enabled, when a message is replied (usually it happens when a message is marked with thejavax.mail.Flags.Flag.ANSWEREDIMAP flag).EmailFlagChangedImapEventis triggered for a folder having an event of theImapEventType.FLAGS_UPDATEDtype enabled, when a standard or custom IMAP flag is changed for a message. The event contains aMapof all changed flags and their actual state (set or unset).EmailDeletedImapEventis triggered for a folder having an event of theImapEventType.EMAIL_DELETEDtype enabled, when a message is completely deleted from a folder on the IMAP server side, it is not related to the IMAP flagjavax.mail.Flags.Flag.DELETED. Such events are also triggered when a message is moved to a trash folder (if it is configured for a mailbox) on the server.EmailMovedImapEventis triggered for a folder having an event of theImapEventType.EMAIL_MOVEDtype enabled, when a message is moved to another folder on the IMAP server. Note: the standard implementation tracks only folders which are selected in theImapMailBoxconfiguration, but does not count a trash folder, if one is configured.NewThreadImapEventis not implemented yet.
The component provides the following API to interact with the IMAP server:
ImapAPImethods:Collection<ImapFolderDto> fetchFolders(ImapMailBox)— retrieves all folders preserving the tree structure.Collection<ImapFolderDto> fetchFolders(ImapMailBox, String...)— retrieves folders with the specified names. The result is not structured as a tree.List<ImapFolderDto> fetchMessage(ImapMessage)— fetches a single message using a reference.void moveMessage(ImapMessage, String)— moves a message to a different folder on the IMAP server side.void deleteMessage(ImapMessage)— deletes a message from a folder.void setFlag(ImapMessage, ImapFlag, boolean)— sets or unsets a specified flag for a message.
ImapAttachmentsAPImethods:Collection<ImapMessageAttachment> fetchAttachments(ImapMessage)— retrieves attachments included in a message. The result contains only meta data, no content.InputStream openStream(ImapMessageAttachment)andbyte[] loadFile(ImapMessageAttachment— retrieve the content of a message attachment.
In order to configure custom logic for a specific mailbox (e.g for applying IMAP extensions and custom communication mechanisms), it is required to register a custom IMAP implementation class in the source code of your application. The example of how to register such class is given below.
@Component("demo_SimpleSingleFolderNewMessagesEventsGenerator")
public class SimpleSingleFolderNewMessagesEventsGenerator implements ImapEventsGenerator {
...
}After registering a class implementing ImapEventsGenerator, it appears in the dropdown list of the Event Generator Class
field in IMAP Configuration Editor (for more details, see IMAP Configuration Editor).
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
