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` parameter 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. The workaround is to add your email provider to the Microsoft™ Outlook service and use the Connect to Microsoft Outlook (outlookConnect) command.