Mail Server Setup

Overview

Appian sends email to notify users of task assignments and various alerts. It receives email to start processes and receive process information. Process designers can also configure the Send E-Mail Smart Service to send email from a process application. Before Appian can send or receive emails, however, you must configure Appian to use your email server.

Sending emails

The initial configuration is not ready to send email. The following configuration steps are required.

Configuring Appian to send email

To configure Appian to send email:

1. Open (or create) <APPIAN_HOME>/conf/custom.properties.
2. On a new line, add the IP address, hostname, or fully qualified domain name of the SMTP server to the following setting:conf.mailhandler.mail.smtp.host=
   • If the SMTP server runs on a port other than port 25, the : format can be used to specify the port to use for that host.
   • Multiple SMTP servers can be specified using a comma-separated list. They will be tried in the order specified and mail will be sent using the first available.

For SMTP server authentication (if required) add the following properties to <APPIAN_HOME>/conf/custom.properties:

1
2
conf.mailhandler.mail.smtp.auth=true
conf.mailhandler.mail.user

Also add the following to <APPIAN_HOME>/conf/passwords.properties (create the file if not already present):

1
conf.password.SMTP

To send email over SMTPS (a Secure Sockets Layer connection) add the following properties to <APPIAN_HOME>/conf/custom.properties (create the file if not already present):

1
conf.mailhandler.mail.transport.protocol=smtps

You can enable starttls with the "smtp" protocol by adding the following property:

1
conf.mailhandler.mail.smtp.starttls.enable=true

This will cause outgoing mail to use STARTTLS if supported by the remote server but will fall back to plain smtp otherwise.

You can require starttls with the "smtp" protocol by adding the following property:

1
conf.mailhandler.mail.smtp.starttls.required=true

This will cause mail to fail if the remote server does not support STARTTLS.

Configuring a process to send email

See also: Send E-Mail Smart Service

Setting the prefix and domain for emails from processes and process models

The domain and the prefix of the email address used when the From field is set to Process or Process Model can be configured by using the following properties in custom.properties:

1
2
3
resources.appian.process.email-expressions.email.domain=your-appian-instance.com
resources.appian.process.email-expressions.email.prefix.process=process
resources.appian.process.email-expressions.email.prefix.processmodel=processmodel

See also: Custom Configurations

Available custom properties

The following custom properties can be configured in <APPIAN_HOME>/conf/custom.properties to configure sending email (inclusive of properties described elsewhere in this page).

See also: Email Alert Address for the properties for setting the sender's email address and email display name.

Receiving emails

The initial configuration is not ready to receive email. The following configuration steps are required.

Anonymous access

The Anonymous user account must be enabled to allow the receipt of email messages to start a process.

See also: Anonymous User

Public events

Public events must be enabled on the General tab of your process model's properties dialog to enable the receipt of email messages to start a process.

See also: Public Events

Configuring Appian to poll an email account

Appian does not install an email server. You must set up an email server (with unique credentials for each Appian instance) in the following manner:

1. Download a mail server (such as Apache James) and configure it to route email destined for Appian, or create an account on your existing email server to receive Appian email.
2. On the email server, create an email address for Appian to use.
3. Write down the email address for future reference. This account is used when sending email to Appian.
4. If you are migrating an existing process that receives email, create an email account for each process that needs to receive email.
5. Open <APPIAN_HOME>/conf/custom.properties and configure the following properties. Note that all properties are in the conf.mailhandler.poller namespace (e.g. conf.mailhandler.poller.EmailHandlerBean.mailServer)

Depending on the brand, version, and configuration of your mail server, one of the following username formats may be applicable: username, username@domain.tld, DOMAIN\\username, DOMAIN\\username\\mailboxname

Setting the password for the email account(s) polled by Appian is accomplished using the passwords.properties configuration file.

1. Open or create <APPIAN_HOME/conf/passwords.properties.
2. Add the property conf.password.EmailHandlerBean.EMAIL_HANDLER
3. Set the value of this property to the password corresponding to the username configured in conf.mailhandler.poller.EmailHandlerBean.userName above.

Configuring Appian to poll additional email accounts

To configure Appian to poll additional email accounts:

1. Open <APPIAN_HOME>/conf/custom.properties
2. Copy all of the properties the start with conf.mailhandler.poller.EmailHandlerBean.
3. Replace the EmailHandlerBean segment of the property names with a unique name for that email account
4. Configure the properties (mailServer, userName, etc) for the new email account
5. Add the password for the new account
   • Open or create <APPIAN_HOME>/conf/passwords.properties
   • Add the property conf.password.<mail_poller_name>.EMAIL_HANDLER, where <mail_poller_name> is replaced with the unique name from the previous step

Repeat this for each of the email accounts configured for polling.

Routing email messages

Email messages are routed to process models, processes, or events using destination key value pairs embedded within the subject or body of the email. When formatting a routing key and value, use the bracketed [key=value] format. For example:

1
[DestinationPMUUID=0006d222-3c28-8000-1944-82000]

This key/value pair routes a message to a process model with the process model UUID of 0006d222-3c28-8000-1944-82000.

The following destination keys are available:

Email routing details

If an email does not contain a proper key/value pair for routing, the message routing fails and an error message is logged.

• Mail that cannot be routed because of missing destination information is returned to the original sender.

Key/value pairs remain in the email message after it is routed to its destination.

• To exclude the routing information from the body of an email message, you can place the key/value pair in the subject line of the message.

Destination keys can only contain alpha-numeric characters and cannot begin with a numeric character.

• If a destination key begins with an invalid character, it is automatically replaced in the following manner.

If a non alpha-numeric character (such as @) appears in the destination key (after the starting character) it is replaced with an underscore character (_).

As a best practice, adhere to the following:

• Use the process model UUID instead of the process model ID for email routing.
• Unlike the process model's ID property, the process model's UUID does not change when the process model is moved to a different server.
• Email routing does not have to be reconfigured for events in process models that are exported and imported (as part of an application) when messages are routed to the event using a DestinationPMUUID key value pair.

Adding a routing alias to custom.properties

Message driven beans can use aliases for routing the email messages received. You can create aliases for process models UUIDs, process model IDs, processes, or events. Configuring an email alias is recommended when handling legacy email addresses.

To add a routing alias:

1. Open (or create) <APPIAN_HOME>/conf/custom.properties.

2. Add a custom alias definition using the following pattern.

   conf.mailhandler.alias.=

For example, with an email alias of HelpDeskRequest@mydomain.topdomain, define a process model start event target using a UUID with the following parameters.

1
conf.mailhandler.alias.HelpDeskRequest=processmodeluuid0004cedf-a045-8000-234b-c0a8031014c0

The following routing prefixes can be used when defining an alias.

• processmodeluuid
• processmodel
• process
• event

Any routing key/value pairs in email sent to an address with an alias are used for routing instead of the alias; key/value pairs are evaluated first. Alias definitions are only used when routing information is not available.

Configuring a process to receive email

See also: Start Event: Receive Message

Available custom properties

The following custom properties can be configured in <APPIAN_HOME>/conf/custom.properties to configure receiving email (inclusive of properties described elsewhere in this page).

Testing and troubleshooting

Testing the email service

To test the email service:

1. Verify that your mail server is running.

2. From a command prompt, type the following:

   1
   telnet [mail.server.name] [port#]
   

   For example, if Appian is installed on server_name.mydomain.com, and the mail server is running on port 26, you would enter the following command.

   1
   telnet server_name.mydomain.com 26
   

3. Verify the mail server is running properly. For example, for Apache James, the following reply is displayed:

   1
   220 servername SMTP Server (JAMES SMTP Server 2.2.0) ready Day, #1. Mmm yyyy hh:mm:ss -1200 (GMT-12:00)
   

4. Type the following based your email address:

   1
   EHLO myemail@mydomain.com
   

   You should receive the following reply.

   1
   250 server-name Hello youremail@yourdomain.com (connecting.machine.hostname [ip.address])
   

5. If you are using an older SMTP server version that does not support EHLO, use the HELO command.
6. Log into Appian.
7. Create a simple process that sends yourself an email.
   • See also: Send E-Mail Smart Service
8. Save, publish, and run the process.
   • If your user profile lists your correct email address, you should receive an email notification when the process completes.
9. If you do not receive the email, check the mail server log files, as well as the application server log

Troubleshooting email configuration

What if it doesn't appear to be working?

1. Connect to the email server from an email client using the credentials you've specified in custom.properties and passwords.properties.
2. Verify that the account is the one that you want to use for Appian.
3. Test this account's ability to send and receive email.
4. Note the username format and the protocol used by the email client (such as POP3 or IMAP). Use the same format and settings in your configuration.
5. If using a secure protocol, verify that the certificate presented by the email server is trusted by the JVM.

What if I send email to an Appian event and nothing happens?

The mail server might be down.

1. Verify its status and restart it if necessary.
2. Make sure that you are sending all the properties that are expected by the event and that the event is active.
3. Make sure the latest version of your process is published. If you are trying to send email to a start event, check your alerts. In some scenarios, an error alert is generated that explains the issue.
4. Double-check the email address you are using.

How can I determine whether or not emails are reaching my mail server?

Check the smtpserver.log for your mail server. This file should have an entry for every email received.

You can also check the mail-listener.log in the <APPIAN_HOME>/logs directory.

How can I determine whether my mail server is establishing a connection with Appian to receive emails?

Add the following property definition to your custom.properties file.

1
conf.mailhandler.poller.EmailHandlerBean.debug=true

Review the application server log output to confirm whether a connection is being established.

Configuring Notifications

See also: Configuring Notifications

Feedback