Define or edit the SMTP mail server

1. From the top navigation bar select Administration  > System. 
2. Select Mail > Outgoing Mail to open the SMTP Mail Server page.
   If no SMTP mail server has been defined, then a Configure new SMTP mail server button will be shown on the page. If one has already been defined, then the SMTP mail server's details will be shown on the page, along with a set of operation links at the right.

3. Click either the Configure new SMTP mail server button to define a new SMTP mail server, or the Edit link at the right to edit the existing SMTP mail server, which will open the Add/Update SMTP Mail Server page.

4. Complete the top section of this page as follows:

   Name	Specify an arbitrary name to identify this SMTP mail server configuration.
   Description	(Optional) Specify an arbitrary description that describes the SMTP mail server. This description appears below the Name of the SMTP mail server on the SMTP Mail Server configuration page.
   From address	Specify the email address used in the 'sender address' (or 'from') field of notification messages sent by Jira, unless overridden in a project configuration. Only specify an email address for this field (e.g. jira@example-company.com). Jira will use this value to construct the full 'from' header based on the current user ("Joe Bloggs (Jira) <jira@example-company.com>"). To change the 'from' header, go to Administration > System > General Configuration and (under Settings), edit the Email from field.
   Email prefix	Specify the subject of emails sent from this server will use this string as a prefix. This is useful for your users so that they can filter email notifications from Jira based on this prefix.

   Screenshot: Add (or Update) SMTP Mail Server

   

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. To enable the JDNI location input, select the Enabled checkbox. This will disable SMTP host details form. 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.
  • Centralized 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), Yahoo! (i.e. Yahoo! Mail Plus), or Microsoft (i.e. Microsoft Exchange Online / Outlook) as the service provider for your SMTP mail server. If you choose either Gmail, Yahoo!, or Microsoft 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 checkbox if your SMTP host uses the Transport Layer Security (TLS) protocol.
   Authentication method	The way to authenticate to the mail server. If you've configured your OAuth 2.0 integration, you'll see it on the list and be able to select it. Learn more in Configure an outgoing link
   Username	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.) If you've configured your OAuth 2.0 integration, this field is mandatory. Otherwise, you'll see the Enter the valid username error message.
   Password	(Optional) Again, if your SMTP host requires authentication, specify the password associated with the username you specified above. When editing an existing SMTP mail server, select the Change Password checkbox 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

   • The SMTP must support the multipart content type. Without this mails will not be able to send.
2. (Only for the OAuth authentication method) Select Authorize. You'll be redirected to your service provider's site to log in to your account and authorize the connection. When you do, you'll be redirected back to the application.
3. Select Test Connection to check that Jira can communicate with the SMTP mail server you've just configured.
4. Select Add or Update 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 application 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.

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 (e.g. 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 javax.mail-x.y.z.jar, javax.mail-api-x.y.z.jar, and activation-x.y.z.jar (where x.y.z defines the version), remove them from the <jira-application-dir>/WEB-INF/lib/ subdirectory of the Jira application installation directory.
• If the application server does not contain javax.mail-x.y.z.jar, javax.mail-api-x.y.z.jar, and activation-x.y.z.jar (where x.y.z defines the version), move them from the <jira-application-dir>/WEB-INF/lib/ subdirectory of the Jira application 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 Configuring an SSL connection to Active Directory 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.