Overview

ProcessMaker can be configured to send out email to keep its users apprised of new cases in their Inbox and notify them at specified times while running cases. From version 3.0, it is possible to create and configure more than one server to send out these emails. This page explains the settings to configure ProcessMaker to use the email servers.

It's necessary to configure the email servers in order to use the following components.

  • Tasks: To automatically email an user when assigned to a case.
  • Events: Send Message Events, to email users at particular times during the course of a case.
  • Conditional notification with the PMFSendMessage() function in a trigger.
  • Case Notes: to send comments an information about cases.

Note: The email settings have been tested with Gmail, Yahoo and Hotmail services. It is not recommended to use Office 365, since it has not been tested and some configurations may not work properly.

Creating New Email Server Configurations

To allow ProcessMaker to send out email notifications, login to ProcessMaker with a user, such as the "admin" user, who has the PM_SETUP permission in his/her role.

Then, go to ADMIN > Settings > Email Servers and, if it's the first time configuring the email servers, select the only item listed in the page that opens. This item represents an email server which is not configured yet and it's called "MAIL".

Click on "Edit" to edit the configuration of this email server:

Available Version: ProcessMaker Enterprise 3.0.x on.

To add more than one email server in ProcessMaker click on "New"

The configuration window of the email servers is opened. Fill in the corresponding fields to configure the email server (check the section below to learn how to do it).

Email Server Configuration

In the window that opens, first define the email engine that will be used by the email server configured in the "Email Engine" dropdown.

  • SMTP (PHPMailer)

    This option sends email using the PHPMailer program. Select this option to use an email server which supports the Simple Mail Transport Protocol (SMTP). If your organization does not have its own email server (such as sendmail, postfix, or exim), use an external email service (such as Gmail, Yahoo or Hotmail) which supports SMTP. If using an external email service, check the configuration information below for Hotmail, Yahoo or Gmail, or see this list for the SMTP configuration of other email providers.

  • Mail (PHP)

    Select this option to use PHP's mail() function to send the email via the Mail Transfer Agent (MTA), such as SendMail, Postfix or Exim, which is installed and configured on the same server where ProcessMaker is installed. Make sure that the php.ini file on the server is configured to use the MTA. If unable to deliver mail, check the sendmail_path setting. If using a Windows server, it may be necessary to change the SMTP and stmp_port settings.

SMTP (PHP Mailer)

If this option has been selected in the "Email Engine" option, fill in the following fields:

Where:

  • Server: The IP address or domain name for the email server. For example, "smtp.gmail.com", "smtp.mail.yahoo.com" or "smtp.example.com".
  • Port (default 25): The port number used by the email server. Generally port 25 is used, or alternatively port 587. If connecting to the email server with a SSL or TLS connection, generally port 465 is used. If left blank, the default port 25 will be used. (See also the corresponding settings by email provider.)

    Note: Make sure that a firewall is not blocking this port on your ProcessMaker server.

  • Require Authentication: Check this option to enable authentication. When checked, the Password field is displayed.
    • Password
    • The password for the user account.
  • Account From: The name of the user account from which emails are sent. Some email servers, such as gmail, require that the account name include the full email address, such as: johndoe@gmail.com
  • From Mail: Mail account with which the email notifications will be sent.
  • From Name:Set the name, from which emails are sent, such as "My Company Admin". If left blank, then emails will be sent from "ProcessMaker" by default.
  • Use Secure Connection: Select whether the email requires a secure connection:
  • Send a test mail: Check this option to send a test mail. When checked, it displays the Mail to field.

    • Mail to: Email account to which the "test mail" will be sent.
  • Set as default configuration:

    Available Version: 3.0. Set this email server as default.

Mail (PHP)

If using Mail (PHP) option, no configuration information needs to be entered, except the type of secure connection.

  • From Mail The email account with which the email notifications will be sent.
  • From Name: Set the name, from which emails are sent, such as "My Company Admin". If left blank, then emails will be sent from "ProcessMaker" by default.
  • Send a test mail: Check this option to send a test mail. When checked, it displays the Mail to field.

    • Mail to: Email account to which the "test mail" will be sent.

Testing the Email Configuration

After filling in the email settings, click on the "Test" button to test the email configuration.

If an error message in red appears, then try different settings and test again.

If the "Send a test mail" option was selected, an email should arrive from "Process Maker OS":

Once all the tests pass, click on the "Save Changes" button to save the email configuration.

Note: Take into account that when using the same email account in the Account From field of the email server in ProcessMaker, but using different From Email accounts, the from account send in the emails will always be the account set in the Account From field. The account set in the From Email field will be sent as the reply-to.

Managing the Email Servers

All email servers created will be listed in "Admin > Settings > Email Servers" as they are created. The characteristics of this list are the following:

  • Email Engine: Type of email engine used in the email server configuration. The two options are "PHPMAILER" and "MAIL"
  • Server: The IP address or domain name for the email server.
  • Port: The port number used by the email server.
  • Account From: The name of the user account set from which emails will be sent.
  • From Email: The email address from which the emails will be sent.
  • From Name: Name from which emails will be sent.
  • Use Secure Connection: If either "TLS" or "SSL" was used they will be shown in this column. In case a secure connection was not used in the email server configuration "No" will be shown.
  • Mail To: The email account to which the test mail was sent.
  • Default: Indicates whether the email configuration is set as default (with a green check) or not (empty).

To edit the configuration of an already created email server first select it and click on "Edit".

To delete a server from the list, select it and click on "Delete" in the menu.

Click on "Yes" in the window that opens to delete the email server selected. Click on "No" to close the window without deleting the email server.

The email server set as default can not be deleted, in that case an error message is shown:

All email servers created in ProcessMaker are stored in the table EMAIL_SERVER of the ProcessMaker database wf_<workflow> with the same information with which they were created using the interface. Each one of them has a unique 32-character UID to identify them.

Some Settings of Common Email Providers

Below there is the description of how to set the email server of four of the most common email providers: Gmail, Yahoo, Hotmail and Outlook.

Email Configuration for Gmail

  • Email Engine: SMTP (PHPMailer)
  • Server: smtp.gmail.com
  • Port: 587
  • Require authentication:
  • Account From: account_name@gmail.com or account_name@company_name.com
  • Password: account_password
  • Use Secure Connection: TLS

Note: In order to save a copy of outgoing emails in the Sent folder of a Gmail account, IMAP needs to be enabled:

  • Sign in to Gmail
  • Click the gear icon in the top right.
  • Select Settings.

  • Click Forwarding and POP/IMAP.
  • Select Enable IMAP.
  • Click Save Changes.

Note: If there is a problem connecting with your gmail account, you probably need to Allow the access to your Google account by accessing this link in the same browser where you have your account session logged in.

Note: If using a 2-Step Verification, the ProcessMaker connection can't be performed correctly.

Email Configuration for Yahoo!

Normal email account:

  • Email Engine: SMTP (PHPMailer)
  • Server: smtp.mail.yahoo.com
  • Port: 465 or 587
  • Require authentication:
  • Account From: account_name@yahoo.com
  • Password: account_password
  • Use Secure Connection: SSL

Note: Yahoo limits accounts to 500 emails per day and emails can only be addressed to a maximum of 100 recipients.

Business email account:

  • Email Engine: SMTP (PHPMailer)
  • Server: smtp.bizmail.yahoo.com
  • Port: 465
  • Require authentication:
  • Account From: account_name@company_name.com
  • Password: account_password
  • Use Secure Connection: SSL

Email Configuration for HotMail

  • Email Engine: SMTP (PHPMailer)
  • Server: smtp.live.com
  • Port: 25 or 587
  • Require authentication:
  • Account From: account_name@hotmail.com
  • Password: account_password
  • Use Secure Connection: TLS

Note: Hotmail accounts are limited to a maximum of 300 messages per day and up to 100 recipients per message.

Email Configuration for Outlook

Settings for Outlook accounts:

  • Email Engine: SMTP (PHPMailer)
  • Server: smtp-mail.outlook.com
  • Port: 25 or 587
  • Require authentication:
  • Account From: account_name@hotmail.com
  • Password: account_password
  • Use Secure Connection: TLS

Checking the Email Configuration

To make sure that ProcessMaker is properly configured to connect to an email server, go to ADMIN > Settings > Email Servers and send a test email. If ProcessMaker is unable to connect to the email server, check the address, port number and firewall.

Check the Address

If the test email fails, then first verify that the ProcessMaker server can address the email server. Go to the command line of the ProcessMaker server and issue a ping. (Use CTL+C to stop the pings.)

For example:

ping smtp.mail.yahoo.com
PING smtp.mail.us.am0.yahoodns.net (98.138.84.55) 56(84) bytes of data.
64 bytes from vcs-s-myc.mail.vip.ne1.yahoo.com (98.138.84.55): icmp_req=1 ttl=48 time=210 ms
64 bytes from vcs-s-myc.mail.vip.ne1.yahoo.com (98.138.84.55): icmp_req=2 ttl=49 time=189 ms
64 bytes from vcs-s-myc.mail.vip.ne1.yahoo.com (98.138.84.55): icmp_req=3 ttl=48 time=210 ms
64 bytes from vcs-s-myc.mail.vip.ne1.yahoo.com (98.138.84.55): icmp_req=4 ttl=48 time=215 ms

--- smtp.mail.us.am0.yahoodns.net ping statistics ---
5 packets transmitted, 4 received, 20% packet loss, time 4001ms
rtt min/avg/max/mdev = 189.429/206.650/215.775/10.173 ms

Note: Some systems may block the IMCP packets used by ping, so the email server may be operating even if the ping fails.

Check the Ports

Then, check which ports are being used by the email server with a tool such as Nmap which shows which ports are being used.

For example, to check which ports are used by smtp.mail.yahoo.com:

nmap smtp.mail.yahoo.com
Starting Nmap 5.21 ( http://nmap.org ) at 2012-03-26 12:55 BOT
Nmap scan report for smtp.mail.yahoo.com (98.139.212.139)
Host is up (0.16s latency).
Hostname smtp.mail.yahoo.com resolves to 3 IPs. Only scanned 98.139.212.139
rDNS record for 98.139.212.139: vcs-s-myc.mail.vip.bf1.yahoo.com
Not shown: 996 filtered ports
PORT    STATE  SERVICE
<font color="green">25/tcp  open   smtp</font>
80/tcp  closed http
<font color="green">465/tcp open   smtps</font>
993/tcp closed imaps

Nmap done: 1 IP address (1 host up) scanned in 11.38 seconds

In this case, smtp.mail.yahoo.com is using port 25 for email and port 465 for email with a secure connection.

To check which ports are being used by the local machine, use netstat -tanp in Linux/UNIX or netstat -anb in Windows.

For example, to figure out which port is being used by the EXIM mail server on the local machine:

netstat -tanp
Active Internet connections (servers and established)
Proto Recv-Q Send-Q Local Address           Foreign Address         State       PID/Program name
tcp        0      0 127.0.0.1:631           0.0.0.0:*               LISTEN      1596/cupsd      
tcp        0      0 0.0.0.0:45367           0.0.0.0:*               LISTEN      1113/rpc.statd  
<font color="green">tcp        0      0 127.0.0.1:25            0.0.0.0:*               LISTEN      2269/exim4</font>      
tcp        0      0 127.0.0.1:3306          0.0.0.0:*               LISTEN      1872/mysqld
tcp        0      0 127.0.0.1:80            0.0.0.0:*               LISTEN      1464/apache2    
tcp        0      0 0.0.0.0:111             0.0.0.0:*               LISTEN      1098/rpcbind    
tcp        0      0 127.0.0.1:7634          0.0.0.0:*               LISTEN      1654/hddtemp

Check the Firewall

If the test email fails, then make sure that no firewall is blocking the port used by the email server.

Linux/UNIX:

To see which ports are open, use the netstat command as shown above. To check the status of iptables, use the command: iptables -L -n -v

For example, the following output indicates that iptables isn't configured, so no traffic should be blocked:

iptables -L -n -v
Chain INPUT (policy ACCEPT 3951 packets, 2148K bytes)
 pkts bytes target     prot opt in     out     source               destination        

Chain FORWARD (policy ACCEPT 0 packets, 0 bytes)
 pkts bytes target     prot opt in     out     source               destination        

Chain OUTPUT (policy ACCEPT 4007 packets, 517K bytes)
 pkts bytes target     prot opt in     out     source               destination  

Windows:

To see which ports are open, use the netstat command as shown above.

To check the status of the Windows firewall:

In Windows XP/2003/Vista, use the command: netsh firewall show state
In Windows 7/2008, use the command: netsh advfirewall firewall

Note: The command is not available in Window 7, check this response in this forum to learn a way to view the ports.

Sending Emails from Different Server and User Accounts

By default all emails are sent out by the email server and user account which is configured under ADMIN > Settings > Email. In some processes, however, it may be appropriate to send emails from a different email server and/or user account. In version 2.8.0 and later, the config parameter has been added to the PMFSendMessage() function, to allow emails to be sent out with a different email server and/or user account.

To create a trigger which sends out an email from a custom email server and/or user account, go to DESIGNER and open a process for editing. Then, go to the Triggers tab and click on New. Then select ProcessMaker Functions and click on the PMFSendMessage() in the list:

See the documentation for this function. The parameter to configure an alternative email server is the last parameter for the function.

The function definition for PMFSendMessage():

    int PMFSendMessage(string caseId, string from, string to, string cc, string bcc,string subject, string template, array aFields=array(), array aAttachments=array(), boolean showMessage=true, int delIndex=0, array config=array())

To use an alternative email server and/or user account, the config parameter of PMFSendMessage() should be set to an associative array with the following values as the keys:

  • MESS_ENGINE: Select the email engine which will be used to send out emails. Possible values include:
    • "PHPMAILER": This option sends email using the PHPMailer program, which is recommended if using an external email service (such as Yahoo!, gmail, hotmail, etc.) or if the server running ProcessMaker is not configured to use a Mail Transfer Agent (such as SendMail, Postfix, exim, etc.).
    • "MAIL": This option uses PHP's mail() function to send the email, which means that the server running ProcessMaker should have a Mail Transfer Agent (such as SendMail, Postfix, Exim, etc.) and PHP should be configured to use it. If this option is used, then the MESS_SERVER, MESS_PORT and SMTPSecure parameters are ignored.
  • MESS_SERVER: The IP address or domain name for the email server. For example, "smtp.live.com" or "smtp.example.com".
  • MESS_PORT: The port number used by the email server. Generally port 25 is used, or alternatively port 587. If connecting to the email server with a SSL or TLS connection, generally port 465 is used.
  • MESS_ACCOUNT: The name which will be included in the From field of the message. It can be an email address, such as "johndoe@example.com", or a name, such as "John Doe" or "Acme Inc.". This value depends upon the email provider. For example, the gmail email server always uses an email address in this field. If this field is an email address, the MESS_FROM_MAIL parameter is ignored, but if it is a name, MESS_FROM_MAIL should be set to a valid email account.
  • MESS_FROM_MAIL: If MESS_ACCOUNT is set to a name, set this to the email address from which the notification will be send, such as: "johndoe@example.com"
  • MESS_RAUTH: Set to 1 if the server requires authentication, meaning that a password is required; otherwise, set it to 0.
  • MESS_PASSWORD: The password for the user account.
  • SMTPSecure: Select whether the email requires a secure connection:

Emailing members of a Group

In this example, the members of a group named "Employees" will receive emails from a gmail account, which is specified in the associative array $serverConfig which is passed to the config parameter of PMFSendMessage():

$groupName = 'Employees';  
$query = "SELECT DISTINCT GU.USR_UID FROM CONTENT AS C, GROUP_USER AS GU WHERE " .
   "C.CON_CATEGORY='GRP_TITLE' AND C.CON_VALUE='$groupName' AND C.CON_ID=GU.GRP_UID";
$result = executeQuery($query);
if (!is_array($result) or count($result) < 1) {
  $g = new G();
  $g->SendMessageText("Unable to find any users in group '$groupName'.", "WARNING");
}
else {
   $to = '';
   foreach ($result as $record) {
      $aInfo = userInfo($record['USR_UID']);
      if (empty($to))
         $to = $aInfo['mail'];
      else
         $to .= ', ' . $aInfo['mail'];
   }
   $serverConfig = array("MESS_ENGINE"=>"PHPMAILER", "MESS_SERVER"=>"smtp.gmail.com", "MESS_PORT"=>465,
      "MESS_ACCOUNT"=>"manager@company.com","MESS_FROM_MAIL"=>"", "MESS_PASSWORD"=>"xxxxxx",
      "SMTPSecure"=>"tls", "MESS_RAUTH" =>1);
   PMFSendMessage(@@APPLICATION,'manager@company.com', $to, '', '', 'Expenses for Project',
      'projectExpenses.html', array(), array(), true, 0, $serverConfig);
}