Email response is a new type of Action by Email. This option is different than other response types: the email recipient submits the response via email to a specific email address. Email responses from that specified email address are processed periodically for responses through cron.php.
There are two benefits of using this method.
- The email content is saved in a case variable; this allows users to add additional information to support their decision.
- An action can be taken even while offline from a mobile device, which is received by ProcessMaker after the device connectivity is restored.
Email Response has the following requirements:
- It is absolutely necessary to have the PHP Module IMAP enabled in the server instance. Therefore, Email Response reviews the content of the email that holds the response.
- It is recommended to have an email account dedicated to receive messages for all messages and actions taken by this method.
Consider the following restrictions before using Email Response:
- Only the body text is transferred to the variable. ProcessMaker ignores attachments.
- The IMAP configuration for the outgoing server is validated at the time the listener account is set up. This is an improvement that is considered for future versions.
To correctly run Email Response, please consider the following configurations:
- An email server configuration:
- SMTP - IMAP (PHPMailer)
- As of ProcessMaker 3.7.7, the Email Response allows to select settings from the email server GMAIL API SMTP - IMAP.
- As of ProcessMaker 3.7.7, the Email Response allows to select settings from the email server OFFICE 365 API SMTP-IMAP.
- Email response configuration
- Cron configuration
Configure Email Response
The Actions by Email adds a new type Email response. Follow these steps to configure email response:
Log in to ProcessMaker as an administrator or a user with the PM_FACTORY permission in their role.
Go to Designer tab.
Open a process.
The process map displays. Right click a task.
The task context menu displays. Click Properties. The Activity Properties screen displays.
In the Type field, select “Email response”.
In the Receiver account field, select the email account that will receive the response emails. The options in this field depend on the email account configured in SMTP - IMAP (PHPMailer), GMAIL API SMTP - IMAP, or OFFICE 365 API SMTP-IMAP.
In the Email account field, select the email account that sends the email. The options in this field depend on the email account configured in SMTP - IMAP (PHPMailer), GMAIL API SMTP - IMAP, or OFFICE 365 API SMTP-IMAP.
In the Sender Name field, select one of the following options:
- Previous user: The email is sent using the name of the user who completed the previous task.
Warning: It is a bad practice to select Previous user when configuring Email response because it could impersonate the configured email server. Otherwise, it displays an error message. Use Email Sender Name instead.
- Email Sender Name: The email is sent using the From Mail and From Name values defined in the email server configuration that was selected in the Email Account field.
In the Email variable field, either enter the email address of the person who will receive the email or select a variable that holds the recipient's email address. If this field is left blank, the next assigned user's email will be used by default.
In the Subject by email field, enter the text of the email's subject line. This text can include a custom variable whose content will be inserted into the subject line. This variable can come from a previous Dynaform field or be created in a trigger.
In the Email template field, select the template file used as the content of the email. Actions By Email includes a default template file named actionsByEmail.html that can be used for testing purposes. This field is required.
In the Store option in field, select the case variable where the value of the option selected by the user will be stored. This field is required.
In the Store email body in field, select the case variable where the body of the email will be stored. This field is required.
In the Register a Case Note when the recipient submits the Response checkbox, check this option to add a case note when an email response will be processed successfully.
In the Options group, add the options that will be sent to the users in the email. Each option added must have a value, which will be stored in the previous selected variable after users select one option and send the response. Each option must also have a label that will be shown to the user and can be customized with CSS code so it is easier for users to identify each option in the email.
Configure the Cron
ProcessMaker will periodically read the Action by Email receiver account inbox looking for new messages. To do this, it is required to configure a Cron task that executes the script
The location of the script depends on the ProcessMaker installation path. If ProcessMaker was installed in the
/opt/ directory in Linux, then execute:
/10 * * *according to the Crontab options.
For more information about the Cron options and how to configure the Crontab options, see Syntax of Cron Options and Configuring Crontab in Linux/UNIX.
How Email Response Works
The end user receives an email with the options provided in Email response configuration. Each option will trigger a new message email containing the following:
- Receiver: In the example below, the receiver's name is "Actions by Email Listener," which is the email account selected in the "Receiver account" drop-down defined in the task's configuration. This receiver email should not be changed by the end user because ProcessMaker will read the Inbox of that account looking for unread emails to process the user's decisions.
- Subject:It is composed by two elements:
- Case title: The case title defined in the task the email was triggered.
- Option selected: The label of the option selected by the end user.
- Body: The body must be populated with the elements below:
- User's response: By default this area is populated with 3 empty lines. However, the user might populate this section with a text. This text will be read by ProcessMaker to be stored in the variable set in "Store email body in."
- Top separator: A "/" character and 25 "=" characters.
- Instructions: A text that reads "Please add your comments above this section. Don't modify or delete this section."
- Code: An encrypted value enclosed in brackets that identifies the case and action that was taken.
- Bottom separator: 25 "=" characters and one "/" character.
Otherwise, if you try to send again a response and you previously sent a response, the following email displays:
Email Response Exceptions
ProcessMaker may fail to process the answer. In this case, it communicates to the user that the action was not successful. This feedback is delivered to the receiver account as another email as a response. The most common causes of this problem are:
- The code identifier is malformed or cannot be found.
- The case was already routed.