Working with outgoing mails

Like many settings in JIRA, you need to be a JIRA system administrator (the user created during the initial setup is a system administrator) to configure mail server details. Perform the following steps to manage the outgoing mail server:

  1. Log in to JIRA as a JIRA administrator.
  2. Browse to the JIRA administration console.
  3. Select the System tab and then the Outgoing Mail option. This will bring up the Outgoing Mail page:
    Working with outgoing mails

Note

You can have only one outgoing mail server in JIRA.

Adding an outgoing mail server

There are two ways of adding an outgoing mail server in JIRA; both options have some common configuration parameters that you will need to fill in. The following table shows those parameters:

Field

Description

Name

This specifies a name for the mail server.

Description

This specifies a brief description for the mail server.

From address

This specifies an e-mail address that outgoing e-mails will appear to have come from.

Email prefix

This specifies a prefix that will appear with all the e-mails sent from JIRA. This allows your users to set up filter rules in their mail clients. The prefix will be added to the beginning of the e-mail subject.

Service Provider

Select from one of the three predefined mail providers such as Google, Yahoo, or the custom SMTP server.

Host Name

This specifies the host name of your mail server (for example, smtp.example.com).

SMTP Port

This specifies the port number your mail server will be running on. This is optional; if left blank, the default port number 25 will be used.

Username

This is used to authenticate against the mail server if required. Note that mail servers may require authentication to relay e-mails to nonlocal users.

Password

This is used to authenticate the user against the mail server, if required.

JNDI Location

This is the JNDI lookup name if you already have a mail server configured for your application server. Please refer to the following section for details.

For the rest of the parameters, depending on which option you select to set up your mail server, you only need to fill in the ones that are appropriate.

The first option is to select from one of the built-in service providers and specify the mail server's details. For example, if you have an SMTP mail server running, you can select the Custom option from the Service Provider field and specify the host and port number. This is the approach most people will use, as it is simple and straightforward. With this approach, the administrator fills in the mail server's host information, such as the host name and port number:

  1. Browse to the Outgoing Mail page.
  2. Click on the Configure new SMTP mail server button. This will bring you to the Add SMTP Mail Server page.
  3. Enter the general details of your mail server, including the name, description, from address, and e-mail prefix.
  4. Select the type of mail server from the Service Provider field.
  5. Enter the mail server's connection details.
  6. Click on the Test Connection button to verify configuration.
  7. Click on the Add button to register to the mail server:
    Adding an outgoing mail server

Tip

JIRA comes with support for Google and Yahoo! mail services. You can select these options in the Service Provider field if you are using these services.

The second option is to use JNDI. This approach is slightly more complicated as it requires configuration on the application server itself (which is different per application server), and sometimes requires a restart of the application server.

If you are using the standalone distribution, which uses Apache Tomcat, the JNDI location will be java:comp/env/mail/JiraMailServer. You will also need to specify the mail server details as a JNDI resource in the server.xml file in the JIRA_INSTALL/conf directory.

A sample declaration for Apache Tomcat is shown in the following code snippet. You will need to substitute in the real values for some of the parameters in the code of your mail server's details:

<Resource name="mail/JiraMailServer"
  auth="Container"
  type="javax.mail.Session"
  mail.smtp.host="mail.server.host"
  mail.smtp.port="25"
  mail.transport.protocol="smtp"
  mail.smtp.auth="true"
  mail.smtp.user="username"
  password="password"
/>

You will need to restart JIRA after saving your changes to the server.xml file.

Disabling outgoing mail

If you are running a test or evaluation JIRA instance or testing changes to notification rules, you might not want to flood your users with test e-mails. The easiest way for you to disable all outgoing e-mails is by just clicking on the Disable Outgoing Mail button in the Outgoing Mail page. Once you are ready to send e-mails again, you can click on the Enable Outgoing Mail button.

Note

Disabling outgoing mail will only prevent JIRA from sending out notification e-mails based on notification schemes.

Enabling SMTP over SSL

To increase security, you can encrypt the communication between JIRA and your mail server if your mail server supports SSL. There are two steps involved in enabling SSL over SMTP in JIRA.

The first step is to import your mail server's SSL certificate into Java's trust store. You can do this with Java's keytool utility. On a Windows machine, run the following command in a Command Prompt:

Keytool –import –alias mail.yourcompany.com –keystore $JAVA_HOME/jre/lib/security/cacerts –file yourcertificate

The second step is to configure your application server to use SSL for mail communication. The following declaration is for Apache Tomcat that is used by JIRA Standalone. We use the same configuration file and only need to add two additional parameters:

<Resource name="mail/JiraMailServer"
  auth="Container"
  type="javax.mail.Session"
  mail.smtp.host="mail.server.host"
  mail.smtp.port="25"
  mail.transport.protocol="smtp"
  mail.smtp.auth="true"
  mail.smtp.user="username"
  password="password"
  mail.smtp.atarttls.enabled="true"
  mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory"
/>

Once you import your certificate and configure your mail server, you will have to restart JIRA.

Sending a test e-mail

It is always a good idea to send a test e-mail after you configure your SMTP mail server, to make sure the server is running and you have set it correctly in JIRA:

  1. Browse to the Outgoing Mail page.
  2. Click on the Send a Test Email link for your SMTP mail server. This will take you to the Send Mail page.
  3. Click on the Send button to send the e-mail. JIRA will autofill the To address based on your user profile.

If everything is correct, you will see a confirmation message in the Mail log section and receive the e-mail in your inbox. If there are errors, such as mail server connection, then the Mail log section will display the problems. This is very useful when troubleshooting any problems with JIRA's connectivity with the SMTP server:

Sending a test e-mail

In the preceding screenshot, you can see the test e-mail delivery has failed, and the error is because JIRA was unable to connect to the configured SMTP server.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
18.116.63.5