Connect to IMAP Email Server

Connects to an IMAP 🡥 email server.

Command availability: IBM RPA SaaS and IBM RPA on premises

Description

Connects to an IMAP 🡥 email server, storing the connection established in a variable. The command does a direct search in the Inbox folder of the email. To specify a folder, use the Apply Search Filters (emailApplySearchFilters) command.

Script syntax

IBM RPA's proprietary script language has a syntax similar to other programming languages. The script syntax defines the command's syntax in the script file. You can work with this syntax in IBM RPA Studio's Script mode.

imapConnect --mailhost(String) --mailport(Numeric) [--usessl(Boolean)] [--UseConnectionToSend(Boolean)] [--smtpcredentials(Boolean)] --smtphost(String) --smtpport(Numeric) --smtpusername(String) --smtppassword(String) [--smtpusessl(Boolean)] [--username(String)] --mailusername(String) [--mailpassword(String)] [--enableLog(Boolean)] (EmailConnection)=value

Dependencies

  • If you are using the IntegrationConnection authentication type, refer to Connections.

Input parameters

The following table displays the list of input parameters available in this command. In the table, you can see the parameter name when working in IBM RPA Studio's Script mode and its Designer mode equivalent label.

Designer mode label Script mode name Required Accepted variable types Description
IMAP address mailhost Required Text IMAP Address of the email server.
Port mailport Required Number TCP port of the IMAP server to connect.
Authentication Type authenticationtype Required Text The type of authentication. See the authenticationType paremeter options.
Connection connection Required when the authentication type parameter is IntegrationConnection text Connections available in your tenant.
Use SSL usessl Optional Boolean When enabled, it uses the security protocol SSL 🡥 for IMAP.
Send Emails UseConnectionToSend Optional Boolean Enable to allow the connection to also send emails.
Use Customized SMTP Credentials smtpcredentials Optional Boolean When enabled, it allows fields to use a customized SMTP 🡥 email sending protocol.
SMTP Address smtphost Required when the Use Customized SMTP Credentials parameter is enabled Text SMTP address of the email server.
SMTP Port smtpport Required when the Use Customized SMTP Credentials parameter is enabled Number TCP port number of the SMTP server to connect.
SMTP User Name smtpusername Required when the Use Customized SMTP Credentials parameter is enabled Text Client username registered on the SMTP server.
SMTP Password smtppassword Required when the Use Customized SMTP Credentials parameter is enabled Text Client user password registered on the SMTP server.
Use SSL for SMTP smtpusessl Optional Boolean When enabled, it allows the use of the SSL 🡥 protocol for SMTP.
User Name username Optional Text Username for email authentication.

🛈 Remember: Usually this is the email address of the account registered on the IMAP server.
Email mailusername Required Text Email address for the connection.
Password mailpassword Optional Text Password of the email used to connect.
Shared Mailbox to access sharedboxaddress Optional Text The shared mailbox that you want to access.
⚠ Attention: If you provide a mailbox, the command connects only to this shared mailbox rather than connecting to the account set on Email.
Enable Log enableLog Optional Boolean Enables protocol logging, if available.

The %localappdata%\IBM Robotic Process Automation directory stores the log file.

authenticationType parameter options

The following table displays the options available for the authenticationType input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.

Designer mode label Script mode name Description
BasicAuthentication basicAuthentication Uses basic authentication to authenticate third-party accounts. Requires User name and password.
IntegrationConnection integrationConnection Uses Oauth authenticated connections from the tenant you're logged in.

Output parameters

Designer mode label Script mode name Accepted variable types Description
Connection value Email Connection Collection containing all messages from the Inbox folder of the email.

Examples

Example 1: The command connects to an IMAP email server using a customized SMTP protocol, with email sending enabled.

defVar --name emailDestination --type List --innertype String --value "[destination@email.com]"
defVar --name emailConnection --type EmailConnection
imapConnect --mailhost "outlook.office365.com" --mailport 993 --usessl--UseConnectionToSend--smtpcredentials--smtphost "smtp.office365.com" --smtpport 587 --smtpusername "useremail@email.com" --smtppassword userpassword --smtpusessl--username "useremail@email.com" --mailusername "useremail@email.com" --mailpassword userpassword --enableLogemailConnection=value
emailSend --connection ${emailConnection} --to ${emailDestination} --from "useremail@email.com" --subject test --bodytype "Text" --body "Message body"
// Sending an email over the IMAP connection with SMTP protocol.

Example 2: Connects to an IMAP email server and searches for emails on all folders that contains attachments.

defVar --name emailDestination --type List --innertype String --value "[destination@email.com]"
defVar --name emailConnection --type EmailConnection
defVar --name outputConnection --type EmailConnection
// Connect to IMAP Email server
imapConnect --mailhost "outlook.office365.com" --mailport 993 --mailusername "useremail@email.com" --mailpassword userpassword
// Apply a filter to search only for emails with attachments in all folders.
emailApplySearchFilters --searchallemails  --subjectdirective "All" --wordsdirective "All" --withattachment  --connection ${emailConnection}
// Disconnect from the server.
emailDisconnect --connection ${emailConnection}

🛈 Remember: The previous examples are only illustrative, so for it to work, you must enter a valid IMAP connection and its appropriate settings.

Limitations

  • You must get the port, username, and password data in your email provider.

  • The Send Emails parameter enables the sending of email with the IMAP connection, however, for some email servers, it is necessary to configure this sending. Otherwise, an error will appear in the script execution. If it is not possible to configure this sending, it is recommended to use the Use Customized SMTP Credentials parameter and a customized SMTP protocol.

  • To send emails the connection must use the original email account and not an alias. Connections using an aliased email account can only read emails.