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.
The initial configuration is not ready to send email. The following configuration steps are required.
Appian Cloud supports routing outbound e-mail over a VPN tunnel. A VPN tunnel configured between an Appian Cloud instance and SMTP server is required. For assistance in setting up secure outbound e-mail, contact Appian Support.
To configure Appian to send email:
For SMTP server authentication (if required) add the following properties to
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):
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):
You can enable starttls with the "smtp" protocol by adding the following property:
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:
This will cause mail to fail if the remote server does not support STARTTLS.
The default SMTP timeout value for email messages sent from the Appian platform is 10 minutes, which is the recommended value per SMTP standards. If for some reason you need to update this value, please contact Appian Support.
See also: Send E-Mail Smart Service
The domain and the prefix of the email address used when the From field is set to
Process Model can be configured by using the following properties in
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
||Refers to the domain part of the email address (the part after the
||Refers to the prefix prepended to the ID of the process from which the email is sent.|
||Refers to the prefix prepended to the ID of the process model from which the email is sent.|
See also: Custom Configurations
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).
||The designated host name of the email sender. List the port number if your SMTP server isn't running on port 25.|
||The default email address a site will use to send notifications. Note that this will also be the default value of the
||The username of the account used to connect to the email server. Only used when
NOTE: This property must be configued in
|The password of the account used to connect to the email server. Only used when
||This property (together with
||The default setting is taken from your
||The default setting is taken from your
See also: Email Alert Address for the properties for setting the sender's email address and email display name.
The initial configuration is not ready to receive email. The following configuration steps are required:
The Anonymous user account must be enabled to allow the receipt of email messages to start a process.
See also: Anonymous User
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
Appian does not include an email server. You must set up an email server (with unique credentials for each Appian instance) in the following manner:
<APPIAN_HOME>/conf/custom.propertiesand configure the following properties. Note that all properties are in the
||The hostname, IP address, or fully qualified domain name of the mail server that Appian checks for mail messages|
||The username associated with the mailbox (the email account that is setup for use by Appian) storing the messages for your processes. Appian reads the email for the address of whatever account you are using to log into the email server.|
||INBOX||The folder from which new messages should be read. The typical value for this property is
||imap||The protocol that is used by the mailstore (
||143||The port number used to communicate with your mail server|
||true||Whether or not to use SSL when connecting to the mail server. If you set this property to
||300000||The frequency in milliseconds of how often Appian into the mail server to check for new messages. Polling intervals more frequent than 5 minutes may not be allowed by the mail server (consult with your organization's email administrator when setting this value).|
||true||Controls whether the IMAP partial-fetch capability should be used. If fetch time for large emails is too long, you may need to disable partial fetch.|
||false||Setting this property to
||false||Enables debug-level logging for mail polling. Debug logging will include sensitive information such as the plain-text password used to connect to the mail server.|
Depending on the brand, version, and configuration of your mail server, one of the following username formats may be applicable:
Setting the password for the email account(s) polled by Appian is accomplished using the
passwords.properties configuration file.
To configure Appian to poll additional email accounts:
EmailHandlerBeansegment of the property names with a unique name for that email account
userName, etc) for the new email account
passwordfor the new account
<mail_poller_name>is replaced with the unique name from the previous step
Repeat this for each of the email accounts configured for polling.
Appian Cloud email infrastructure supports polling only a single mailbox. If additional mailbox polling is needed, a custom mail server will need to be used.
Inbound email routing works differently in Appian Cloud. See Email on Appian Cloud for more details.
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:
This key/value pair routes a message to a process model with the process model UUID of
The following destination keys are available:
||The ID of the process model.|
||The UUID of the process model.|
||The ID of the process instance.|
||The event persistent ID of the Receive Message Event node.|
If an email does not contain a proper key/value pair for routing, the message routing fails and an error message is logged.
Key/value pairs remain in the email message after it is routed to its destination.
Destination keys can only contain alpha-numeric characters and cannot begin with a numeric character.
|Starts With||Replaced With||Comment|
|Numeric character (0-9)||
|Any non alpha-numeric character||
||Three underscore characters are used.|
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:
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:
Add a custom alias definition using the following pattern.
For example, with an email alias of
HelpDeskRequest@mydomain.topdomain, define a process model start event target using a UUID with the following parameters.
The following routing prefixes can be used when defining an alias.
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.
See also: Start Event: Receive Message
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).
||A routing alias for email received by Appian.|
The mailhandler alias custom property outlined above is not available in Appian Cloud.
To test the email service:
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
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)
Type the following based your email address:
1 EHLO email@example.com
You should receive the following reply.
1 250 server-name Hello firstname.lastname@example.org (connecting.machine.hostname [ip.address])
EHLO, use the
The mail server might be down.
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
Add the following property definition to your
Debug logging will include sensitive information such as the plain-text password used to connect to the mail server.
Review the application server log output to confirm whether a connection is being established.
See also: Configuring Notifications
Mail Server Setup