Email Reader

In this article

Overview

You can use this Snap to read IMAP or POP3 server email messages. In addition to reading emails, you can also process inline images, images sent as attachments, archive read emails using this Snap. The Snap allows you to choose the target folder where such archived emails are moved, and you can use this feature to delete emails as well by configuring the corresponding 'trash' folder in your email.

Snap Type

Email Reader Snap is a READ-type Snap that reads the data and passes to the downstream Snap.

Prerequisites

This Snap requires a valid IMAP or POP 3 account to handle access to this endpoint.

Clicking the "Preview" button does not read any email message if the account is IMAP and the Unread only property is checked. When unread messages are read, they are all marked as "read" in the mail server. Therefore, they should not be read during the preview. Otherwise, the execution of the Snap will not be able to read any message.

Support for Ultra Pipelines

Works in Ultra Pipelines

Limitations

Gmail IMAP or POP3 accounts may not work with the Email Reader Snap. Gmail processes an email hijack detection based on IP addresses and locations. If it sees the IP address that the IMAP or POP3 client app is running from is different than the usual locations, it suspects the account is being hijacked and sends error messages like:

  • +OK Gpop ready for requests from 23.23.38.68 n18mb191678450qav" or

  • Cannot connect to the endpoint reason: [SYS/PERM] Your account is not enabled for POP access. Please visit your Gmail settings page and enable your account for POP access." or other variations.

You may find an email from Gmail in the inbox titled "Suspicious sign in prevented", which is caused by the execution of Email Reader Snap. You may be able to see more messages from Gmail in your Gmail account web page: Account > Security > Recent Activity > View activity. As of writing this note, there seems to be no settings available in the Gmail account to disable this security feature. Please contact Gmail Support if your Gmail account must work in Email Reader Snap.

Known Issues

None.

Snap Views

Type

Format

Number of Views

Examples of Upstream and Downstream Snaps

Description

Type

Format

Number of Views

Examples of Upstream and Downstream Snaps

Description

Input 

Document

  • Min: 0

  • Max: 1

Document

This Snap has at the most one document input view.

By default, the input view is not enabled; however, you can specify at the most one input.

Output

Document

 

  • Min: 1

  • Max: 1

Document

This Snap has exactly one output view and produces documents in the view. Each Document contains a Map data which represents one email message. The keys in the document are "from", "to", "cc", "subject", "dateSent", "emailType", "textBody", "htmlBody" and "attachments". The value of "from", "to" and "cc" keys is a list of strings. The value of "subject" and "dateSent" keys is a string.The value of "emailType" key is "text/plain" or "text/html" or "multipart/*". The value of "attachments" key is a list of Map data. Each Map data corresponds to an attached file. The keys of the Map data are "contentType", "filename" and "attachment". The value of the "attachment" key is a binary data read from the attached file. If the email message received has a nested multipart of content, all plain text bodies are appended to the value of the "textBody" key, and all HTML contents to the value of the "htmlBody" key. The following is an example of an Output Document:

{ from: "sender@example.com", to: "Snap@example.com; youto@example.com", cc: "meto@example.com", subject: "testing Email Sender Snap", emailType: "text/plain", textBody: "This is a sample email body.", htmlBody: "", dateSent: "Thu Mar 06 09:20:06 PST 2014", attachments: [ { contentType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet; name="bbskus.xlsx"", filename: "sldb:///Snaplogic/projects/attachments/bbskus.xlsx", status: "overwritten" } ] }

Error

Error handling is a generic way to handle errors without losing data or failing the Snap execution. You can handle the errors that the Snap might encounter while running the Pipeline by choosing one of the following options from the When errors occur list under the Views tab. The available options are:

  • Stop Pipeline Execution: Stops the current pipeline execution when the Snap encounters an error.

  • Discard Error Data and Continue: Ignores the error, discards that record, and continues with the rest of the records.

  • Route Error Data to Error View: Routes the error data to an error view without stopping the Snap execution.

Learn more about Error handling in Pipelines.

Snap Settings

  • Asterisk (*): Indicates a mandatory field.

  • Suggestion icon (): Indicates a list that is dynamically populated based on the configuration.

  • Expression icon (): Indicates whether the value is an expression (if enabled) or a static value (if disabled). Learn more about Using Expressions in SnapLogic.

  • Add icon (): Indicates that you can add fields in the fieldset.

  • Remove icon (): Indicates that you can remove fields from the fieldset.

Field Name

Field Type

Field Dependency

Description

Field Name

Field Type

Field Dependency

Description

Label*

Default ValueEmail Reader
ExampleEmail Reader

String

None

Specify the name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your Pipeline.

 

Mail folder*

Default Value: Inbox
Example: Inbox

String/Expression

None

Specify the name of email folder where the Snap reads messages from.

Ensure that you specify the folder name as it appears on the email client, because folder names might be case-sensitive for some email providers, such as Yahoo. Otherwise, the Snap displays Error retrieving folder for given source or destination error.

Unread only

Default Value: Selected
Example: Selected

Checkbox

None

Select this checkbox to inform Snap to read only the unread email messages. If you do not select this checkbox, the Snap reads all messages.

 If this property is selected, the Snap does not execute during preview as the execution changes the state of the unread messages.

Number of messages

Default Value: All
Example: 100

Integer

None

Specify the maximum number of messages that the Snap has to read. Any non-integer or negative value leads to "All" messages being moved.

Older message first

Default Value: Deselected
Example: Selected

Checkbox

None

Select this checkbox to view the older messages first in the output view. If you do not select this checkbox, the latest messages display first in the output view.

Attachment folder

Default Value: Shared
Example: smb://<username>@<hostname>:<port>/<directory>

String/Expression

None

Specify the URL of the directory where attached files are stored. If this property is blank, all attached files are ignored.

  • This property is expression-enabled. For more information on the expression language, see Expression Language Overview and Expression Language Usage.

  • The user must have write access to the target folder listed in this field.

  • If the Attachment folder is in the SMB file protocol, the name of the file attached to the Email must not contain any of the following characters:  " \ / : | < > * ?

The following are the most commonly-used target directory values:

  • shared: The Snap writes attachment files to /<org>/shared/ 

  • /<org>/projects/<project>: The Snap writes attachment files to the specified project.

  • sftp://<username>@<hostname>:<port>/<directory>:The Snap writes attachment files to the specified directory.

  • smb://<username>@<hostname>:<port>/<directory>: The Snap writes attachment files to the specified directory.

  • smb://<domain>;<username>@<hostname>:<port>/<directory>: The Snap writes attachment files to the specified directory. if the SMB credential has a Domain field, there should be a semicolon used as a separator between <domain> and <username>.

  • For SFTP and SMB paths, the password should be entered into the Attachment password property in the email account.

Examples:

  • sldb:///snaplogic/projects/attachments

  • $attachmentFolder

  • sftp://mrtest@ftp.xyz.com/home/mrtest

  • smb://mydomain;snapuser@54.111.223.111:444/snapuser/

File action

Default ValueOVERWRITE
Example: RENAME

Dropdown list

None

Select an action to be taken if a file with the same name as in the email attachments exists in the specified directory. The available options include:

  • OVERWRITE

  • RENAME

  • IGNORE

  • ERROR

If ERROR is selected, the Snap displays an error message and the pipeline execution is terminated when it encounters an already existing file.

Archive messages after reading

Default ValueDeselected
Example: Selected

 

None

Select this checkbox to move or archive the read messages. If you do not select this checkbox, the read messages are not moved or archived.

Target folder

Value: None
Example: Archived

String/Suggestion

Archive messages after reading

Specify the target location for the archived emails. You need to configure this property only if you select the Archive messages after reading field. This is a suggestible field and the suggestions are based on the folders available in the email account.  

Ensure that you specify the folder name as it appears on the email client, because folder names might be case-sensitive for some email providers, such as Yahoo. Otherwise, the Snap displays Error retrieving folder for given source or destination error.

Snap Execution

Default ValueValidate & Execute
Example: Execute only

Dropdown list

N/A

Select one of the three modes in which the Snap executes. Available options are:

  • Validate & Execute: Performs limited execution of the Snap, and generates a data preview during Pipeline validation. Subsequently, performs full execution of the Snap (unlimited records) during Pipeline runtime.

  • Execute only: Performs full execution of the Snap during Pipeline execution without generating preview data.

  • Disabled: Disables the Snap and all Snaps that are downstream from it.

Examples

Reading Attachment from an SFTP Location

In this pipeline, the Email Reader Snap reads the attachment from the path as provided in the Attachment folder field, in this case, from an SFTP location. 

The Email Reader Snap is configured as in the following image:

email-reader-example.png

 

In order to read and store the files on a provided location, the Attachment password must be set on the Account Settings of the Snap, else will display an error.

 

Reading Emails from Shared Mailbox

The pipeline below demonstrates how the Email Reader Snap is used to read emails from shared mailboxes:

The Snap's configuration is the same as in reading emails from individual mailboxes, however the Account settings are to be configured a little differently:

  • Email ID - email ID suffixed with "/shared-mailbox". For example, abc@hotmail.com/shared-mailbox

  • Mail properties fields:

    • Mail property name: mail.imaps.auth.plain.disable

    • Mail property value: true

The screenshot below is a sample of the Account settings for such a configuration:

Validate the account and click Apply. If the mail properties are not configured the validation fails with an exception.

The Email Reader Snap is configured the same way as in individual mailboxes, in the Mail folder property, the folders from the shared mailbox are suggested as seen in the screenshot below:

A sample preview of the output data showing one of the emails in the shared mailbox.

Archiving Read Emails

The emails read by the Snap can be archived/moved to a specified target location using this Snap. In this example, the emails are moved to the Spam folder. The pipeline is as shown in the screenshot below:

The Email Reader Snap is configured as shown in the screenshot below:

The Archive messages after reading property is selected, and the target folder is specified as the Spam folder. The email page shows the Inbox of the email account with an email, which will be archived and moved to the Spam folder when the Snap is executed.

Below is a preview of the output from the Snap, it shows the body of the email along with other email attributes:

When refreshed, the Inbox is updated and the email is moved to the Spam folder:

Delete Emails Using the Archive Feature

The emails read by the Snap can be archived/moved to a specified target location using this Snap. In this example, the emails are moved to the Trash folder. The pipeline is as shown in the screenshot below:

The Email Reader Snap is configured as shown in the screenshot below:

The Archive messages after reading property is selected and the target folder is specified as the Trash folder. The email page displays the Inbox of the email account with an email. This email will be archived and moved to the Trash folder when the Snap is executed.

Below is a preview of the output from the Snap, it shows the body of the email along with other email attributes:

When refreshed, it can be seen that the Inbox is updated and the email is moved to the Trash folder.

Read Inline Images

The pipeline in this example, Reading_Inline_Attachment_Images.slp, demonstrates the image reading functionality of the File Reader Snap. An email containing an inline image and an image as an attachment is passed to the Email Reader Snap.

Upon execution, the output preview shows the inline and attached image.

Download this pipeline.

We have an email in a Gmail account inbox that contains both an inline image and an image as an attachment:

Configure the Email Reader Snap as shown below:

 

 

 

 

The output preview of the Snap displays the details of the image files in the email, both inline and attachments:

Downloads

  1. Download and import the Pipeline into SnapLogic.

  2. Configure Snap accounts as applicable.

  3. Provide Pipeline parameters as applicable.

 

  File Modified

File Basic Use Case_Email Reader_Shared Mailbox.slp

Mar 13, 2018 by Mohammed Iqbal

File Email Reader_ Archive test.slp

Jul 20, 2018 by Mohammed Iqbal

File Reading_Inline_Attachment_Images.slp

Oct 19, 2018 by Vidya Patil

Snap Pack History