Study guide
8.4 Mail Handlers: Creating Issues and Comments from Email
Atlassian Certified Professional - Jira Administration for Cloud ACP-120
Track your progress as you read
Finished sections get a check mark.
1 Chapter 1: Exam Overview, Blueprint & Jira Cloud Fundamentals
1.1 ACP-120 Exam Structure, Blueprint & Testing Strategy 1.2 Jira Cloud Architecture, Products & Admin Hierarchy
2 Chapter 2: Organizations, Managed Accounts & Global Access
2.1 Atlassian Organizations, Domain Verification & Managed Accounts 2.2 Atlassian Guard, SAML SSO, SCIM & Authentication Policies 2.3 Site Access, Product Access Tiers & Global Permissions 2.4 User Directory Architecture: Groups vs. Project Roles
3 Chapter 3: Project Permissions & Issue-Level Security Schemes
3.1 Permission Scheme Mechanics & Critical Project Permissions 3.2 Permission Troubleshooting, Additive Permissions & Permission Helper 3.3 Issue Security Schemes, Security Levels & Access Containment
4 Chapter 4: Project Configuration, Types, Versions & Boards
4.1 Company-Managed vs. Team-Managed Project Architecture 4.2 Project Templates, Project Keys & Project Categories 4.3 Project Components, Component Leads & Default Assignees 4.4 Versions, Fix Versions, Release Lifecycles & Project Archiving 4.5 Scrum and Kanban Board Configuration, Board Filters & Columns
5 Chapter 5: Issue Types, Custom Fields, Screens & Schemes
5.1 Standard vs. Sub-task Issue Types & Issue Type Schemes 5.2 Custom Field Types, Global vs. Project Contexts & Options 5.3 Field Configurations, Renderers, Hiding & Required Fields 5.4 Screens, Screen Schemes & Issue Type Screen Schemes
6 Chapter 6: Workflows — Company-Managed and Team-Managed
6.1 Statuses, Status Categories, Direct & All-to-One Global Transitions 6.2 Transition Rules: Conditions vs. Validators 6.3 Post Functions, Execution Order & Resolution Management 6.4 Workflow Schemes, Editing Active Workflows & Status Migration 6.5 Team-Managed Workflows, Statuses & Workflow Rules
7 Chapter 7: Jira Cloud Automation
7.1 Automation Engine, Rule Architecture & Event Triggers 7.2 Automation Conditions, Smart Values & String/Date Expressions 7.3 Branch Rules, Related Issues, Sub-tasks & Parent Epics 7.4 Rule Scopes, Automation Usage, Audit Logs & Error Handling
8 Chapter 8: Notifications, Events, Personal Settings & Mail Handlers
8.1 Jira Events, System Events & Notification Schemes 8.2 Notification Recipients, Custom User Fields & Deduplication 8.3 Team-Managed Notifications, Personal Settings & Troubleshooting Missing Email 8.4 Mail Handlers: Creating Issues and Comments from Email
9 Chapter 9: JQL, Filters, Dashboards & Bulk Operations
9.1 JQL Fundamentals, Clauses, Operators & History (WAS / CHANGED) 9.2 Advanced JQL Functions & Dynamic Date Searches 9.3 Filter Permissions, Shared Filters & Filter Subscriptions 9.4 Dashboard Layouts, the Default Dashboard, Sharing & Essential Gadgets 9.5 Bulk Operations: Edit, Move, Transition, Delete & Watch
10 Chapter 10: System Administration
10.1 Global UI Features: User Defaults, Look and Feel, Announcement Banner & Default Dashboard 10.2 Statuses, Resolutions, Priorities & Sub-tasks: Global Configuration 10.3 Global Settings: Time Tracking, Issue Linking, Attachments & Application Links 10.4 System Backup, Restore & Data Import
8.4 Mail Handlers: Creating Issues and Comments from Email
Key Takeaways Explain This Topic AI
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.
Last updated: September 2026
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.