Mail Server Setup

This page describes how to enable Appian to send and receive emails from a mail server.

Why set up a mail server?

Appian sends email to notify users of task assignments and various alerts. It receives email to start processes and receive process information. App developers can also configure the Send E-Mail Smart Service to send email from a process application.

Before Appian can send or receive these emails, you must configure Appian to use your mail server.

Step 1: Set up a mail server

Appian does not include a mail server. You must set up a mail server with unique credentials for each Appian instance.

To set up a mail server:

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 mail server to receive Appian email.
2. On the mail server, create an email address for Appian to use.
3. Write down the email address for future reference. This account will be 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.

Step 2: Configure sending emails

When first installed, Appian on Kubernetes is not ready to send email without additional configuration.

To enable Appian to send email, you must specify the SMTP host that will be sending the email.

Depending on your environment, you may also want to do the following:

• Enable SMTP server authentication.
• Send email over SMTPS.
• Enable STARTTLS with SMTP.
• Require STARTTLS with SMTP.
• Configure the From field for process emails.
• Set the default From email
• Specify an alternate email body source.

(Required) Specify the SMTP host

To provide the name of the SMTP host that will be sending the email, add the following .spec.customProperties field to the Appian CR configuration file:

1
conf.mailhandler.mail.smtp.host: "<value>"

where <value> is the IP address, hostname, or fully qualified domain name of the SMTP server.

In addition:

• If your SMTP server isn't running on port 25, list the port number using the <host>:<port> format.

  For example:

  smtphost:80
  
  

• 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.

Enable SMTP server authentication

To enable SMTP server authentication:

1. Add the following .spec.customProperties fields to the Appian CR configuration file:

   1
   2
   conf.mailhandler.mail.smtp.auth: "true"
   conf.mailhandler.mail.user: "<username>"
   

   Where <username> is the account used to connect to the mail server.

2. Provide the password of the account used to connect to the mail server:

   1. Create a Secret named passwords.properties:

      1
      kubectl -n <NAMESPACE> create secret generic passwords-properties --from-file=passwords.properties
      

      where password.properties is the name of the secret.
      
      

   2. Add the following property to the secret you created:

      1
      conf.password.SMTP=<password>
      

      where the <password> value belongs to the mail server account.
      
      

   3. Add the webapp field to the Appian CR configuration file:

      1
      passwordsPropertiesSecretName: "password.properties"
      

      where password.properties is the name of the secret you created.

Send email over SMTPS

Add the following .spec.customProperties field to the Appian CR configuration file:

1
conf.mailhandler.mail.transport.protocol: "smtps"

Enable STARTTLS with SMTP

Add the following .spec.customProperties field to the Appian CR configuration file:

1
conf.mailhandler.mail.smtp.starttls.enable: "true"

If this property is enabled, outgoing mail will use STARTTLS if supported by the remote server but will fall back to plain SMTP otherwise.

Require STARTTLS with SMTP

Add the following .spec.customProperties field to the Appian CR configuration file:

1
conf.mailhandler.mail.smtp.starttls.required: "true"

If this property is enabled, mail will fail if the remote server does not support STARTTLS.

Configure the From field for emails from processes and process models

You can configure the domain and the prefix of the email address used when the From field is set to Process or Process Model.

To do so, add the following .spec.customProperties field to the Appian CR configuration file:

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"

Set the default From email

To set the default email address your site will use to send notifications (for example, an alert or a password reset email), add the following .spec.customProperties field to the Appian CR configuration file:

1
conf.mailhandler.ntf_sndr_addr: "<email address>"

The default value is appian-alerts@<domain>. The <domain> portion of the email address is determined in the following manner:

• appian-alerts@<domain name> where domain name is the domain name in the .spec.webapp.url field in the Appian CR configuration file.
• appian-alerts@<domain.tld> where domain.tld is the domain name and top-level domain of the server if the server has a fully-qualified domain name.
• appian-alerts@<hostname> where hostname is the server running the application server (if there are multiple applications servers, this results in a different name for each).
• appian-alerts@REPLACEME.com if all of the above fail.

Specify an alternate email body source

By default, the application server determines where to retrieve the body of an email before it is sent based on the following fields in the Appian CR configuration file:

However, if the application server cannot readily connect to your configured site URL, you must specify an alternate URL for the application server to use instead.

To do so, add the following .spec.customProperties fields to the Appian CR configuration file:

1
2
3
conf.suite.MAIL_SCHEME: "<URL scheme>"
conf.suite.MAIL_APPLICATION_CONTEXT: "<URL context>"
conf.suite.MAIL_SERVER_AND_PORT: "<fully-qualified domain name and port>"

Step 3: Configure receiving emails

The initial Appian configuration is not ready to receive email. The following configuration steps are required for both Appian Cloud and self-managed environments.

To enable Appian to receive email:

1. (Self-managed environments only) Enable anonymous access.
2. Configure Appian to poll an email account.
3. (Optional) Configure Appian to poll additional email accounts.
4. Configure email routing.

Enable anonymous access

The anonymous user is a system account that does not require authentication using credentials. It must be enabled if you need to send email messages to start process models.

The account is automatically:

• Denied access to all other objects, pages, applications, or items in the portal other than the right to trigger a process using email.
• Assigned the Application User Role. Adding the anonymous user to another user role has no effect; it will always be considered in the Application User Role.

In an Appian Cloud environment, the anonymous user access is enabled by default. To disable this access, contact Appian Support.

In a self-managed environment, you must enable this access by adding the following .spec.customProperties field to the Appian CR configuration file:

1
conf.suite.ANONYMOUS_ACCESS: "true"

Configure Appian to poll an email account

To configure Appian to poll an email account:

1. Add the properties listed in the following table to the .spec.customProperties field in the Appian CR configuration file.

   To construct the full property name, prefix the text in the first column of the table with this string:

   1
   conf.mailhandler.poller.EmailHandlerBean.
   

   For example:

   1
   conf.mailhandler.poller.EmailHandlerBean.mailServer: "mail.example.com"
   

   Property	Description	Default Value
   mailServer	The hostname, IP address, or fully qualified domain name of the mail server that Appian checks for mail messages.
   userName	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. 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
   mailFolder	The folder from which new messages should be read. The typical value for this property is INBOX.	INBOX
   storeProtocol	The protocol that is used by the mailstore (pop3, imap, or imaps). Value must be lowercase (for example, imaps and not IMAPS).	imap
   port	The port number used to communicate with your mail server.	143
   starttls	Whether or not to use SSL when connecting to the mail server. If you set this property to true, and you're using IMAP, storeProtocol must be set to imaps.	true
   pollingInterval	How often (in milliseconds) Appian connects to the mail server to check for new messages. Polling intervals more frequent than 5 minutes may not be allowed by the mail server, so be sure to consult with your organization's email administrator when setting this value.	300000
   partialFetch	Whether Appian uses the IMAP partial-fetch capability when connecting to the mail server. If fetch time for large emails is too long, you may need to disable this property.	true
   forceImapLogin	Sets the command that Appian uses to connect to an IMAP email server. If you set this property to `true`, Appian uses LOGIN instead of IMAP AUTHENTICATE. Tip: Set this property to true when attempting to poll a Microsoft Exchange shared mailbox. A shared mailbox will have a username pattern similar to DOMAIN\username\mailboxname.	false
   debug	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.	false

2. Provide the password for the polled email account:

   1. Create a Secret named passwords.properties:

      1
      kubectl -n <NAMESPACE> create secret generic passwords-properties --from-file=passwords.properties
      

      where password.properties is the name of the secret.
      
      

   2. Add the following property to the secret you created:

      1
      conf.password.EmailHandlerBean.EMAIL_HANDLER=<password>
      

      where the <password> value belongs to the account specified in EmailHandlerBean.username.
      
      

   3. Add the webapp field to the Appian CR configuration file:

      1
      passwordsPropertiesSecretName: password.properties
      

      where password.properties is the name of the secret you created.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
   apiVersion: crd.k8s.appian.com/v1beta1
   kind: Appian
   metadata:
      name: appian
   spec:
      # The properties below serve only as examples. For a full list of
      # email-related properties, refer to the product documentation
      # at Mail_Server_Setup.html
      customProperties:
         conf.mailhandler.mail.smtp.host: "mail.example.com"
         conf.mailhandler.mail.smtp.auth: "true"
         conf.mailhandler.mail.user: "username"

         conf.suite.ANONYMOUS_ACCESS: "true"
         conf.mailhandler.poller.EmailHandlerBean.mailServer: "mail.example.com"
         conf.mailhandler.poller.EmailHandlerBean.userName: "username"

      # Use the name of the Kubernetes secret created earlier
      webapp:
         passwordsPropertiesSecretName: "passwords-properties"

Configure Appian to poll additional email accounts

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. Learn more about email in Appian Cloud.

To configure Appian to poll additional email accounts, repeat the steps in the previous section for each email account, replacing the EmailHandlerBean segment of the property names with a unique name for that email account.

Configure email routing

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:

[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.

Specify a routing alias

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 specify a routing alias, add the following .spec.customProperties field to the Appian CR configuration file:

1
conf.mailhandler.alias.<recipientName>: "<routing>"

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.

Step 4: Select client certificates

To support secure connections to the mail server(s) you've configured, upload and select client certificates in the Admin Console.

Step 5: Test the email service

To test the email service:

1. Verify that your mail server is running by entering the following from a command prompt:

   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
   

2. 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)
   

3. Enter 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])
   

   Tip:  If you are using an older SMTP server version that does not support EHLO, use the HELO command instead.

4. Log into Appian.
5. Create a simple process to send yourself an email.
6. 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.
7. If you do not receive the email, check the mail server log files, as well as the application server log.

Step 6: Troubleshoot email configuration

The sections below describe how to troubleshoot common mail server issues. Follow these steps as needed to resolve problems you run into while testing the email service.

What if it doesn't appear to be working?

1. Connect to the mail server from an email client using the credentials you've specified in the Appian CR configuration file.
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 mail 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 .spec.customProperties field to the Appian CR configuration file:

1
conf.mailhandler.poller.EmailHandlerBean.debug: "true"

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

What's next: Configure notification defaults

Self-managed environments must configure notification defaults.

Feedback