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.