How to Use the Mail (IMAP) Connector

Document created by magali.kain.boomi Employee on Jan 3, 2018Last modified by Adam Arrowsmith on Jul 6, 2018
Version 14Show Document
  • View in full screen mode

This article discusses how to use the Mail (IMAP) connector to send and receive emails using the IMAP protocol. Let’s see what it takes to get up and running with the Mail (IMAP) connector.


 Get the example process used below from the Process Library here.




The Mail (IMAP) connector allows you to get and send emails via the IMAP protocol instead of POP. The IMAP protocol--and therefore the IMAP connector--supports additional interaction types when working with emails and may be preferred to POP especially when multiple devices or clients are involved. Many SMTP email servers support both protocols so you may be able to start using the IMAP connector without changes to your server.


For complete connector documentation, see the Mail (IMAP) connector.



The Internet Message Access Protocol (IMAP) can be used in place of the Post Office Protocol (POP). IMAP differs from other mail systems because messages are manipulated directly on the email server. As a result, you can access email from any device at any time, and folders and message status are synchronized.


Notable Improvements vs. the Mail Connector (POP)

  • Take advantage of IMAP-specific functionality (e.g. the ability to retrieve emails from specific folders in a mailbox).
  • Receive attachments AND the email body. This is not possible with the current Mail connector which requires you to choose one or the other when retrieving emails.
  • Ability to send multiple attachments, leveraging the Document Cache component.

  • Specify CC and BCC email addresses when sending.
  • Supports transport security up to TLSv1.2 for sending email.

  • More document properties to dynamically set your operations.

  • Move emails from one folder to another as with an explicit connector call after they have been processed.
  • Additional query/filter options when receiving messages.
  • Test Connection option within connection component to quickly verify connection settings are correct without executing entire process.


Configuring the Mail (IMAP) Connection

When configuring the Mail (IMAP) connection, you configure one single connection. The single connection helps to avoid any potential issues with outgoing and incoming email on the server, and also simplifies setup because you only have to choose the valid connection for each operation.


The following image shows a sample Mail (IMAP) connection.





  • For the outbound mail server, enter the host name, port number, select the security protocol, and if required, enter the user name and password.
  • For the inbound mail server, enter the host name, port number, user name, password, and select the security protocol.


Sending an Email with Attachments

Use the Send operation to send messages to an SMTP mail server. This operation supports attachments through the use of the Document Cache. In this case, all of the related operation fields must be filled.


The following image shows the steps in the Send Message with Attachments Process.



  1. Define a unique value to identify the files that will be sent as attachments for a specific email, and ultimately relates them. To illustrate this, create and set a dynamic process property using a Set Properties Shape.
  2. Add the documents into the Document Cache with only one index and key. In this example, we use a dynamic document property as the key. However, you can use any property.
    As you can see in this example, you must set the key property with the value of the dynamic process property that we created in the previous step.
  3. Set the body, if message has one, using a Message Shape.
  4. Set the “Attachment Cache Key” property belonging to the connector with the same value that is used as the key to store the attachments into the cache. In this example, we assign the value specified on the “ROOT_ID” dynamic process property.
  5. Create a new Send Mail (IMAP) operation and configure the associated Document Cache.


And Here's Your Email!




Receiving Emails with Attachments

Use the Receive operation to retrieve emails into the process. The connector now supports using complex query filters to select the emails for processing. When first creating the Operation component, click the Import button in the upper right, browse against the Cloud Atom, and complete the wizard to display the Filter options on the Operation component.


Note: By default, the operation returns unread emails from the inbox if "read" and "fromFolder" filters are not defined.


The Mail (IMAP) connector allows you to retrieve both the email message AND any attachments. When receiving emails, the email message body is sent into the process as a document but the email's related attachments are automatically added to a document cache, indexed by the connector's "Message ID" document property. This document property is associated with each message in the process and is used to retrieve the cached attachments for the given message.


The following image shows the steps in the Receive Messages with Attachments Process.


  1. Set the Document Cache shape. The Document Cache must have one key and it must be the Message ID. Note the profile type must be "None".

  2. Create a new Receive Mail (IMAP) operation, configure the associated Document Cache and set the query filters.
  3. Process the messages.
  4. Process the attachments.


Moving Emails to a Different Folder

Use the Move operation to transfer emails from one folder to another on the mail server using the Message-ID. For example, you may want to move or "archive" a message on the mail server after successfully processing within AtomSphere.


The following image shows the steps in the Move Message to a Different Folder.



  1. Create a new Move Mail (IMAP) operation and import the profile.
  2. Configure the id parameter with the Message ID value on the Mail (IMAP) connector shape parameter.
  3. Execute the operation to move the email.
2 people found this helpful