Troubleshooting issues with the email channel
There are common errors when setting up an email channel for your service project. If you are not receiving requests or if you are getting errors, check the email connection. You might also review how emails are processed to see why a certain type of email isn't making it to your service project.
Check you email connection
To troubleshoot email channel issues, the first thing to do is to check the connection between Jira Service Management and your email account. You will see error messages that show you why the email channel doesn't work for your service project.
To check your connection:
- Choose Jira administration > Applications.
- Under Jira Service Management, select Email requests.
- Select Test.
Check how you process email requests
Global mail settings control how your site processes requests that your customers send to your service project's email addresses. We process emails in three stages:
- Email puller: fetches unread emails from the service project's associated inbox every minute, and copies them to the email database. Emails with attachments larger than 25MB are not fetched.
- Email processor: filters pulled emails to remove things like auto-replies and spam.
- Database cleaner: deletes old emails from the database that are older than 45 days. You can change the purge to a range of intervals from 14 days to 180 days.
You can temporarily adjust these settings to troubleshoot your email channel.
To change global mail settings:
- Choose Jira administration > System.
- Go to Mail > Global mail settings.
Common email channel errors
This section describes the common errors and provides information about how to resolve them.
Setting up the email channel
Message:
This authentication method is deprecated, you should use OAuth 2.0 instead.
Resolution:
You're trying to use an email account from Google or Microsoft with the basic authentication credentials—user and password. Since basic authentication is being deprecated by Google and Microsoft, you need to switch to the OAuth 2.0 authentication method. OAuth 2.0 can be configured by your Jira system admin for the whole Jira instance and then used in your projects. Once it's configured, you can choose it as a method from the drop-down list instead of providing the credentials. For more info on how to configure OAuth 2.0, see OAuth 2.0 integration.
Message:
The email address you entered is currently used by another project's email channel. Please choose another email address. Check out our troubleshooting docs for help resolving the issue.
Resolution:
Make sure each of your service projects has a unique email account. An email account can't connect with multiple service projects.
You can also receive this message if you're trying to use multiple email aliases that point to the same email account for multiple service project email channels.
Requests aren't created or notifications received
Description:
Customers are emailing requests that aren't arriving in your queues. They also aren't receiving notifications.
Resolution:
- Use the instructions above to check the email connection.
- Verify that the customer has permission to email the service desk.
- Verify that the default request type for the email channel has visible Summary and Description fields.
- Verify that the Email puller is on in Global mail settings.
No suitable request type for the email channel
Message:
No suitable request type for the email channel
You will select the default request type assigned to requests created from the email channel during the setup. However no existing request types are suitable for email requests. A suitable request type must have both the Summary and Description fields as visible fields, and all the other visible fields, if any, must be optional. If you want to enable the email channel, add a new request type that meets the criteria or modify an existing one on the Request types page.
Resolution:
- In your service project, select Project Settings > Request types.
- Add a new request type or choose an existing one.
- Select Edit fields.
- Make sure both the Summary and Description fields are added and marked as Visible. Add an Attachment field and mark it as not Required.
- Select Save, then head back to Project settings > Email requests.
Archived messages are creating requests
Description:
When Jira Service Management checks your email accounts for new messages, it polls the inbox folder. Gmail uses labels to classify messages into categories and only has the following folders:
- Inbox
- Sent Mail
- Bin (or Trash)
This means that the archived messages are treated like they're in the inbox folder. With POP3, Jira Service Management is not able to identify archived messages by labels and therefore still brings them in as requests.
Resolution:
Use IMAP instead.
Setting up a Gmail account
Message:
Unfortunately Jira couldn't connect to the mail server. Here is what the mail server said: "[ALERT] Please log in via your web browser: http://support.google.com/mail/accounts/bin/answer.py?answer=78754 (Failure)
Resolution:
Create an application-specific password for Jira Service Management in your Gmail account settings.
Setting up a Yahoo! account
Message:
Unfortunately Jira couldn't connect to the mail server. Here is what the mail server said: "[AUTHENTICATIONFAILED] (#MBR1240) Please verify your account by going to https://login.yahoo.com"
Resolution:
Create an application-specific password for Jira Service Management in your Yahoo! account settings.
Microsoft Outlook locks account for security
Message:
Unfortunately Jira Service Management couldn't connect to the mail server. Here is what the mail server said: "STAT command failed: Exceeded the login limit for a 15 minute period. Reduce the frequency of requests to the POP3 server.
Resolution:
Jira Service Management checks email accounts every minute. Microsoft Outlook might suspect inappropriate usage of this account and lock it for security reasons. To resolve this, use IMAP instead.
Jira doesn't trust the SSL certificate on the the mail server
Message:
Unfortunately JIRA couldn't connect to the mail server. Here is what the mail server said: "unable to find valid certification path to requested target" Check out our troubleshooting docs for help resolving the issue.
Resolution:
Make sure that the SSL certificate chain from the mail server is imported into Jira's Java trust store. Follow the steps on https://confluence.atlassian.com/kb/unable-to-connect-to-ssl-services-due-to-pkix-path-building-failed-779355358.html.