Documentation for JIRA 6.3 EAP developer (EAP) releases only. Not using this? See below:
(JIRA 6.2.x documentation | JIRA OnDemand documentation | earlier versions of JIRA)

Skip to end of metadata
Go to start of metadata

On this page:

To enable JIRA to send notifications about various events, you need to first configure an SMTP mail server in JIRA .

Define or edit the SMTP mail server

  1. Log in as a user with the JIRA System Administrators global permission.
  2. Choose > System. Select Mail > Outgoing Mail to open the SMTP Mail Server page.
    (tick) Keyboard shortcut: g + g + start typing outgoing mail
    (info) 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.
    (info) 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. 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! Mail Plus) as the service provider for your SMTP mail server.
    (info) 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.
    (info) When editing an existing SMTP mail server, select the Change Password check box to access and change this field.

    (warning) 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

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

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:

or:

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.

(warning) 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):

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.

 

19 Comments

  1. Anonymous

    These instructions, and the ones linked, seem to allow the user to fall into a very easy pitfall of blowing away Jira's access to the cacert files. I propose two changes:

    1. Note that going down the path of importing every ssl certificate you trust should not be embarked on lightly, and is only needed if you are dealing with certificates not signed by a root CA. For example, self-signed certificates.
    2. That the user use keytool to import the cacerts keystore to avoid headaches down the line if they do wish to go down the path of creating their own keystore. This provides the benefit of trusting all root CA signed certificates automatically which reduces administrative headache. The drawback is the same, if the user wishes to hand verify each certificate themselves they should not do this.
  2. Anonymous

    I followed all instructions to the letter to set up GmailSmtpServer connection in a Windows Standalone installation.  The Stdout log showed that I was clearly able to connect:

            "DEBUG SMTP: connected to host "smtp.gmail.com", port: 465"

    However, the gmail service rejected my login:

             "535-5.7.1 Username and Password not accepted."

    The Send Test Mail interface also reported Authentication Failure

    After adding several startup options for the JVM, I was able to see that JIRA set JAVA_HOME to a different path than I had used when importing the smtp.gmail.com cert!

    Options added:

    -Dmail.smtp.starttls.enable=true
    -Dmail.debug=true
    -Djavax.net.debug=all

    My original JAVA_HOME:
       c:\Program Files\Java\jre1.6.0_07

    What JIRA set:
       c:\Program Files\Atlassian\JIRA 4.2\jre

    Once I imported the cert to the keystore in the JIRA path, everything worked.  I think that JIRA set a different JAVA_HOME b/c my JAVA_HOME was set only locally, i.e., only for the cmd session in which I was doing my trouble-shooting. 

    Moral of the story: when you've done everything according to the doc, but still get an Authenication Failure, check the source of the cacerts.

  3. Who can describe how to configure Mail servers on localhost to test email notifications? Is it possible to do on local computer?

  4. I'm getting 'unknown host' when configuring SMTP server from within Jira administration page. I have to use IP address for it to work. This is not recommended, and so we'd like to use a hostname.

    I'm running on RHEL5, Oracle 11g. /etc/resolv.conf contains:
      nameserver 8.8.8.8
      nameserver 8.8.4.4

    And i can 'ping' and 'nmap' my host successfully.

    ls -l atlassian-jira-enterprise-4.2-standalone/lib/
    total 12044
    -rw-r--r--  1 jira jira   10807 Oct 18  2010 annotations-api.jar
    -rw-r--r--  1 jira jira  243597 Dec  8  2008 carol-1.5.2.jar
    -rw-r--r--  1 jira jira     606 Dec  8  2008 carol-properties.jar
    -rw-r--r--  1 jira jira   49147 Oct 18  2010 catalina-ant.jar
    -rw-r--r--  1 jira jira  123820 Oct 18  2010 catalina-ha.jar
    -rw-r--r--  1 jira jira 1146570 Oct 18  2010 catalina.jar
    -rw-r--r--  1 jira jira  230149 Oct 18  2010 catalina-tribes.jar
    -rw-r--r--  1 jira jira   27814 Oct 18  2010 el-api.jar
    -rw-r--r--  1 jira jira  641570 Dec  8  2008 hsqldb-1.8.0.5.jar
    -rw-r--r--  1 jira jira  103201 Oct 18  2010 jasper-el.jar
    -rw-r--r--  1 jira jira  513722 Oct 18  2010 jasper.jar
    -rw-r--r--  1 jira jira 1395266 Oct 18  2010 jasper-jdt.jar
    -rw-r--r--  1 jira jira   17097 Jan  4  2010 jcl-over-slf4j-1.5.8.jar
    -rw-r--r--  1 jira jira   11428 Dec  8  2008 jonas_timer-1.4.3.jar
    -rw-r--r--  1 jira jira   64502 Dec  8  2008 jotm-1.4.3.jar
    -rw-r--r--  1 jira jira   42654 Dec  8  2008 jotm-iiop_stubs-1.4.3.jar
    -rw-r--r--  1 jira jira    5824 Dec  8  2008 jotm-jrmp_stubs-1.4.3.jar
    -rw-r--r--  1 jira jira   76608 Oct 18  2010 jsp-api.jar
    -rw-r--r--  1 jira jira    8809 Dec  8  2008 jta-1.0.1.jar
    -rw-r--r--  1 jira jira  294726 Jan  8  2010 jtds-1.2.2.jar
    -rw-r--r--  1 jira jira    4464 Jul 27  2009 jul-to-slf4j-1.5.8.jar
    -rw-r--r--  1 jira jira  391834 Dec  8  2008 log4j-1.2.15.jar
    -rw-r--r--  1 jira jira  724225 Jan  8  2010 mysql-connector-java-5.1.10.jar
    -rw-r--r--  1 jira jira    3305 Dec  8  2008 objectweb-datasource-1.4.3.jar
    -rw-rw-r--  1 jira jira 2111220 Feb 15  2011 ojdbc6.jar
    -rw-r--r--  1 jira jira 1996228 Jan 15  2010 oracle-jdbc15-11.2.0.1.0.jar
    -rw-r--r--  1 jira jira  145744 Dec  8  2008 ots-jts_1.0.jar
    -rw-r--r--  1 jira jira  472831 Jan  8  2010 postgresql-8.4-701.jdbc3.jar
    -rw-r--r--  1 jira jira   88209 Oct 18  2010 servlet-api.jar
    -rw-r--r--  1 jira jira   23445 Jul 27  2009 slf4j-api-1.5.8.jar
    -rw-r--r--  1 jira jira    9679 Jul 27  2009 slf4j-log4j12-1.5.8.jar
    -rw-r--r--  1 jira jira  750470 Oct 18  2010 tomcat-coyote.jar
    -rw-r--r--  1 jira jira  197445 Oct 18  2010 tomcat-dbcp.jar
    -rw-r--r--  1 jira jira   66144 Oct 18  2010 tomcat-i18n-es.jar
    -rw-r--r--  1 jira jira   43742 Oct 18  2010 tomcat-i18n-fr.jar
    -rw-r--r--  1 jira jira   49021 Oct 18  2010 tomcat-i18n-ja.jar
    -rw-r--r--  1 jira jira   85476 Dec  8  2008 xapool-1.3.1.jar
  5. For you JIRA users with an Exchange server, the setting that works for me by default with Exchange is:

    Port: 587
    TLS: Yes

    Exchange doesn't like unencrypted passwords being used, and it seems that in order to encrypt them you need to use SECURE_SMTP or TLS... Well, TLS didn't work on port 25, but did on port 587.

    Hope this helps someone 

  6. Anonymous

    There is no option for outgoing mail in the ondemand version of JIRA. Either a problem with JIRA or your documentation...or both?

    1. Hi there,

      Please note this note at the top of the page:

      Kind regards,

      Giles.

      1. Anonymous

        I have the same problem.  Just upgraded to JIRA v5.1.  Ours is not the OnDemand version as its installed locally on an isolated network.  Any ideas?

        1. Hi there,

          My local 'behind the firewall' test installation of JIRA 5.1 (i.e. not JIRA OnDemand) exposes the Outgoing Mail option to me.

          Have you confirmed that the account you are logged in with has the JIRA System Administrators global permission? (You won't be able to access this Outgoing Mail administration page in JIRA without this permission.)

          Cheers,

          Giles.

  7. As Anonymous wrote above, for OnDemand there is no path: Administration > System > Mail > Outgoing Mail.

    This is particularly important because the basic "Ninja" training directs new users to that non-existent path.  Quite a number of the "Ninja" training paths are non-existent.  Perhaps, this ("Ninja" training) is a good starting point for updating documentation and increasing Atlassian's user base, which would, in turn, increase user adoption and Atlassian's revenues – so that Atlassian could hire people to update the documentation.

  8. Anonymous

    I have just upgraded to jira4.4.5. All i can see in Administration : Administration > System > Mail > Mailservers. The only option I get POP/IMAP not smtp server. It doesn't display the "Add SMTP Mail Server" screen.

    Can anyone help?

    Thanks.

    1. Anonymous

      I think this is the reason.

      export JAVA_OPTS="-Datlassian.mail.senddisabled=true -Datlassian.mail.fetchdisabled=true -Djava.library.path=/usr/lib/jvm/java-1.6.0-sun-1.6.0.31.x86_64/jre/lib/amd64/server:/usr/lib/jvm/java-1.6.0-sun-1.6.0.31.x86_64/jre/lib/amd64:/usr/lib/jvm/java-1.6.0-sun-1.6.0.31.x86_64/jre/lib"

  9. Anonymous

    I am having problems with my JIRA mail sending.

    I follow the instructions above to set up an SMTP host.

    I click test connection and it's successful

    I send a test email and it's successful

    I go to Send Email and send an email to several users successfully.

    ... but if I create an issue, or assign one to me, or resolve an issue, I don't get an email!

    I'm using the default notification scheme with no changes from the installation version.

    Does anyone have any ideas?

    1. Anonymous

      Ive managed to get it working now. 

      It was because none of my projects were associated with a notification scheme by default

      (which means that the page link for Creating a Notification Scheme needs to be edited as it says new projects get the default notification scheme set up on creation)

  10. Hi,

    I have transfered JIRA (v4.1.2#531) on a new server and since the eMail notification does not work.

    The parameters are the same on the two servers.

    Could you please help me making it work ?

    Thanks

    Thierry

    1. Solved. In fact it was working.

  11. Anonymous

    Back to version 3.12, "Email Prefix" would eventually reflect the event (Created, Issue Workload Updated, Closed, ... etc) in the email subjects, but it seems not available now. How do I do to get it back?  Thanks.

  12. Anonymous

    I need to know if anyone had the following problem:
    Notification emails are in queue the waiting and I have to send them manually, this is very annoying.d

  13. I had Avast Antivirus running on my computer and this one caused connection to first timeout and later to give other errors.

    Fortunately after a few tries in JIRA setup, Avast opened up itself on correct settings page and I turned that feature off.