Workflow Mail Task
The mail task is used to send email. When a process execution arrives at the mail task, the task is automatically executed. This task uses the API Server's Email Worker, which means you can generate PDFs, handle attachments and use Handlebars templating. Note that this task is not an official task of the BPMN 2.0 specification.
| Property | Description |
|---|---|
| ID | An optional unique ID for this element. The modeller will assign a random ID if left blank |
| Name | A name for this element |
| Description | An optional description for this element |
| Asynchronous | When execution reaches a task that has been marked as asynchronous the engine will commit the current transaction and schedule a background job to continue the process from the asynchronous task |
| To | A comma separated list of recipients. Can include values from stored process variables using ${form_EMAIL} (where EMAIL is the name of a field on the form that interacted with this process instance containing the user's email address) You must be confident that the variables you reference exist. If they don't, the mail task will error and no emails will be sent. This could be checked with a preceding script task, for example: if (execution.hasVariable("form_EMAIL") == false){ |
| From | The from address. Leave this blank to use the from address set in the email worker |
| Subject | The subject line of the email |
| Use Handlebars for Subject? | Check this box to enable Handlebars templating in the subject line |
| Cc | A comma separated list of recipients, works in the same way as the "To" field |
| Bcc | A comma separated list of recipients, works in the same way as the "To" field |
| Text | A text only fall-back version of the email for email clients that don't support rich content |
| HTML | The HTML content of the email, see below |
| Use Handlebars | True if checked. Handlebars templating can be used to process the body of the email |
| PDF Template | A Handlebars template used to generate a PDF attachment, see below |
| PDF Filename | The name given to the generated PDF |
| Attachments | A array of process variable names that represent attachments. See below |
| Return Variable | The process variable that any return from the activity will be stored in |
| Transient Return Variable? | If enabled, the result will be stored as a transient process variable instead of a persistent one. Transient variables are not saved to the database or process history, and are only visible until the process reaches its next wait state |
| Error Variable | The process variable that any error will be stored in |
| Error Handling | Should an error occur will it be ignored, follow the transition specified on the advanced tab (ie the ID of a sequence flow from the current activity), or throw a BPMN error which could be caught by a boundary error event |
HTML Body Content
The email generated by the mail task can include HTML content, Handlebars templating and simple value substitution.
A header and footer can be added to the email if the email header and footer process variables have been set via the Workflow Worker's configuration. See Process Variables for further information.
PDF Template
The PDF template can be used to generate a PDF version of the email (or any other content) which is automatically attached to the email generated by the mail task (in addition to any other attachments). The name of the PDF attachment is set in the PDF Filename property.
See the Email Worker documentation for further information, including how to configure PDF headers, footers and styling.
Attachments
The attachments property allows you to attach files to the generated email. It is an array of strings, with each string identifying a file. Files can be referenced in two ways: the file UUID, or the value of an upload form field.
A single explicit file identifier would be added to the attachments property as:
The values of upload form fields are added as:
You can create the array in a preceding script task, setting it as the value of a variable using
See the Handling File Uploads knowledge base article for more information about how the platform handles file uploads and File Uploads and Email Attachments in Workflow for a more detailed look at attachments.
Limits
All mail servers put limits on the total size of the emails they will accept. In AWS (our main hosting provider) the size limit is 40MB after encoding for the complete email, including embedded images and attachments.
There is also a limit of 50 recipients for a single message (combined "to", "cc" and "bcc"). When sending emails you should be emailing each recipient individually. The use cases for recipients having a message with the same message-id are limited to situations in which the recipients are expected to interact with the message as a group, for example, recipients using reply-all to the email and having a resulting email conversation.
