Overview
The Receive Mail Task can be used to perform functions related to the reception and management of email. POP3, IMAP and Exchange email servers are supported. The task can handle email attachments as well as the emails themselves.
The task can also verify email signatures and decrypt encrypted emails and attachments using the S/MIME standard. Emails and attachments encrypted using the PGP standard can be handled by combining the email-handling functions of this task with the decryption capabilities of the COZYROC OpenPGP task.
Four actions are available within this task:
-
Parameters Description MailConnection This parameter is used to specify the connection manager for the email server. The types of connection managers that may be used for this parameter are IMAP, Exchange, and POP3.
Filter, IsFilterVariable, FilterVariable These parameters are used to specify the filter criteria to apply against the list of emails.
For IMAP, use an IMAP SEARCH COMMAND expression, described in IETF RFC 1730.
For Exchange, use an Exchange AQS expression.
For POP3, use a FLEE expression. The following elements may be specified: ID, Date, Size, From, To, CC, ReplyTo, Subject, BodyText, BodyHtml, and HasAttachments.
Use the Filter parameter to specify the filter string.
If you prefer to use a variable so that the filter can be modified at runtime, then set IsFilterVariable parameter to True and set FilterVariable parameter to the variable containing the filter criteria. Click on the orange “Expand Options” button to display these parameters.
ResultVariable Use this parameter to specify the variable where you would like the list of emails to be stored for subsequent use.
-
Parameters Description MailConnection This parameter is used to specify the connection manager for the email server. The types of connection managers that may be used for this parameter are IMAP, Exchange, and POP3.
MailVariable This parameter specifies the variable containing the email message. You can select a variable containing either a list of messages or a single message.
Local, IsLocalVariable, LocalVariable These parameters are used to specify where to place each email as it is downloaded. One email is downloaded each time the task is executed with the "Get mail" action. Hence, to download all emails from a list, perform the "Get mail" action within a loop to download multiple emails.
Use the Local parameter to specify the connection manager containing the path and filename information. The types of connection managers that may be used for this parameter are File and Flatfile.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsLocalVariable parameter to True and set LocalVariable parameter to the variable containing the path and filename for where to place the email.
If you want to save the contents of each of the emails and not overwrite the previous one on each iteration through the loop, use the LocalVariable parameter to specify a different path and filename for each email on each iteration through the loop. You must also set the OverwriteExisting parameter to False.
OverwriteExisting If you do not need to save the contents of each email and it is acceptable to overwrite the contents each time through the loop, then set this parameter to True.
If you want to save the contents of each of the emails and not overwrite them on each iteration through the loop, set this parameter to False and ensure that a new path and filename are specified in the LocalVariable parameter each time through the loop.
If an existing local file exists in the specified location, it will not be overwritten by the received email and a warning message will be generated in the log file.
-
Parameters Description Local, IsLocalVariable, LocalVariable These parameters are used to specify where to find the email to open. Make sure the email has already been downloaded before using this action. One email is opened each time the task is executed with the "Open mail" action.
To open multiple emails from a list, use the "Get mail" action and the "Open mail" action in a loop with the "Get mail" action preceding the "Open mail" action.
Use the Local parameter to specify the connection manager containing the path and filename information for the location of the email to be opened. The types of connection managers that may be used for this parameter are File and Flatfile.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsLocalVariable parameter to True and set LocalVariable parameter to the variable containing the path and filename for where to find the email to be opened.
Sender, IsSenderVariable, SenderVariable These parameters are used to specify the path and filename for where the sender’s email address should be placed.
Use the Sender parameter to specify the connection manager containing the path and filename information for the file where the sender of the email should be placed. The types of connection managers that may be used for this parameter are File and Flatfile.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsSenderVariable parameter to True and set SenderVariable parameter to the variable containing the path and filename for the file in which to store the sender of the email.Date, IsDateVariable, DateVariable These parameters are used to specify the path and filename for where the date of the email should be placed.
Use the Date parameter to specify the connection manager containing the path and filename information for the file where the date of the email should be placed. The types of connection managers that may be used for this parameter are File and Flatfile.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsDateVariable parameter to True and set DateVariable parameter to the variable containing the path and filename for the file in which to store the date of the email.
Subject, IsSubjectVariable, SubjectVariable These parameters are used to specify the path and filename for where the subject of the email should be placed.
Use the Subject parameter to specify the connection manager containing the path and filename information for the file where the subject of the email should be placed. The types of connection managers that may be used for this parameter are File and Flatfile.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsSubjectVariable parameter to True and set SubjectVariable parameter to the variable containing the path and filename for the file in which to store the subject of the email.
BodyText, IsBodyTextVariable, BodyTextVariable These parameters are used to specify the path and filename for where the text of the body of the email should be placed.
Use the BodyText parameter to specify the connection manager containing the path and filename information for the file where the text of the body of the email should be placed. The types of connection managers that may be used for this parameter are File and Flatfile.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsBodyTextVariable parameter to True and set BodyTextVariable parameter to the variable containing the path and filename for the file in which to store the text of the body of the email.
BodyHtml, IsBodyHtmlVariable, BodyHtmlVariable These parameters are used to specify the path and filename for where the HTML of the body of the email should be placed.
Use the BodyHtml parameter to specify the connection manager containing the path and filename information for the file where the HTML of the body of the email should be placed. The types of connection managers that may be used for this parameter are File and Flatfile.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsBodyHtmlVariable parameter to True and set BodyHtmlVariable parameter to the variable containing the path and filename for the file in which to store the HTML of the body of the email.
Attachment, IsAttachmentVariable, AttachmentVariable These parameters are used to specify the path of the folder where the email attachment(s) should be placed.
Use the Attachment parameter to specify the connection manager containing the path information for the folder where the email attachment(s) should be placed. Only a File connection manager may be used for this parameter.
If you prefer to use a variable so that the path can be modified at runtime, then set IsAttachmentVariable parameter to True and set AttachmentVariable parameter to the variable containing the path for the folder in which to store the email attachment(s).
Decrypt This parameter is used to specify whether the email (and attachments) should be decrypted. Set this parameter to True if the email and any attachments were encrypted using the S/MIME standard. If the parameter is set to True, another set of parameters will be displayed.
See the PrivateKey, IsPrivateKeyVariable, PrivateKeyVariable and Password parameters below if you have set this parameter to True.
If you do not need to decrypt the email and attachments or they are encrypted with a different standard, then set this parameter to False.
PrivateKey, IsPrivateKeyVariable, PrivateKeyVariable, Password These parameters are only displayed if you have set the Decrypt parameter to True. They are used to point at the S/MIME private key for decrypting the email (and attachments, if applicable).
Use the PrivateKey parameter to specify the connection manager that points at the private key. Only a File connection manager may be used for this parameter.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsPrivateKeyVariable parameter to True and set PrivateKeyVariable parameter to the variable containing the path and filename for the location of the private key.
Use the Password parameter to specify the private key password.
VerifySignature The VerifySignature parameter is used to indicate whether or not to verify the signature on the email. If the parameter is set to True, another set of parameters will be displayed.
See the Certificate, IsCertificateVariable, and CertificateVariable parameters below if you have set this parameter to True.
If you do not want to verify the signature, set the VerifySignature parameter to False.
Certificate, IsCertificateVariable, CertificateVariable These parameters are only displayed if you have set the VerifySignature parameter to True. They are used to point to the S/MIME certificate which should be used to verify the signature.
Use the Certificate parameter to specify the connection manager that points at the certificate. Only a File connection manager may be used for this parameter.
If you prefer to use a variable so that the path and filename can be modified at runtime, then set IsCertificateVariable parameter to True and set CertificateVariable parameter to the variable containing the path and filename for the location of the certificate.
-
Parameters Description MailConnection This parameter is used to specify the connection manager for the email server. The types of connection managers that may be used for this parameter are IMAP, Exchange, and POP3.
MailVariable This parameter specifies the variable containing the email message. You can select a variable containing either a list of messages or a single message.
In order to download and process emails, the first step is always to get a list of the emails using the "Get mail list" action. Criteria may be applied to filter the emails that will be included in the list. Where the filtering will take place (ie. client or server) is dependent on the type of email server being used.
Filtering for a POP3 mail server is done on the client side. If you need to filter based on characters in the body of the email, the entire body of the email must be downloaded so that the filter can be applied. The same applies to filtering on characters in email attachments. If you can filter based only on the information in the header, the entire email message and/or attachment will not be downloaded, thus resulting in better performance.
Filtering for IMAP and Exchange mail servers is done on the server side so performance is not affected by filtering based on text in the body or in attachments.
When you use the "Get mail", "Open mail" and "Delete mail" actions, the task will process one email each time it is executed. Therefore, to process multiple emails from a list, use an instance of the task to create the list first and then place an instance (or instances) of the task within a loop to perform the desired action(s) on each email.
If you would like to download and open emails, set up an instance of the task for each of the following steps:
- Get a list of the emails to be downloaded using the "Get mail list" action.
- Download the emails using the "Get mail" action from within a loop.
- Open the emails using the "Open mail" action from within a loop.
If you would like to delete emails, set up an instance of the task for each of the following steps:
- Get a list of the emails to be deleted using the "Get mail list" action.
- Delete the emails using the "Delete mail" action from within a loop.
Demonstration
Parameters
General
Specify the task name.
Specify the task description.
Specify whether or not the Receive Mail Task terminates if the chosen action fails.
Specify the task action. This parameter has the options listed in the following table.
Option Description Get mail Downloads mail to a local file. Selecting this action displays the dynamic parameters IsLocalVariable, Local, LocalVariable, OverwriteExisting, MailConnection, MailVariable. Open mail Opens the mail file. Selecting this action displays the dynamic parameters IsLocalVariable, Local, LocalVariable, Decrypt, VerifySignature, IsSenderVariable, Sender, SenderVariable, IsDateVariable, Date, DateVariable, IsSubjectVariable, Subject, SubjectVariable, IsBodyTextVariable, BodyText, BodyTextVariable, IsBodyHtmlVariable, BodyHtml, BodyHtmlVariable, IsAttachmentVariable, Attachment, AttachmentVariable. Delete mail Deletes the mail. Selecting this action displays the dynamic parameters MailConnection, MailVariable. Get mail list Gets a list of e-mails. Selecting this action displays the dynamic parameters ResultVariable, MailConnection, IsFilterVariable, Filter, FilterVariable. Indicate whether or not the local path is stored in a variable. This parameter has the options listed in the following table.
Option Description True The local path is stored in a variable. Selecting this option displays the dynamic parameter LocalVariable. False The local path is specified in a File connection manager. Selecting this option displays the dynamic parameter Local. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Specify whether or not an existing local file can be overwritten with the received mail. This parameter has the options listed in the following table.
Option Description True If an existing local file exists, it will be overwritten by the received mail. False If an existing local file exists, it will not be overwritten by the received mail and a warning message will be generated in the log file. Select an existing connection manager, or click <New connection...> to create a new connection manager.
Related Topics: IMAP Connection Manager, Exchange Connection Manager 1.6, POP3 Connection Manager
Mail information object. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Indicate whether or not the mail must be decrypted. This parameter has the options listed in the following table.
Option Description True The mail must be decrypted. Selecting this option displays the dynamic parameters IsPrivateKeyVariable, PrivateKey, PrivateKeyVariable, Password. False The mail is not encrypted so it need not be decrypted. Indicate whether the file path of the private key is stored in a variable. This parameter has the options listed in the following table.
Option Description True The file path of the private key is stored in a variable. Selecting this option displays the dynamic parameter PrivateKeyVariable. False The file path of the private key is specified in a File connection manager. Selecting this option displays the dynamic parameter PrivateKey. Specify the File connection manager where the file path of the private key is specified. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Specify the variable where the file path of the private key is specified. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Specify the private key password.
Indicate whether or not the mail signature must be verified. This parameter has the options listed in the following table.
Option Description True Verify the mail signature. Selecting this option displays the dynamic parameters , IsCertificateVariable, Certificate, CertificateVariable. False Do not verify the mail signature. Indicate whether or not the file path of the certificate is stored in a variable. This parameter has the options listed in the following table.
Option Description True The file path of the certificate is stored in a variable. Selecting this option displays the dynamic parameter CertificateVariable. False The file path of the certificate is specified in a File connection manager. Selecting this option displays the dynamic parameter Certificate. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Indicate whether or not the sender of the mail should be stored in a variable. This parameter has the options listed in the following table.
Option Description True The sender of the mail should be stored in a variable. Selecting this option displays the dynamic parameter SenderVariable. False The sender of the mail should be stored in a file and is specified in a File connection manager. Selecting this option displays the dynamic parameter Sender. Specify the file where the sender of the mail should be stored. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Specify the variable where the sender of the mail should be stored. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Indicate whether or not the origination date of the mail should be stored in a variable. This parameter has the options listed in the following table.
Option Description True The origination date of the mail should be stored in a variable. Selecting this option displays the dynamic parameter DateVariable. False The origination date of the mail should be stored in a file and is specified in a File connection manager. Selecting this option displays the dynamic parameter Date. Specify the file in which the origination date of the mail should be stored. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Specify the variable in which the origination date of the mail should be stored. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Indicate whether or not the subject line of the mail should be stored in a variable. This parameter has the options listed in the following table.
Option Description True The subject line of the mail should be stored in a variable. Selecting this option displays the dynamic parameter SubjectVariable. False The subject line of the mail should be stored in a file and is specified in a File connection manager. Selecting this option displays the dynamic parameter Subject. Specify the file in which the subject line of the mail should be stored. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Specify the variable in which the subject line of the the mail should be stored. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Indicate whether or not the text of the body of the mail should be stored in a variable. This parameter has the options listed in the following table.
Option Description True The text of the body of the mail should be stored in a variable. Selecting this option displays the dynamic parameter BodyTextVariable. False The text of the body of the mail should be stored in a file and is specified in a File connection manager. Selecting this option displays the dynamic parameter BodyText. Specify the file in which the text of the body of the mail should be stored. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Specify the variable in which the text of the body of the mail should be stored. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Indicate whether or not the HTML of the body of the mail should be stored in a variable. This parameter has the options listed in the following table.
Option Description True The HTML of the body of the mail should be stored in a variable. Selecting this option displays the dynamic parameter BodyHtmlVariable. False The HTML of the body of the mail should be stored in a file and is specified in a File connection manager. Selecting this option displays the dynamic parameter BodyHtml. Specify the file where the HTML of the body of the mail should be stored. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Specify the variable where the HTML of the body of the mail should be stored. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Indicate whether or not the mail attachments folder is stored in a variable. This parameter has the options listed in the following table.
Option Description True The mail attachments folder should be stored in a variable. Selecting this option displays the dynamic parameter AttachmentVariable. False The mail attachments folder should be specified in a File connection manager. Selecting this option displays the dynamic parameter Attachment. Specify the File connection manager in which the mail attachments folder should be specified. Select an existing File connection manager, or click <New connection...> to create a new connection manager.
Related topics: File Connection Manager Editor
Specify the variable in which the mail attachments folder should be specified. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Specify the variable where the returned list of mail should be stored. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Indicate whether the mail filter criteria is stored in a variable. This parameter has the options listed in the following table.
Option Description True The mail filter criteria is stored in a variable. Selecting this option displays the dynamic parameter FilterVariable. False The mail filter criteria is directly specified. Selecting this option displays the dynamic parameter Filter. Specify the mail filter criteria. The filter expression for each connection type is as follows:
Connection Description POP3 FLEE expression. You can use the following elements: ID, Date, Size, From, To, CC, ReplyTo, Subject, BodyText, BodyHtml, HasAttachments.
For example, to get all e-mails after 10 Sep 2009 containing "data" in the subject line, use the following expression: Date > #09/10/2009# and Subject.Contains("data")
Note: Because the filter process is done on the client side, be careful what elements you use in your expressions. Using BodyText, BodyHtml and HasAttachments elements will require complete mail retrieval.
IMAP IMAP SEARCH COMMAND expression. EXCHANGE 1.6 Exchange AQS expression. Specify the variable in which the mail filter criteria is stored. Select an existing user-defined variable, or click <New variable...> to create a new variable.
Related Topics: Integration Services Variables, Add Variable
Knowledge Base
- Where can I find the documentation for the Receive Mail Task?
- Error Message: 'ProtocolVersion' has been reported by the remote connection end
- How can I get the Mail ID from an email?
- How to connect to a Shared Mailbox?
- FLEE Expressions for filtering
Related scripts
What's New
- Fixed: 'Get mail list' action failed when using with Exchange connection (Thank you, Cesar).
- Fixed: 'Get mail list' action failed when using with POP3 connection (Thank you, Marvin).
- New: The result returned from 'Get mail list' action can now be iterated using the standard 'Foreach ADO Enumerator'.
- Fixed: Failed to process email containing attachments with invalid date metadata (Thank you, Aaron).
- Fixed: Failed to extract properly Unicode text attachments (Thank you, Patrick).
- New: New parameters Sender and Date to extract email sender and origination date.
- New: Introduced task.
COZYROC SSIS+ Components Suite is free for testing in your development environment.
A licensed version can be deployed on-premises, on Azure-SSIS IR and on COZYROC Cloud.