Introduction
The Send Email (SMTP) tool sends messages to any SMTP compliant mail server. This tool is capable of sending multiple messages in either text or HTML formats, incorporating data from Input and Format steps to any number of recipients. If recordset data being used from an Input step includes a column containing email addresses, then this can be used as a “dynamic” recipient address.
Connections to relevant SMTP servers are made globally, then available for all task steps to use.
The Send Email (SMTP) tool provides an internal address book so that common SMTP addresses can be defined and re-used. MAPI address books, such as those available from Microsoft Mail, Microsoft Outlook, and the Microsoft Exchange Server Global Address List (GAL), are also supported.
Typically, the message content is a document generated by a Format type step, such as Format as Text, Format as HTML, or Run Crystal Report, but it is also possible to attach the document to the message and additionally create fixed or dynamic message content by using columns from a consumed recordset.
Features
- Supports connections to multiple SMTP servers
- Native ESMTP client
- Configurable port selection
- Supports From, To, Cc and Bcc forms of addressing
- Static and dynamic reply address for To, Cc and Bcc recipients
- Supports HTML and text formats
- Memory features to memorise task data created at run-time
- Internal address book
- Support for MAPI address books (requires MAPI)
- Supports static and dynamic file attachments
White Paper - Send Email (SMTP)
Technical Summary
Working with other Tools
The Send Email SMTP tool can directly interact with the following tools:
Consuming from Other Tools
The Send Email SMTP tool can consume object directly outputted by the following tools:
| Icon | Tool Name | Tool Category |
|---|---|---|
 | Create Workflow Job | Format |
 | Format as Flat File | Format |
 | Format as HTML | Format |
 | Format as HTML Pro | Format |
 | Format as Text | Format |
 | Run Crystal Report | Format |
 | Run Microsoft Reporting Services | Format |
 | Run Microsoft Word (Merge) | Format |
Objects Consumed
The following objects, outputted by the above tools, can be directly consumed by the Send Email (SMTP) tool:
- Documents (Text) — Plain text documents
- Documents (HTML) — Standalone HTML pages
Exposing to Other Tools
As an Output category tool, Send Email (SMTP) does not expose any objects that can be directly consumed by another tool. However, it does expose the following objects which can be used in a task step sequence:
- DocumentSource — If a Document Source has been selected (see General tab), this contains the data in the document as recordset columns
- Step Properties — Standard step properties are available allowing you to use statistical data of the tool
Prerequisites
In order for the Send Email (SMTP) tool to function correctly, the additional third-party technologies must be in place:
- SMTP Compliant Mail Server — Compatible with ESMTP client to (RFCs 2821, 1870)
Creating the Connection to an SMTP Server
You must provide the connection details for this SMTP server:
Adding Basic Connection Details
Enter a unique Connection name. If adding connections for different types of SMTP server, it is recommended you add such details to the connection name.
In Server Address, add the DNS or IP address of the SMTP server.
If authentication is required by the SMTP server, select Enable Authentication and choose between:
- Windows Authentication (NTLM) — The currently logged-in Window’s user credentials are used to connect to the SMTP server
- Plain Text Authentication (LOGIN) — The specified Username, Password, and Domain (if required) are used to connect to the SMTP server
- Microsoft Exchange Online OAuth2 — If connecting to an Exchange Online / Exchange 365 account, use this authentication type. Enter the required Username and click Authorise. Enter the account details in the Microsoft Authorisation Console. Should OAuth2 authentication for other email providers be required, contact your Codeless Platforms account manager or partner.
- Gmail (2FA) — For GMail connections, enter the required credentials in the external Google sign-in window.
Use Test connection to ensure the credentials can be accepted.
Creating a Global Address Book
If required, you can add addresses to a global address book which can be used by any task step using this connection — click Address Book:
Click New to add new addresses. Use Edit and Delete to manage your existing email addresses.
To search for an existing entry, enter the Name into Type Name or Select from List.
If the address book from the SMTP server is available, select it from the Show Names from the drop-down.
Adding Advanced Connection Details
If Authentication has been enabled in the Main tab, you can choose to:
- Abort send if Authentication not supported by host — Emails sent by task steps using this connection are aborted if the chosen authentication method is not accepted by the SMTP server
- Abort send if Authentication fails — Emails sent by task steps using this connection are aborted if the supplied credentials, whether from the logged-in user or taken from the Authentication pane, are incorrect
Adding Secure Connection Details
If secure SMTP (SMTPS) is supported by the SMTP server, you can choose to:
- Use Secure SMTP if available — If SMTPS is not supported by the server then plain text is used instead (if allowed by the server).
- Require Secure SMTP — If SMTPS is in use, this option makes it compulsory for all emails sent. If TLS is not available, then an event is written to the Event Log instead of the email being sent.
By default, the Send Email (SMTP) tool uses Port Number 25 to communicate with the SMTP server. Amend this here as required by your SMTP server.
Changing the Message Formatting
By default, plain text emails are sent as plain text and HTML emails as HTML. If the SMTP server only accepts HTML emails, enable Send Plain Text as HTML to convert all plain text emails before sending.
Encoding the Subject Line
You can choose whether to Encode Subject field in Base64 UTF-8 Encoding. This is particularly useful if you are using a variable, recordset column, or step property to create a dynamic email subject at task run-time — if the Subject’s dynamic content contains non-Latin characters, without this parameter enabled, this will render as question marks (?).
Step Configuration
To add a new Send Email (SMTP) step to an existing task, you either:
- Click and drag the Send Email (SMTP) icon from the Task Browser to the task Design area.
- From the task’s Design tab, right-click on empty space and select New > Output > Send Email (SMTP).
– OR –
For a detailed description of how to create new tasks, refer to the product help.
About the General Tab
The General tab is used to Name and describe (Description) this task step.
- Read documents from a source — Enable this parameter if document data from a Format task step is required when creating the email
- Document Source — Contains all available documents from Format steps previously created in the task; note that the document format is displayed after the step name
About the Connection Tab
You specify the SMTP server Connection this step must use.
All connections created in the global configuration are presented here.
Alternatively, you can use a BPA Platform variable to create a dynamic connection, where the connection used is determined by runtime circumstances. At runtime, the contents of the variable must match the name of one of the Global Configuration connections — this is case-sensitive.
About the Main Tab
Use the Main tab to configure the email content and recipients.
Use Memory to memorise some or all of the step output for use in other task steps. This is particularly useful when the Send Email (SMTP) step is called multiple times — use Memory to compare the email previously processed to the new email currently being processed to avoid duplicates.
Adding the From Address
Click From to add the email address:
Use Type Name or Select from List to search for the relevant email address. If the address book from the SMTP server is available, select it from the Show Names from the drop-down to use an address from there.
If the From address is not available in the email list, you can add a One off / Dynamic Address. Enable this parameter and add the Display Name and email Address. Data source variables, recordset columns, or step properties can be dragged-and-dropped to either field to create a dynamic name or email address.
Adding Email Recipients
Click either To, Cc, or Bcc to add email recipients:
Preconfigured email addresses are shown on the left. Use Type Name or Select from List to search for the relevant email address. If the address book from the SMTP server is available, select it from the Show Names from the drop-down to use an address from there.
Highlight the relevant address and click To, Cc, or Bcc as required.
If the required address is not available in the email list, you can add a one off recipient. Click New and add the Name and email Address. Data source variables, recordset columns, or step properties can be dragged-and-dropped to either field to create a dynamic name or email address.
Alternative Method of Adding Dynamic Recipients
You can also add dynamic recipients by dragging-and-dropping data source variables, recordset columns, or step properties from the Task Browser to the relevant Message Recipients text box in the Select Recipient interface. This renders the name and address with the same dynamic value.
To change this, either double-click the new recipient or right-click on it and select Properties, and adjust the Name or Address as required:
Adding Email Attachments
To add file attachments to the email, click Attach:
To prevent duplicate attachments (those with the same filename) being sent during the same task run, enable Do not send duplicate attachments.
Click Add to add new attachments — note that files added here are not available to other Send Email (SMTP) task steps; they are for use with this step instance only. Use Edit and Remove to managed existing attachments.
Adding a Static Attachment
Static attachments are physical, existing files that do not change at task run-time — enable Static Attachment.
Use Import File to import the file into the Send Email (SMTP) task step. A copy of the file is cached into the task step so if the file is amended it in any way, those changes are not reflected in the emails sent until Update is clicked. Click Browse to locate and import the file.
Use Link to File on Disk to create a reference to the file. This is the recommended option to use as the latest version of the file is “picked up” during every task run and sent to the recipient. Click Browse to locate the file and create the reference.
In both cases, if required, you can rename the file to have a different filename when being sent from this task step — enter the new name into Attachment Name.
File properties are displayed underneath.
The Options tab allows you to decide what happens if the file cannot be found:
- Send Message Regardless — The message is sent without the attachment
- Send Message But Log Warning — The message is sent without the attachment and a warning is logged to the Event Log for the task
- Do Not Send Message and Log Error — No message is sent and an error is logged to the Event Log for the task
Adding a Dynamic Attachment
Dynamic attachments change for every task run — enable Dynamic Attachment.
Path to File On Disk works in the same way as Link to File on Disk for static attachments, but you cannot give the file a new name when sending. Click Browse to locate the file and create the reference, or use variables or recordset columns to create a dynamic file path and name.
If you have a file stored in a database table which you want to use as the attachment, enable File from Data — for example, images and PDFs. Use a Database Query step to extract the file to a recordset. Drag the recordset column containing the file to Source. Either manually create a static Name for the attachment, or use variables, recordset columns, or step properties to create a dynamic name.
If a document from a previous task step is being consumed, you can use that as the dynamic attachment — enable File From Document. Either manually create a static Name for the attachment, or use variables, formulas, recordset columns, or step properties to create a dynamic name.
The Options tab allows you to decide how to handle the attachment:
- Once to Each Mail — The attachment is added once to each email generated by the task
- Each Time Column Changes — A new attachment is created when the value of the selected field changes
- For Each Row — A new attachment is created for each new row in the recordset returned by the data source query
Adding an Email Subject
Either manually create a static Subject for the email, or use variables, recordset columns, or step properties to create a dynamic subject. If the dynamic content uses non-Latin characters, ensure you enable to Encode Subject field in Base64 UTF-8 Encoding in the global configuration. Without this parameter enabled, non-Latin characters render as question marks (?).
Defining the Email Message
You can choose whether the email body consists of:
- Message Only — Enable this option to create the email body in the space provided. Variables, recordset columns, and step properties can be dragged in to create dynamic data. If a document from a previous task step is being consumed , this can be used as an attachment.
- Document Output — If a document from a previous task step is being consumed, enable this option to use the consumed document as the email body. Note that this does not allow you to add extra text to the email body, however separate files can be added as attachments.
About the Options Tab
The Options tab allows you to define how errors in this step are handled at task runtime.
If an error occurs, you can decide whether the step should Continue processing, or terminate the step immediately (Abort Step).
If the step is aborted, you can choose to Continue processing onto the next step in the task, or terminate the whole task immediately (Abort Task).
You can Request a delivery receipt for each message sent, however this is dependant on the recipient’s mailbox settings as to whether a receipt is sent.
By default warnings are logged in the Event Log for any emails where the CC or BCC fields contain NULL or blank values passed in at runtime. Selection of the Do not log zero-length recipients as warnings option will prevent these warnings being logged.
The Skip sending attachment if “File from Data” source is null or empty option prevents the sending of Dynamic Attachments if the File from Data option has been selected and the Source is null or empty. See Adding a Dynamic Attachment
