Configuring JIRA to Send SMTP Mail

To enable JIRA to send notifications about various events, you need to first configure JIRA to send SMTP email.

On this page:

1. Define the SMTP Mail Server

1. Log in as a user with the 'JIRA System Administrators' global permission.
2. Bring up the administration page by clicking either the 'Administration' link on the top bar or the title of the Administration box on the dashboard.
3. Click "Mail Servers" in the left-hand column (under "Global Settings").
4. Click "Configure new SMTP mail server".
5. This will display the "Add SMTP Mail Server" screen. Complete the top section as follows:

   Name	An arbitrary name to associate with this email server configuration
   Description	(Optional) Email server description
   From address	The email address that outgoing mails will appear to have come from (unless overridden per project). Note that this is just the address part ("jira@company.com"). JIRA will use it in constructing the full From header based on the current user ("Joe Bloggs (JIRA) <jira@company.com>"). To change the From header, go to the "Administration" menu, select "General Configuration" (under "Global Settings") and edit the Email From Header field.
   Email prefix	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 their email.

2. Specify the Host Name or JNDI Location

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

• specify the Host Name of your mail server;
  or:
• specify the JNDI Location - that is, use JNDI to look up a 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: if you want to use SMTP over SSL (see below), you will need to use JNDI.
  • 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 Host Name

Most people configure SMTP details directly in JIRA. The form fields are as follows:

Once done, click 'Update' and then "Send a Test Email" to test the connection details.

Specify and configure a JNDI Location

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

Complete the following form field

The JNDI Location will depend on your application server and configuration. For example, in Tomcat 5.5 (the default application server that is bundled with JIRA Standalone ), your JNDI Location would be java:comp/env/mail/JiraMailServer, and you would add the following section in conf/server.xml , 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 don't 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>
        

The format for other application servers will be similar. For details please see the Transaction Factory documentation.

If you have problems connecting, add a mail.debug="true" parameter, which will let you see SMTP-level details when testing the connection.

Move the JavaMail Classes

You will also need to ensure that the JavaMail classes are present in your application server's classpath, and do not conflict with JIRA's copy. This is necessary because the application server is establishing the SMTP connection, not JIRA, and the application server will not see the JARs in JIRA's classloader.

Most J2EE application servers (eg. JBoss, Orion, Weblogic, Websphere) come with JavaMail. Also, some operating systems may ship 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 app servers — Tomcat (including JIRA Standalone), Resin, Jetty (but not JettyPlus) — do not always come with JavaMail.

To prevent any conflicts, check your application server's lib/ directory, eg. common/lib/ for Tomcat.

• If the application server already contains mail-1.4.1.jar and activation-1.1.1.jar, then just remove WEB-INF/lib/mail-1.4.1.jar and WEB-INF/lib/activation-1.1.1.jar from the JIRA webapp.
• If the application server does not contain mail-1.4.1.jar and activation-1.1.1.jar, then move JIRA's WEB-INF/lib/mail-1.4.1.jar and WEB-INF/lib/activation-1.1.1.jar into the application server's lib/ directory.

SMTP over SSL

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

To do this, edit your mail server connection properties and specify starttls and SSLSocketFactory. From <jira-install>/conf/server.xml:

  <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"
  />
         

Please note that there is a known bug in some versions of Tomcat 5.5.x (please see JRA-12180).

Additionally, as you are connecting to an SSL service, you will need to import the SMTP server certificate into a Java keystore. The process is described on the Connecting to SSL Services page.

For example, on Linux using GMail's SMTP server, you can obtain the certificate by issuing:

openssl s_client -connect smtp.gmail.com:465 > gmail.cert
^C

Deleting everything from gmail.cert except ----BEGIN CERTIFICATE---- through -----END CERTIFICATE-----

Then importing the certificate as follows:

keytool -import -alias jiramailserver -keystore ~/.keystore -file ~/gmail.cert
Enter keystore password:  changeit
Owner: CN=smtp.gmail.com, O=Google Inc, L=Mountain View, ST=California, C=US
Issuer: EMAILADDRESS=premium-server@thawte.com, CN=Thawte Premium Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA
Serial number: 511d848064f8fa118a1210a02cc5f6b2
Valid from: Sun Jul 29 17:00:00 PDT 2007 until: Thu Jul 29 16:59:59 PDT 2010
Certificate fingerprints:
	 MD5:  F1:D3:DE:59:9D:9C:E2:31:EA:AA:2C:A0:FC:AD:9A:61
	 SHA1: 5E:F7:E8:CE:1A:BE:D8:94:F2:77:45:5D:ED:38:46:4F:5D:D1:97:61
	 Signature algorithm name: SHA1withRSA
	 Version: 3

Extensions:

#1: ObjectId: 2.5.29.19 Criticality=true
BasicConstraints:[
  CA:false
  PathLen: undefined
]

#2: ObjectId: 1.3.6.1.5.5.7.1.1 Criticality=false
AuthorityInfoAccess [
  [accessMethod: 1.3.6.1.5.5.7.48.1
   accessLocation: URIName: http://ocsp.thawte.com]
]

#3: ObjectId: 2.5.29.31 Criticality=false
CRLDistributionPoints [
  [DistributionPoint:
     [URIName: http://crl.thawte.com/ThawtePremiumServerCA.crl]
]]

#4: ObjectId: 2.5.29.37 Criticality=false
ExtendedKeyUsages [
  serverAuth
  clientAuth
]

Trust this certificate? [no]:  yes
Certificate was added to keystore

You would also need to tell Tomcat where the keystore file is located by adding the following to bin/setenv.sh :

export JAVA_OPTS="-Djavax.net.ssl.trustStore=$HOME/.keystore"

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 doesn't appear to be creating sending emails or creating issues and comments from email, your JIRA instance 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 haven't accidentally started a second copy of JIRA (eg. in a staging environment) which is downloading and deleting mails. See the Restoring Data page for flags you should set to prevent mail being processed.
• If you receive email with non-ASCII attachment names, particularly from Thunderbird users, you will need to configure JavaMail to support RFC 2231-encoded attachments. See JRA-12525 for details.

Getting Help

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