Prepare a Jira development server's mail configuration

Still need help?

The Atlassian Community is here for you.

Ask the community

What is the problem?

When you bring up a development instance of Jira, it is important to test your mail settings. However, if you bring up an identical copy of your running instance, you can have a recipe for disaster as it could result in incoming emails being parsed by your development instance, or erroneous notifications going out to users that do not understand what is going on. Extreme cases have resulted in system outages.

If you have multiple Jira instances using the same mailbox, the dev instance can end up processing mails that should be going to production. This means issues and comments can be added to the development server instead of production and also dev can send out notifications.

Jira Service Management versions that are 2.4.3 or lower will still continue to poll mail due to JSD-1860 - Getting issue details... STATUS . Please keep this in mind when going through these steps.

How do we prevent it?

Follow these steps to get a dev instance up and running with no rogue email issues: 

  1. Backup your existing instance as in our Backing Up docs.
  2. Before restoring the XML data into your staging Jira instance, please disable the mail handlers, as in our disabling emailing documentation.
    (info) This will require a restart of Jira. If you've used one of the bundled installers, it will automatically start Jira up without these settings. Please ensure to restart Jira after making these changes.
  3. After restarting Jira and disabling email, import your production Jira data.
  4. Delete all of the existing mail handlers. 
  5. Delete all existing SMTP and IMAP / POP servers.
  6. Shut down the instance.
  7. Remove all the filter subscriptions with the following SQL:

    delete from filtersubscription; 

    (info) skip this if you need to test filter subscriptions. Just make sure to do step 11 to ensure that your users do not get spammed.

  8. Remove the following entries:

    delete from notificationinstance; 
  9. As all references to the production mail servers have been removed, you can now revert the changes in step 2 and restart Jira.
  10. Add the necessary development mail server configuration for testing.
  11. To ensure that no emails go out to regular users during your testing, we recommend creating a dummy email address which you can use to verify that notifications are going to the right place. Then update all user emails to point to the same place using this query:

    update cwd_user set email_address='test@example.com', lower_email_address='test@example.com'; 
  12. Replace all property entries which contain emails with one of your choice:

    update propertystring set propertyvalue ='test@example.com' where id in (select pe.id from propertyentry pe where pe.property_key='jira.project.email.sender');
  13.  Alternate to the previous two steps, the following technique can be used to trap mail externally. 
    This will control where the outgoing mails are being delivered to, without updating all mailaddresses.

    One option for this is using local postfix for sending mails (this is best practice in most of the cases anyway), and rewriting the "to" address with the desired test-address. (All outgoing mails will be generated the way they should be, but will instead be sent to a dedicated address without touching the user base here.)

    The other option is to use a product like "mailtrap" which comes with a free version: https://mailtrap.io/ This can be used in different scenarios where a local postfix was not an option. All outgoing mails will be "trapped" into the mailtrap mailbox (imagine it as intermediate mailbox), you can read, see and inspect them - and will definitely see what Jira (and JSM!) was sending out.

    Note that the software mentioned above (postfix, mailtrap) is not within Atlassian's support scope, and the techniques requires your expertise and experience with the above for setting up and monitoring test mail notifications. 

Last modified on Aug 29, 2022

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.