public class EmailClient extends Object
The main purpose of this class is waiting and reading of inbound email messages within RPA process. It's adapted
to make this work is much simpler and convenient as possible. This is achieved by using of
RPAServicesAccessor to get all necessary configuration parameters and thus moving out the definition of
them from RPA process code. In conjunction with using of Inject annotation the using of this class
looks easy and clear:
@Injectprivate EmailClient emailClient; public void execute() { ...List<EmailMessage> messages = emailClient.fetchMessages();... }
EmailMessage| Constructor and Description |
|---|
EmailClient()
Default constructor of this EmailClient.
|
EmailClient(eu.easyrpa.openframework.core.sevices.RPAServicesAccessor rpaServices)
Constructs EmailClient with provided
RPAServicesAccessor. |
| Modifier and Type | Method and Description |
|---|---|
EmailMessage |
copyMessage(EmailMessage message,
String targetFolder)
Makes a copy of given email message in the specified folder.
|
boolean |
createFolder(String folderName)
Creates a new folder with given name in the mailbox.
|
EmailClient |
defaultFolder(String defaultFolder)
Sets explicitly the name of default mailbox folder with inbound messages.
|
boolean |
deleteFolder(String folderName)
Deletes given mailbox folder with all messages and sub-folders contained in it.
|
void |
deleteMessage(EmailMessage message)
Deletes given email message from the mailbox.
|
void |
deleteMessages(List<EmailMessage> messages)
Deletes given email messages from the mailbox.
|
List<EmailMessage> |
fetchAllMessages()
Gets all email messages contained in all mailbox folders.
|
List<EmailMessage> |
fetchAllMessages(Predicate<EmailMessage> isSatisfy)
Gets all email messages contained in all mailbox folders and satisfy to specific condition.
|
EmailMessage |
fetchMessage(String messageId)
Searches email message in the mailbox with given message ID.
|
List<EmailMessage> |
fetchMessages()
Gets all email messages contained in the default mailbox folder.
|
List<EmailMessage> |
fetchMessages(Predicate<EmailMessage> isSatisfy)
Gets email messages contained in the default mailbox folder and satisfy to specific condition.
|
List<EmailMessage> |
fetchMessages(String folderName)
Gets all email messages contained in the mailbox folder with given name.
|
List<EmailMessage> |
fetchMessages(String folderName,
Predicate<EmailMessage> isSatisfy)
Gets email messages contained in the mailbox folder with given name and satisfy to specific condition.
|
List<EmailMessage> |
fetchUnreadMessages(boolean markRead)
Gets unread messages contained in the mailbox.
|
List<EmailMessage> |
fetchUnreadMessages(String folderName,
boolean markRead)
Gets unread messages contained in the mailbox folder with given name.
|
protected String |
getConfigParam(String key)
Gets value of configuration parameter specified in the RPA platform by the given key.
|
String |
getDefaultFolder()
Gets the name of default mailbox folder with inbound messages.
|
int |
getMessageCount()
Gets amount of email messages in the default mailbox folder.
|
int |
getMessageCount(String folderName)
Gets amount of email messages in the mailbox folder with given name.
|
InboundEmailProtocol |
getProtocol()
Gets protocol that is necessary to use for working with inbound email server.
|
String |
getSecret()
Gets JSON string with secret information necessary to perform authentication to specific mailbox on
the server.
|
String |
getServer()
Gets inbound email server URL.
|
List<String> |
listFolders()
Gets the list of folder names that are present in the mailbox.
|
EmailMessage |
moveMessage(EmailMessage message,
String targetFolder)
Moves given email message to the specified folder.
|
EmailClient |
protocol(InboundEmailProtocol protocol)
Sets explicitly the value of protocol that is necessary to use for working with inbound email server.
|
EmailClient |
protocol(String protocol)
Sets explicitly the value of protocol that is necessary to use for working with inbound email server.
|
boolean |
renameFolder(String folderName,
String newFolderName)
Renames given mailbox folder.
|
EmailClient |
secret(String secret)
Sets explicitly the value of secret information necessary to perform authentication to specific mailbox on
the server.
|
EmailClient |
secret(String userName,
String password)
Sets explicitly credentials necessary to perform authentication to specific mailbox on the server.
|
EmailClient |
server(String emailServerHostAndPort)
Sets explicitly the value of inbound email server URL.
|
void |
setDefaultFolder(String defaultFolder)
Sets explicitly the name of default mailbox folder with inbound messages.
|
void |
setProtocol(InboundEmailProtocol protocol)
Sets explicitly the value of protocol that is necessary to use for working with inbound email server.
|
void |
setSecret(String secret)
Sets explicitly the value of secret information necessary to perform authentication to specific mailbox on
the server.
|
void |
setServer(String emailServerHostAndPort)
Sets explicitly the value of inbound email server URL.
|
void |
updateMessage(EmailMessage message)
Updates parameters of given email message in the mailbox.
|
void |
updateMessages(List<EmailMessage> messages)
Updates parameters of given email messages in the mailbox.
|
CompletableFuture<List<EmailMessage>> |
waitMessages(Predicate<EmailMessage> isSatisfy)
Waits appearing of email messages in the default mailbox folder that satisfy to specific condition.
|
CompletableFuture<List<EmailMessage>> |
waitMessages(Predicate<EmailMessage> isSatisfy,
Duration timeout)
Waits appearing of email messages in the default mailbox folder that satisfy to specific condition.
|
CompletableFuture<List<EmailMessage>> |
waitMessages(Predicate<EmailMessage> isSatisfy,
Duration timeout,
Duration checkInterval)
Waits appearing of email messages in the default mailbox folder that satisfy to specific condition.
|
CompletableFuture<List<EmailMessage>> |
waitMessages(String folderName,
Predicate<EmailMessage> isSatisfy)
Waits appearing of email messages in the mailbox folder with given name that satisfy to specific condition.
|
CompletableFuture<List<EmailMessage>> |
waitMessages(String folderName,
Predicate<EmailMessage> isSatisfy,
Duration timeout)
Waits appearing of email messages in the mailbox folder with given name that satisfy to specific condition.
|
CompletableFuture<List<EmailMessage>> |
waitMessages(String folderName,
Predicate<EmailMessage> isSatisfy,
Duration timeout,
Duration checkInterval)
Waits appearing of email messages in the mailbox folder with given name that satisfy to specific condition.
|
public EmailClient()
This constructor should be used in case of manual providing of parameters for connection with inbound email server or if its necessary to work with more than one email server at the same time. E.g.:
EmailClient client1 = new EmailClient().server("imap1.mail.com").protocol("imaps")
.secret("{ \"user\": \"user1@mail.com\", \"password": \"passphrase\" }");
EmailClient client2 = new EmailClient().server("imap2.mail.com").protocol("imaps")
.secret("{ \"user\": \"user2@mail.com\", \"password": \"passphrase\" }");
...
});
@Inject public EmailClient(eu.easyrpa.openframework.core.sevices.RPAServicesAccessor rpaServices)
RPAServicesAccessor.
This constructor is used in case of injecting of this EmailClient using Inject annotation. This is
preferable way of working with this class. E.g.:
@Injectprivate EmailClient emailClient; public void execute() { ...List<EmailMessage> messages = emailClient.fetchMessages();... }
rpaServices - instance of RPAServicesAccessor that allows to use provided by RPA platform services
like configuration, secret vault etc.public String getServer()
If this server URL is not specified explicitly then it will be looked up in configurations parameters of the
RPA platform under the key inbound.email.server.
public void setServer(String emailServerHostAndPort)
This parameter can be changed at any time of working with this class. It will switch to work with a new value before calling of next service method.
emailServerHostAndPort - inbound email server URL with host name and port to set.public EmailClient server(String emailServerHostAndPort)
This parameter can be changed at any time of working with this class. It will switch to work with a new value before calling of next service method.
emailServerHostAndPort - inbound email server URL with host name and port to set.public InboundEmailProtocol getProtocol()
If this protocol is not specified explicitly then it will be looked up in configurations parameters of the
RPA platform under the key "inbound.email.protocol".
If it's not specified in configurations parameters either then "imap" protocol will be
used as default.
InboundEmailProtocol representing necessary to use protocol.public void setProtocol(InboundEmailProtocol protocol)
This parameter can be changed at any time of working with this class. It will switch to work with a new value before calling of next service method.
protocol - InboundEmailProtocol that is necessary to use.public EmailClient protocol(InboundEmailProtocol protocol)
This parameter can be changed at any time of working with this class. It will switch to work with a new value before calling of next service method.
protocol - InboundEmailProtocol that is necessary to use.public EmailClient protocol(String protocol)
This parameter can be changed at any time of working with this class. It will switch to work with a new value before calling of next service method.
protocol - string with name of protocol that is necessary to use.public String getSecret()
The JSON string format depends on the protocol used by this client. But in most cases it looks like the following:
{ "user": "email@dress", "password": "passphrase" }
If this secret string is not specified explicitly then it will be looked up in secret vault of the
RPA platform. The secret vault alias that is necessary to lookup is expected to be specified in configuration
parameters under the key "inbound.email.secret".
public void setSecret(String secret)
The secret information should be in JSON format. Specific format depends on the protocol used by this client. But in most cases it should look like the following:
{ "user": "email@dress", "password": "passphrase" }
This parameter can be changed at any time of working with this class. It will switch to work with a new value before calling of next service method.
secret - JSON string with secret information to set.public EmailClient secret(String secret)
The secret information should be in JSON format. Specific format depends on the protocol used by this client. But in most cases it should look like the following:
{ "user": "email@dress", "password": "passphrase" }
This parameter can be changed at any time of working with this class. It will switch to work with a new value before calling of next service method.
secret - JSON string with secret information to set.public EmailClient secret(String userName, String password)
These parameters can be changed at any time of working with this class. It will switch to work with new values before calling of next service method.
userName - email address of the necessary mailbox.password - pass phrase to access the necessary mailbox.public String getDefaultFolder()
If the default folder name is not specified explicitly then it will be looked up in configurations parameters
of the RPA platform under the key "mailbox.default.folder".
If it's not specified in configurations parameters either then "INBOX" folder will be used.
public void setDefaultFolder(String defaultFolder)
defaultFolder - the name of mailbox folder with inbound messages to set as default.public EmailClient defaultFolder(String defaultFolder)
defaultFolder - the name of mailbox folder with inbound messages to set as default.public int getMessageCount()
The name of default mailbox folder is taken using getDefaultFolder().
EmailMessagingException - in case of some errors.public int getMessageCount(String folderName)
folderName - the name of mailbox folder where is necessary to count messages.EmailMessagingException - in case of some errors.public EmailMessage fetchMessage(String messageId)
It views all mailbox folders to find the necessary message.
messageId - the unique identifier of email message that is necessary to find.EmailMessage object representing found email message or null if nothing is found.EmailMessagingException - in case of some errors.public List<EmailMessage> fetchMessages()
The name of default mailbox folder is taken using getDefaultFolder().
EmailMessage objects representing existing email messages.EmailMessagingException - in case of some errors.public List<EmailMessage> fetchMessages(String folderName)
folderName - the name of mailbox folder which is necessary to get all messages from.EmailMessage objects representing existing email messages.EmailMessagingException - in case of some errors.public List<EmailMessage> fetchMessages(Predicate<EmailMessage> isSatisfy)
The name of default mailbox folder is taken using getDefaultFolder().
If it's necessary to interrupt the fetching of messages by some reason the special
BreakEmailFetchException can be thrown to do it. E.g. when all necessary messages are found and it
doesn't make sense to continue the fetching.
Here is an example of using this exception:
@Injectprivate EmailClient emailClient; public void execute() { ... log.info("Fetch the first message from default inbox folder that contain attachments.");List<EmailMessage>messages = emailClient.fetchMessages(msg -> { if (msg.hasAttachments()) { //By throwing this exception it stops further checking of //emails and return this message as single result throw new BreakEmailCheckException(true); } return false; }); ... }
isSatisfy - lambda expression representing specific condition. It should return true to let
email message get into results.EmailMessage objects representing satisfying email messages.EmailMessagingException - in case of some errors.public List<EmailMessage> fetchMessages(String folderName, Predicate<EmailMessage> isSatisfy)
If it's necessary to interrupt the fetching of messages by some reason the special
BreakEmailFetchException can be thrown to do it. E.g. when all necessary messages are found and it
doesn't make sense to continue the fetching.
Here is an example of using this exception:
@Injectprivate EmailClient emailClient; public void execute() { ... log.info("Fetch the first message from 'Personal' folder that contain attachments.");List<EmailMessage>messages = emailClient.fetchMessages("Personal", msg -> { if (msg.hasAttachments()) { //By throwing this exception it stops further checking of //emails and return this message as single result throw new BreakEmailCheckException(true); } return false; }); ... }
folderName - the name of mailbox folder where is necessary to collect email messages.isSatisfy - lambda expression representing specific condition. It should return true to let
email message get into results.EmailMessage objects representing satisfying email messages.EmailMessagingException - in case of some errors.public List<EmailMessage> fetchAllMessages()
WARNING: This is a heavy operations and can take much time.
EmailMessage objects representing existing email messages.EmailMessagingException - in case of some errors.public List<EmailMessage> fetchAllMessages(Predicate<EmailMessage> isSatisfy)
WARNING: This is a heavy operations and can take much time.
If it's necessary to interrupt the fetching of messages by some reason the special
BreakEmailFetchException can be thrown to do it. E.g. when all necessary messages are found and it
doesn't make sense to continue the fetching.
Here is an example of using this exception:
@Injectprivate EmailClient emailClient; public void execute() { ... log.info("Fetch the first message that contain attachments.");List<EmailMessage>messages = emailClient.fetchAllMessages("msg -> { if (msg.hasAttachments()) { //By throwing this exception it stops further checking of //emails and return this message as single result throw new BreakEmailCheckException(true); } return false; }); ... }
isSatisfy - lambda expression representing specific condition. It should return true to let
email message get into results.EmailMessage objects representing satisfying email messages.EmailMessagingException - in case of some errors.public List<EmailMessage> fetchUnreadMessages(boolean markRead)
It views all mailbox folders to find unread message.
markRead - whether is necessary to mark all found unread messages as read immediately.EmailMessage objects representing unread email messages.EmailMessagingException - in case of some errors.public List<EmailMessage> fetchUnreadMessages(String folderName, boolean markRead)
folderName - the name of mailbox folder where is necessary to search unread messages.markRead - whether is necessary to mark all found unread messages as read immediately.EmailMessage objects representing unread email messages.EmailMessagingException - in case of some errors.public CompletableFuture<List<EmailMessage>> waitMessages(Predicate<EmailMessage> isSatisfy)
The waiting of messages is performed asynchronously using CompletableFuture. It allows to save a time
in cases when waiting of messages is expected can take much time and something different can be done in parallel.
When this method is called it does the following:
1 minute is checked newly come messages. If at least one satisfying message
is found the waiting ends and satisfying messages are returned in results. Otherwise continue
with step 3.
1 hour starting from the
moment of this method call. If timeout is reached than the waiting ends and empty result is returned.
Otherwise continue with steps 2-3.
isSatisfy - lambda expression representing specific condition. It should return true to let
the email message get into results.CompletableFuture object with list of EmailMessage objects representing satisfying email
messages as result.EmailMessagingException - in case of some errors.public CompletableFuture<List<EmailMessage>> waitMessages(Predicate<EmailMessage> isSatisfy, Duration timeout)
The waiting of messages is performed asynchronously using CompletableFuture. It allows to save a time
in cases when waiting of messages is expected can take much time and something different can be done in parallel.
When this method is called it does the following:
1 minute is checked newly come messages. If at least one satisfying message
is found the waiting ends and satisfying messages are returned in results. Otherwise continue
with step 3.
timeout starting from the
moment of this method call. If timeout is reached than the waiting ends and empty result is returned.
Otherwise continue with steps 2-3.
isSatisfy - lambda expression representing specific condition. It should return true to let
email message get into results.timeout - the maximum time of waiting necessary messages.CompletableFuture object with list of EmailMessage objects representing satisfying email
messages as result.EmailMessagingException - in case of some errors.public CompletableFuture<List<EmailMessage>> waitMessages(Predicate<EmailMessage> isSatisfy, Duration timeout, Duration checkInterval)
The waiting of messages is performed asynchronously using CompletableFuture. It allows to save a time
in cases when waiting of messages is expected can take much time and something different can be done in parallel.
When this method is called it does the following:
checkInterval is checked newly come messages. If at least one satisfying message
is found the waiting ends and satisfying messages are returned in results. Otherwise continue
with step 3.
timeout starting from the
moment of this method call. If timeout is reached than the waiting ends and empty result is returned.
Otherwise continue with steps 2-3.
isSatisfy - lambda expression representing specific condition. It should return true to let
email message get into results.timeout - the maximum time of waiting necessary messages.checkInterval - amount of time that defines period of checking newly come messages.CompletableFuture object with list of EmailMessage objects representing satisfying email
messages as result.EmailMessagingException - in case of some errors.public CompletableFuture<List<EmailMessage>> waitMessages(String folderName, Predicate<EmailMessage> isSatisfy)
The waiting of messages is performed asynchronously using CompletableFuture. It allows to save a time
in cases when waiting of messages is expected can take much time and something different can be done in parallel.
When this method is called it does the following:
1 minute is checked newly come messages. If at least one satisfying message
is found the waiting ends and satisfying messages are returned in results. Otherwise continue
with step 3.
1 hour starting from the
moment of this method call. If timeout is reached than the waiting ends and empty result is returned.
Otherwise continue with steps 2-3.
folderName - the name of mailbox folder where is necessary to check messages.isSatisfy - lambda expression representing specific condition. It should return true to let
email message get into results.CompletableFuture object with list of EmailMessage objects representing satisfying email
messages as result.EmailMessagingException - in case of some errors.public CompletableFuture<List<EmailMessage>> waitMessages(String folderName, Predicate<EmailMessage> isSatisfy, Duration timeout)
The waiting of messages is performed asynchronously using CompletableFuture. It allows to save a time
in cases when waiting of messages is expected can take much time and something different can be done in parallel.
When this method is called it does the following:
1 minute is checked newly come messages. If at least one satisfying message
is found the waiting ends and satisfying messages are returned in results. Otherwise continue
with step 3.
timeout starting from the
moment of this method call. If timeout is reached than the waiting ends and empty result is returned.
Otherwise continue with steps 2-3.
folderName - the name of mailbox folder where is necessary to check messages.isSatisfy - lambda expression representing specific condition. It should return true to let
email message get into results.timeout - the maximum time of waiting necessary messages.CompletableFuture object with list of EmailMessage objects representing satisfying email
messages as result.EmailMessagingException - in case of some errors.public CompletableFuture<List<EmailMessage>> waitMessages(String folderName, Predicate<EmailMessage> isSatisfy, Duration timeout, Duration checkInterval)
The waiting of messages is performed asynchronously using CompletableFuture. It allows to save a time
in cases when waiting of messages is expected can take much time and something different can be done in parallel.
When this method is called it does the following:
1 minute is checked newly come messages. If at least one satisfying message
is found the waiting ends and satisfying messages are returned in results. Otherwise continue
with step 3.
timeout starting from the
moment of this method call. If timeout is reached than the waiting ends and empty result is returned.
Otherwise continue with steps 2-3.
folderName - the name of mailbox folder where is necessary to check messages.isSatisfy - lambda expression representing specific condition. It should return true to let
email message get into results.timeout - the maximum time of waiting necessary messages.checkInterval - amount of time that defines period of checking newly come messages.CompletableFuture object with list of EmailMessage objects representing satisfying email
messages as result.EmailMessagingException - in case of some errors.public EmailMessage copyMessage(EmailMessage message, String targetFolder)
message - the source email message that should be copied.targetFolder - the name of mailbox folder where the email message should be copied.EmailMessage object representing copied message.EmailMessagingException - in case of some errors.public EmailMessage moveMessage(EmailMessage message, String targetFolder)
The moving is performed by copying of the email message to the specified folder and removing of the source message.
message - the source email message that should be moved.targetFolder - the name of mailbox folder where the email message should be moved.EmailMessage object representing moved message. The source message will be deleted.EmailMessagingException - in case of some errors.public void updateMessage(EmailMessage message)
Currently it updates only one parameter: EmailMessage.isRead flag.
message - the email message whose parameters should be updated in the mailbox.EmailMessagingException - in case of some errors.public void updateMessages(List<EmailMessage> messages)
Currently it updates only one parameter: EmailMessage.isRead flag.
messages - the list of email messages whose parameters should be updated in the mailbox.EmailMessagingException - in case of some errors.public void deleteMessage(EmailMessage message)
The message is deleted permanently without Trash.
message - the email message to delete.EmailMessagingException - in case of some errors.public void deleteMessages(List<EmailMessage> messages)
Messages are deleted permanently without Trash.
messages - the list of email messages to delete.EmailMessagingException - in case of some errors.public List<String> listFolders()
EmailMessagingException - in case of some errors.public boolean createFolder(String folderName)
folderName - the name of folder to create.true if the folder has been created successfully and false otherwise.EmailMessagingException - in case of some errors.public boolean renameFolder(String folderName, String newFolderName)
folderName - the name of source mailbox folder.newFolderName - a new name of the folder.true if the folder has been renamed successfully and false otherwise.EmailMessagingException - in case of some errors.public boolean deleteFolder(String folderName)
folderName - the name of mailbox folder to delete.true if the folder has been deleted successfully and false otherwise.EmailMessagingException - in case of some errors.protected String getConfigParam(String key)
key - the key of configuration parameter that need to lookup.null if parameter is
not found or RPAServicesAccessor is not defined for this email client.Copyright © 2023. All rights reserved.