Configuring JIRA's SMTP Mail Server to Send Notifications

2. Specify a host name or JNDI location for your SMTP mail server

The second part of the Add/Update SMTP Mail Server page specifies the Server Details of the SMTP mail server to which JIRA will send mail. There are two ways you can do this. Either:

• specify the SMTP host details of your SMTP mail server;
  or:
• specify the JNDI location of a javax.mail.Session object  — that is, use JNDI to look up an SMTP mail server that you have preconfigured in your application server. This has the following advantages:
  • Better security: the mail details are not available to JIRA administrators through the JIRA administration interface and are not stored in JIRA backup files.
  • More SMTP options: for instance, you could switch to RSET instead of NOOP for testing connections by setting the mail.smtp.userset property.
  • Centralised management: mail details are configured in the same place as database details and may be configured through your application server administration tools.

Specify the SMTP host details

Most people configure JIRA's SMTP mail server by specifying the SMTP host details of this mail server directly in JIRA.

1. In the SMTP host section of the Add/Update SMTP Mail Server page (above), complete the following form fields:

   Service Provider (not available when updating an existing SMTP mail server)	Choose between using your own SMTP mail server (i.e. Custom), or either Gmail (i.e. Google Apps Mail / Gmail) or Yahoo! (i.e. Yahoo! MailPlus) as the service provider for your SMTP mail server. If you choose either Gmail or Yahoo! options and then switch back to Custom, some of the key fields in this section will automatically be populated with the relevant SMTP mail server settings for these service providers.
   Protocol	Choose between whether your SMTP mail server is a standard (i.e. SMTP) or a secure (i.e. SECURE_SMTP) one.
   Host Name	Specify the hostname or IP address of your SMTP mail server. Eg. smtp.yourcompany.com
   SMTP Port	(Optional) The SMTP port number, usually 25 for SMTP or 465 for SMTPS, either of which are assumed if this field is left blank.
   Timeout	(Optional) Specify the timeout period in milliseconds, which is treated as 10000 if this field is left blank. Specifying 0 or a negative value here will result in JIRA waiting indefinitely for the SMTP server to respond.
   TLS	(Optional) Select this check box if your SMTP host uses the Transport Layer Security (TLS) protocol.
   Username	(Optional) If your SMTP host requires authentication, specify the username of these authentication credentials here. (Most company servers require authentication to relay mail to non-local users.)
   Password	(Optional) Again, if your SMTP host requires authentication, spcify the password associated with the username you specified above. When editing an existing SMTP mail server, select the Change Password check box to access and change this field.

    Please Note:

   • If your server's startup script uses the -Dmail system properties (e.g. mail.smtp.host or mail.smtp.port), they will override the settings that you specify in the above form. Additionally, if necessary you can manually specify the host name that JIRA reports itself as to the SMTP server by setting -Dmail.smtp.localhost

2. (Optional) Click the Test Connection button to check that JIRA can communicate with the SMTP mail server you just configured.
3. Click the Add (or Update) button to save JIRA's SMTP mail server configuration.

Specify a 'JNDI Location'

As an alternative to specifying SMTP host details directly in JIRA, you can configure them in your application server, and then look up a preconfigured mail session via JNDI.

In the JNDI Location section of the Add/Update SMTP Mail Server page (above), specify the location of a javax.mail.Session object to use when sending email, in the JNDI Location field. This will begin with the prefix java:comp/env/

Configuring a JNDI location

The JNDI Location that you specify in JIRA will depend on JIRA's application server and configuration. JNDI locations are typically configured in the application server that runs JIRA. Hence, JIRA will need to be restarted after configuring a JNDI location for that configuration to be available in JIRA.

For example, in Tomcat 6 (the application server bundled with 'recommended' distributions of JIRA), your JNDI Location would be java:comp/env/mail/JiraMailServer and you would add the following section to the conf/server.xml of your JIRA Installation Directory, inside the <Context/> node:

<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false">
   ...
     <Resource name="mail/JiraMailServer"
       auth="Container"
       type="javax.mail.Session"
       mail.smtp.host="mail.yourcompany.com"
       mail.smtp.port="25"
       mail.transport.protocol="smtp"
       mail.smtp.auth="true"
       mail.smtp.user="jirauser"
       password="mypassword"
     />
   ...
</Context>

Or if you do not require authentication (e.g. if you are sending via localhost, or only internally within the company):

<Context path="" docBase="${catalina.home}/atlassian-jira" reloadable="false">
   ...
     <Resource name="mail/JiraMailServer"
       auth="Container"
       type="javax.mail.Session"
       mail.smtp.host="localhost"
       mail.smtp.port="25"
       mail.transport.protocol="smtp"
     />
   ...
</Context>

If you happen to be running JIRA on an application server other than Apache Tomcat (which is not a supported JIRA configuration), a similar methodology for configuring a JNDI location to your SMTP mail server should apply to that application server. For details, please see the Transaction Factory documentation.

If you have problems connecting, add a mail.debug="true" parameter to the <Resource/> element (above), which will let you see SMTP-level 'debugging' details when testing the connection.

Move the JavaMail Classes

You will also need to ensure that the JavaMail classes (typically in JAR library files) are present in your application server's classpath and that these do not conflict with JIRA's JAR library files. This is necessary because the application server itself (not JIRA) is establishing the SMTP connection and as such, the application server can not see the JAR library files in JIRA's classloader.

Some operating systems may bundle the JavaMail classes with application servers (eg. Tomcat in Red Hat Enterprise Linux). This may conflict with JIRA's copy of the JavaMail classes, resulting in errors like:

java.lang.NoClassDefFoundError: javax/mail/Authenticator

or:

java.lang.IllegalArgumentException: Mail server at location [java:comp/env/mail/JiraMailServer] is not
         of required type javax.mail.Session.

Lighter application servers such as Apache Tomcat (including the one incorporated into the 'recommended' distributions of JIRA), do not always come with JavaMail.

To prevent any conflicts, check your application server's lib/ directory:

• If the application server already contains mail-1.4.1.jar and activation-1.1.1.jar, then just remove mail-1.4.1.jar and activation-1.1.1.jar from the <jira-application-dir>/WEB-INF/lib/ subdirectory of the JIRA Installation Directory.
• If the application server does not contain mail-1.4.1.jar and activation-1.1.1.jar, then move the mail-1.4.1.jar and activation-1.1.1.jar from the <jira-application-dir>/WEB-INF/lib/ subdirectory of the JIRA Installation Directory into the the lib/ subdirectory of the JIRA Installation Directory (for 'recommended' distributions of JIRA) or the lib/ subdirectory of the application server running JIRA.

SMTP over SSL

You can encrypt email communications between JIRA and your mail server via SSL, provided your mail server supports SSL. 

Firstly, you will need to import the SMTP server certificate into a Java keystore. The process is described on the Connecting to SSL Services page.

Important Note: Without importing the certificate, JIRA will not be able to communicate with your mail server.

Secondly, edit your mail server connection properties and specify starttls and SSLSocketFactory. From {$JIRA_INSTALL}/conf/server.xml (this example uses Gmail's server):

<Resource name="mail/GmailSmtpServer"
   auth="Container"
   type="javax.mail.Session"
   mail.smtp.host="smtp.gmail.com"
   mail.smtp.port="465"
   mail.smtp.auth="true"
   mail.smtp.user="myusername@gmail.com"
   password="mypassword"
   mail.smtp.starttls.enable="true"
   mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"
/>

Troubleshooting

A useful tip for debugging mail-related problems in JIRA is to set the -Dmail.debug=true property on startup. This will cause protocol-level details of JIRA's email interactions to be logged. Additionally, turning up JIRA's log level will show when the service is running and how mails are processed.

Common Problems

• If JIRA does not appear to be creating or sending emails or creating issues and comments from email, your JIRA installation could be experiencing OutOfMemory errors. Please check your log files for OutOfMemory errors. If there are OutOfMemory errors, please restart JIRA and investigate the errors.
• If you find some incoming emails simply disappear, check that you have not accidentally started a second copy of JIRA (eg. in a staging environment) which is downloading and deleting email messages. See the Restoring Data page for flags you should set to prevent mail being processed.
• If you receive 'Mail Relay' errors, make sure you have specified the Username and Password in the SMTP Host section of JIRA's SMTP Mail Server configuration page.

Getting Help

If you cannot resolve a problem yourself, please create a support case in the 'JIRA' project and we will assist.