8.4 Mail Handlers: Creating Issues and Comments from Email
Key Takeaways
- Mail handlers (Settings > System > Mail > Incoming mail) turn email from licensed users into new issues or comments; JSM's email channel is the tool for unlicensed customers.
- The 'create a new issue or add a comment' handler comments on the issue whose key is in the subject, and otherwise creates an issue in the handler's default project.
- A default reporter lets Jira accept email from unknown senders, and the original sender's address is appended to the issue description.
- CC assignee assigns the new issue to the first valid user in CC, then To, then BCC; otherwise the project default assignee (project lead or Unassigned) applies.
- Jira skips messages older than 7 days, messages without a subject, and messages that fail SPF, and caps message data plus attachments at 25 MB.
8.4 Mail Handlers: Creating Issues and Comments from Email
Blueprint objective 5.4 asks you to configure mail handlers and to troubleshoot auto-assignment for issues created from a mail handler. Mail handlers let licensed Jira users create issues and add comments by sending email. They're a Jira admin feature, configured in Settings > System > Mail > Incoming mail.
Don't confuse this with Jira Service Management. A JSM service project has its own email channel (Project settings > Email requests) built for customers, and those senders don't need a Jira license. The Jira mail handler covered here is designed for licensed users working in Jira projects.
The Two Pieces: Mail Server and Mail Handler
| Piece | What It Is | Key Settings |
|---|---|---|
| Incoming mail server | The mailbox Jira reads | Every site has a preconfigured default cloud mail server. You can add Gmail or Microsoft servers with OAuth 2.0 (sign in with Google or Microsoft), or a custom POP/IMAP server with protocol, host, port, timeout, username, and password |
| Mail handler | The rule that turns each message into an issue or a comment | Handler type, the server to read, an IMAP folder (optional), how often to scan (minutes), and the handler options below |
Atlassian recommends switching Gmail and Microsoft servers from basic authentication or app passwords to OAuth 2.0, because both providers are phasing out the older methods. Configuring mail servers requires the Administer Jira global permission.
Handler Types
| Handler | Behavior |
|---|---|
| Default email handler | Created automatically with the default cloud mail server. Its parameters include createusers=false, stripquotes=true, and bulk=ignore |
| Create a new issue or add a comment to an existing issue | If the subject contains an issue key, the message becomes a comment on that issue. If not, Jira creates a new issue in the handler's default project |
| Create a new issue from each email message | Every message becomes a new issue |
| Add a comment with the entire email body | Adds the whole body as a comment on the first issue key found in the subject |
| Add a comment from the non-quoted email body | Adds only lines that don't start with a > or vertical-bar quote marker |
| Add a comment before a specified marker or separator | Keeps the text before a Split Regex match (for example, /----\s*Original Message\s*----/) and discards the rest |
For every commenting handler, the comment author comes from the email's From address.
Handler Options
| Option | What It Does |
|---|---|
| Project | The default project for new issues (only used when creating issues) |
| Issue type | The default issue type for new issues |
| Strip quotes | Removes quoted text from earlier replies |
| Catch email address | Processes a message only if a specific address is in the To or CC line. Useful when several aliases deliver to one mailbox. One catch address per handler |
| Bulk | How to treat automated "bulk" mail (Precedence: bulk, or Auto-Submitted not "no"): ignore it, forward it, delete it, or accept it. Forwarding is recommended to prevent mail loops |
| Forward email | Where Jira sends a status message when it can't process an email |
| Default reporter | The user account used when the sender's address doesn't match an existing user. The original sender's address is added to the end of the issue's description |
| CC assignee | Assigns the new issue to the first valid user in CC, then To, then BCC. If no valid user is found, the handler sets no assignee |
| CC watchers | Adds matching Jira users from the email as watchers |
How Jira Processes a Message
- Jira scans the mailbox on the handler's schedule.
- It ignores messages whose sent date is older than 7 days, and messages with no subject (the subject becomes the issue summary).
- If the sending domain uses SPF and the message fails SPF validation, Jira rejects it.
- It matches the From address to a Jira user, or falls back to the default reporter if one is configured.
- It creates the issue or adds the comment according to the handler type, as that user. The user needs Create Issues (or Add Comments) in the project.
- Attachments become issue attachments if attachments are enabled. The limit for message data plus attachments is 25 MB.
- A high-priority email creates an issue with a higher priority than the default.
- Successfully processed messages are deleted from POP/IMAP mailboxes. With Gmail or Microsoft OAuth servers, they're marked as read instead. Atlassian suggests routing a copy to a backup folder so you keep a record.
Mail loops: Jira keeps count of messages from each sender. Its advanced mail loop detection can start treating a sender that emails too often as bulk mail. You can raise the threshold (recommended), allowlist trusted domains, or set the threshold to 0 to disable it (not recommended, because out-of-office replies commonly cause loops).
Troubleshooting Mail Handlers
| Symptom | Likely Cause | Fix |
|---|---|---|
| Emails from outsiders are ignored | The sender isn't a Jira user and no default reporter is set | Set a default reporter (a dedicated account with Create Issues) |
| "Reporter does not have permission to create an issue" | The matched user (or default reporter) lacks Create Issues in the project | Grant Create Issues through the permission scheme |
| Issues from a known sender fail, but a default reporter is set | The sender's address matches an existing user who lacks Jira app access, so the default reporter is ignored | Give that user app access, or remove the address from the existing user |
| Nothing is processed | Messages older than 7 days, missing subject, or SPF failure | Fix the sending side |
| Long reply chains land in comments | Handler keeps quoted text | Use Strip quotes or the marker/separator handler with a Split Regex |
| Creation fails for a required field | The project's field configuration requires a field the email can't supply | Make the field optional or give it a default value |
Troubleshooting Auto-Assignment
Blueprint 5.4 specifically names assignment problems. Work through them in this order:
- Is CC assignee enabled? If it is, Jira assigns the issue to the first valid user in CC, then To, then BCC. An unexpected assignee usually means someone was CC'd. A missing assignee means no address matched an assignable user.
- If CC assignee isn't used (or finds no one), normal defaults apply. Emails don't set components, so the project default assignee is used: the project lead or Unassigned (if the site allows unassigned issues).
- Check that the intended person is assignable. They need the Assignable User permission in the project.
- Automation can reassign afterwards. An Issue created rule can route email-created issues, for example by sender domain or by keywords in the summary.
A company wants partners who don't have Jira accounts to email bug reports to a shared address and have issues created in the PARTNER project. The mail handler creates issues for employees, but partner emails are ignored. What should the Jira admin configure?
Issues created by a mail handler keep getting assigned to Priya, a manager who's often CC'd on partner emails, instead of staying with the project default. Which handler setting explains this?
An admin configures a new IMAP mail handler, but some messages are never turned into issues. They were sent more than a week ago, or have an empty subject line. What explains this?