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.

Limitations

You must get the port, username, and password data in your email provider.
The Send Emails parameter enables sending emails through IMAP. Some email servers, however, require you to enable email sending throug IMAP to avoid errors during runtime. If you can't enable sending emails through IMAP, use the Use Customized SMTP Credentials parameter and enter your SMTP settings to enable sending emails using this connection.
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 (microsoftMailConnect) command.

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.

If you have problems connecting to a service using Basic Authentication, use the Integration Connection instead. Some services, such as Gmail and Outlook, can block access to certain applications and require additional authentication.

To use an Integration Connection, you must configure your connection in the IBM RPA Control Center. For more information, see:

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: If you use services such as Gmail or Outlook, you must use Connections to connect with an IMAP email server. These services block unauthorized applications from accessing your email account, and require an OAuth authentication method to provide access to their services. You must configure a valid Connection before you use these email services. For more information, see Adding connections to an application.

The following example demonstrates how to effectively use a connection to connect with Gmail and read email messages:

defVar --name email --type EmailMessage
defVar --name subject --type String
defVar --name body --type String
defVar --name from --type String
defVar --name to --type List --innertype String
defVar --name cc --type List --innertype String
defVar --name bcc --type List --innertype String
defVar --name receivedDate --type DateTime
defVar --name emailConnection --type EmailConnection
imapConnect --connection rpa_test_gmail --mailhost "imap.gmail.com" --mailport 993 --usessl  --authenticationtype "IntegrationConnection" emailConnection=value
foreach --collection "${emailConnection}" --variable "${email}"
	emailRead --message ${email} subject=subject body=body from=from to=to cc=cc bcc=bcc receivedDate=receiveddate
	logMessage --message "${body}" --type "Info"
endFor

Remember:Replace the connection used in the example with a valid connection that is authorized to the sender's email account.

Example 2: Using Basic Authentication, the following example 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 "imap.example.com" --mailport 993 --usessl--UseConnectionToSend--smtpcredentials--smtphost "smtp.example.com" --smtpport 587 --smtpusername "useremail@example.com" --smtppassword userpassword --smtpusessl--username "useremail@example.com" --mailusername "useremail@example.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 3: Using Basic Authentication, the following example connects to an IMAP email server and searches for email messages 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 "imap.example.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.