This is an old revision of the document!
The EmailReporting plugin allows you to report an issue in Mantis by sending an email to a particular mail account.
The stable releases can be downloaded from the GitHub downloads page: https://github.com/mantisbt-plugins/EmailReporting/releases
The development versions (e.g. 0.9.0-DEV) are not meant for production environments. Use at your own risk
EmailReporting plugin is hosted in GitHub along with other plugins. GitHub URL: https://github.com/mantisbt-plugins/EmailReporting
Please use forum to get help in installing and using EmailReporting plugin. Visit EmailReporting Forum.
To report an issue or feature request for EmailReporting plugin, visit Mantis BugTracker. (Make sure that you select the correct project from the drop-down)
Currently it seems EmailReporting is having compatibility issues with another plugin called “TriggerClose”
See this MantisBT issue for further information: 20399
Exchange has several IMAP issues for which we have created workarounds in EmailReporting
EmailReporting requires that a scheduled / cron job is set up so that it can periodically retrieve emails from mailboxes
In MantisBT 1.3.x access to the plugins folder is blocked through a browser. So of the methods shown below, method 1 should be used from the command line while method 2 should be used if your hosting environment accesses the job through a webserver
It's possible to run into database query errors if you've incorrectly setup some maximum size settings in PHP, and MantisBT
EmailReporting and MantisBT use the following to decide what the maximum attachment size is that should be supported (MySQL variable is not used for this decision)
|Where||Configuration option||Help information|
The PHP variables should not affect EmailReporting but we wanted to make EmailReporting behave the same as MantisBT as much as possible so we included them.
As for the MantisBT $g_max_file_size. That one is very important if you've setup EmailReporting to save attachments in the database instead of on the disk. MySQL/MariaDB for example also have limits on the amount of data that is allowed in one insert statement which could generate an error (see max_allowed_packet above). If max_allowed_packet is set too low, this could result in the error "MySQL server has gone away".
Make sure you set $g_max_file_size to a slightly lower value then your server setup supports (alternatively increase the other mentioned values to be higher then $g_max_file_size and adjust any not mentioned requirements for your setup to handle the increased size). If you need to handle big attachments, make sure MantisBT stores them on the disk, not in the database.
It is advised to set $g_from_email and $g_return_path_email in your MantisBT configuration file to an email address that is being monitored by EmailReporting so that emails received there can be converted into notes.
You do not need to set these values per project. Notes will be imported to any issue to which they are related without ever looking at the project in which the issue resides. So “Select a project” and “Select a category” are only applicable for newly created issues
If an issue passes the readonly threshold ($g_bug_readonly_status_threshold) it cannot be reopened again under normal conditions.
We advise you to set this configuration option to CLOSED (default is RESOLVED)
If you keep the default setting EmailReporting will not be able to reopen or add notes to issues passed the readonly threshold. Instead it will create a new issue with a relation to the old one
The sections below are reached the easiest by clicking on the [?] next to the option within the EmailReporting interface
Name: Block this script from running via a webserver (recommended = “Yes”)
Description: Protects the scripts/bug_report_mail.php script so that it can't be executed by some random visitor
MantisBT 1.3.x added extra security by using .htaccess and web.config files to restrict access to this folder. If you must run bug_report_mail.php through a webserver, please use /plugin.php?page=EmailReporting/bug_report_mail
Name: Only allow access to bug_report_mail from this IP address
Description: This allows restricting access to bug_report_mail when invoked through a webserver to a single IP address
Name: Delete processed email from the mailbox
Description: Whether or not to delete processed emails from the mailbox. See “Mailbox type” for some more info about its effects
Do keep in mind that this option was not meant for archiving purposes. The more emails there are in the mailbox, the higher the run-time for the script everytime it is run. This is especially true for IMAP
Name: Maximum size of the description or note being added to the issue
Description: This is the maximum size allowed for the description or a note. The choice was made to make the default 60000 bytes because 65535 used to be the default column length for old MantisBT versions prior to mid 2007 using MySQL. Since we need some overhead we lowered 65535 to 60000. New MantisBT installations after mid 2007 will be able to store upwards of 1 million bytes. Even more depending on which database backend you use. As updating the schema does not update the column size in question this would be a good default that would not cause problematic issues
Of course you can increase this if you want. Just make sure that your MantisBT database is using a column type in which this will fit. This is usually the case if you MantisBT installation was created using MantisBT 1.1.x or later
Name: Use this text if the description or note has been truncated
Description: If a description or note is truncated this text will be added to the end
Name: Add the complete description or note as an attachment incase it was truncated
Description: Enable this and if a description or note is truncated, the complete description or note before it was truncated will be added as an attachment to the issue. This might fail if the attachment size is also exceeded.
The filename will be description.txt or note.txt. If the filename already exists it will be prepended with a number
Name: Use only default reporter user for issues created by email
Description: This will force the use of “The default / fallback reporter user for issues created by email”. The sender of the email will be ignored
Name: Enable fallback to default reporter
Description: You can disable the fallback to “The default / fallback reporter user for issues created by email”. Keep in mind that if EmailReporting cannot find a proper user for the new issue or note and this settings is disabled it will result in an email that will be ignored/deleted without it resulting in a new issue or note.
Name: The default / fallback reporter user for issues created by email
Description: This is the default / fallback reporting user if all other attempts for finding a better user account have failed. It is advised that you make sure this user exists and is enabled so that emails have somewhere to go as a backup
Permission issue: The Mail Reporter user created by EmailReporting upon installation will have Global Reporter permissions. If all of your projects are private, Global Reporter permissions will not allow this Mail Reporter user access to any projects if private_project_threshold is set to a permission level higher then Reporter. This means that it cannot function as the default / fallback reporter
So in short. Make sure the Mail Reporter user has access to the necessary projects where EmailReporting will be creating issues and notes
Name: Signup new users automatically (possible security risk!, see documentation)
Description: New user accounts will be automatically created. Be advised that this might pose a security risk if the email address in question is available from the outside and spam can be received on it
Name: Preferred username for new user creations
Description: Set the preferred username for new user accounts that are created by EmailReporting. Possible options are:
|Email address||Will strip the email address of problematic characters and restrict its length if necessary|
|Email address without the domain name||Will use the part of the email address before the @. The same limitation applies as for “Email address”|
|From LDAP||If properly set up in MantisBT, EmailReporting is able to collect the name of the user in question from LDAP. The name field that is retrieved can be set in the MantisBT config_inc.php file with the configuration option ldap_realname_field|
|Name||Uses the name of the user that is supplied by the “From” field of the email|
Name: Preferred realname for new user creations
Description: Is mostly the same as Preferred username for new user creations but has one extra option
|Full “From” address||Will use the complete “From” field from the email. The same limitation applies as for “Email address”|
Name: Disposable email address checker of MantisBT
Description: With this you can disable MantisBT internal disposable email checker. This will only be changed for EmailReporting, not for the rest of MantisBT
Name: Check user permissions
Description: Whether or not EmailReporting should check the permission of the user for adding new issues, notes or attachments.
The email will be ignored if a permission check fails for notes or issues, not for attachments. When processing finishes Delete processed email from the mailbox will be respected.
The default is to ignore permissions because EmailReporting works with the intend to “Process at all costs”. If you turn this on it is possible that you will lose emails so should only consciously be turned on.
Name: Add new issues
Description: Whether or not to allow the creation of new issues by EmailReporting. If an email cannot be added as a new issue, the email will be ignored without further processing and respect Delete processed email from the mailbox
Name: Add notes
Description: Whether or not to allow the creation of new notes by EmailReporting. If this is disabled what would have been notes are instead added as new issues
Name: Rule system
Description: This is a system that is currently in development. Best comparison is probably the rule wizard in Microsoft Outlook
Name: Parse HTML emails
Description: If an HTML email is received and a plaintext version is not available, this decides whether or not to convert the HTML to plaintext using PHP Simple HTML DOM Parser. If this is disabled the body will be left empty in this situation. From EmailReporting 0.9.1 onward it will be added as an attachment if this is turned off
With MantisBT 2.1.x, markdown support was added to MantisBT. EmailReporting 0.10.0 and later versions support converting a html email to markdown. The requirements are:
In general EmailReporting prefers the plaintext versions of emails if it can find them. But if markdown support is enabled, EmailReporting prefers the html email version.
Note for MS Exchange users: Exchange seems to think its smart and might have decided for you that you do not need the plaintext email. Thereby only providing the HTML version. You could modify your Exchange environment so that it also provides the plaintext version to EmailReporting. The result is often a lot better then converting a html email to plaintext, though html to markdown should get an even better result
Check bullet point 7 here for POP3: View or Configure POP3 Properties: Exchange 2010 Help
Check bullet point 7 here for IMAP: View or Configure IMAP4 Properties: Exchange 2010 Help
Name: Should users receive emails for their own actions (N/A if email_receive_own = ON)
Description: MantisBT has an option “email_receive_own” whereby users will receive notifications of there own actions. Usually not really handy in MantisBT but incase of EmailReporting this means that users will receive confirmation of an issue or note that has been added to MantisBT based on the email they sent.
This option allows you to turn this option on only for EmailReporting while the rest of MantisBT will work as if it was still turned off
Name: Write the sender of the email into the issue report/note
Description: This will write the “From” field of the mail in note or issue that will be created by EmailReporting
Name: Write the subject of the email in the note
Description: This will write the subject of the email in the note. This is not done for new issues as it is already stored in the Summary of the new issue
Name: What kind of search should be used to find the issue id in the subject
Description: This will give you three options so that you can adjust it to a way that suits your use case
|Strict||This is the default option. Only accepts issue id's where the subject line is in the style of MantisBT Notification emails|
|Balanced||A nice balance between Strict and Relaxed. For examples see below|
|Relaxed||The most relaxed option. For examples see below|
Here are some example to give you an idea of what the results will be
|Subject line example||Minimum required “ID Search” for acceptance|
|“anything here [anything 123] anything here”||Strict|
|“anything here [anything 000000000000123] anything here”||Strict|
|“anything here [anything 0000123] anything here”||Strict|
|“anything here  anything here”||Balanced|
|“anything here [ 123] anything here”||Relaxed|
|“anything here [ 123 ] anything here”||Relaxed|
Name: Use Message-ID in Mail header to identify notes
Description: Emails have unique id's. These can be used to figure out which emails are replies to other emails. This could be useful if somebody cc's your EmailReporting mailbox as part of a email discussion and you don't want every reply to create its own issue
Name: Add users to issue monitoring list from Cc and To fields in mail header
Description: This will add the users that were in the CC or TO fields as Monitors to the issue. These users already need to exist as a user in MantisBT as an account will not be created for them automatically
Name: Look for priority header field
Description: Whether or not you want EmailReporting to try to get the priority of the email and convert it to an equivalent priority in MantisBT. See “Classify bug priorities” for the conversion table
Name: Classify bug priorities
Description: This is the conversion table for the email priorities to MantisBT priorities conversion. Also see “Look for priority header field”
Name: Block attachments matching these MD5 hashes
Description: With this you can block certain attachments in emails from being added as attachments in MantisBT. This could be useful if you have images in your email signatures
Name: Log blocked attachments in the “Rejected files” list
Description: This will allow you to monitor whether the Block attachments matching these MD5 hashes works as intended.
Name: Strip signature from email body
Description: Strip an email signature from notes. It will search for a delimiter (see “Delimited by”) which will mark the start of the signature. Anything below it will be deleted (this includes any other email parts)
Name: Delimited by
Description: The delimiter thats used by “Strip signature from email body” for the search for the start of the signature
It should be the only thing on a single line for it to work
Name: Use this text if no subject is found in the email
Description: Self explanatory i believe. Some users just don't like filling in subject lines in emails. How lazy.
Name: Use this text if no description is found in the email
Description: Self explanatory i believe. Some users just want to add some attachments to an existing issue. In that case a note is not added but the attachments are. But if this happens for a newly created issue you might wonder what caused it since you would expect the user to inform you of what the problem… maybe he wrote it all in the subject line?
Name: Ignore auto-reply emails
Description: Ignore auto-reply emails like out-of-office replies.
Check if the email is an out of the office auto reply by checking the following fields:
Name: Remove all replies from notes
Description: Will only add the most recent reply in the email chain and ignore the rest. This is based on “Use this text to identify the start of a reply”
Name: Use this text to identify the start of a reply
Description: This will mark the start if a reply. Also see Remove all replies from notes
Name: Remove Gmail style replies (English only) from notes (mail_remove_replies should be YES)
Description: Whether or not to look for gmail style replies headers. Will remove anything below it if found.
Name: Remove MantisBT notification emails from replies
Description: Will search for the MantisBT notification email and remove as much as possible from the email
Name: Use this text if replies have been removed from the email
Description: This text will be added in place of a reply that has been removed by EmailReporting
Name: Debug mode
Description: Debug mode will show more information about whats going on when EmailReporting is processing a email.
Name: Save email contents to this directory if debug mode is activated
Description: EmailReporting will write 2 files to this directory. EmailReporting developers might ask for these files to debug any issues you are reporting
|Filename starts with||Contains|
|raw_msg_||The raw MIME content of the email as the provided to EmailReporting. This is useful if MIME decoding errors need to be debugged|
|parsed_msg_||This contains a PHP array after EmailReporting processed the raw MIME content. This is useful to see the result of the MIME decoding done by EmailReporting and check any flaws that might need to be corrected|
Name: Add the complete email into the attachments
Description: This will add the raw MIME content (see “Save email contents to this directory if debug mode is activated”) as an attachment to the issue in question
Name: Show the memory usage at various stages of the email processing process
Description: This will show memory usage during several stages of the email processing. This was mostly added to improve memory usage and should normally be disabled
Description: Enable or disable the selected record. This way you are not required to delete records which you are still testing or just want to disable temporarily
Description: Helpful description of the record so that you easily find it again
Name: Mailbox type
Description: Currently only IMAP and POP3 are supported.
|Mailbox type||Folder||Reads||Processed emails|
|POP3||Inbox folder||Only unread emails||Are marked as read. They are deleted based on “Delete processed email from the mailbox”|
|IMAP||Depends on the “Basefolder (optional)”||All emails except those that are marked as deleted||Are marked as deleted. They are expunged based on “Delete processed email from the mailbox”|
Description: Can either be a hostname or an ip address of the mail server. At the moment there have not been any tests on ipv6 addresses so its unclear how well that will work but its likely there will be some issues
Name: TCP port (optional)
Description: This is the port number of the mail servers POP3 or IMAP service. If you leave this empty the default port numbers are used (see below)
Name: Connection encryption
Description: Here you select the encryption you want to use.
|SSL||Encrypted||Will automatically decide what version of SSL to use|
|SSLv2||Encrypted||Force SSLv2 encryption. It is advised this is only used for specific requirements|
|SSLv3||Encrypted||Force SSLv3 encryption. It is advised this is only used for specific requirements|
|TLS||Encrypted||Will automatically decide what version of TLS to use|
|TLSv1.0||Encrypted||Force TLSv1.0 encryption. It is advised this is only used for specific requirements|
|TLSv1.1||Encrypted||Force TLSv1.1 encryption. It is advised this is only used for specific requirements|
|TLSv1.2||Encrypted||Force TLSv1.2 encryption. It is advised this is only used for specific requirements|
|STARTTLS||Normal||Only supported for IMAP. Will add encryption after connection has already been set up. Will only work if the mail server supports it, otherwise the connection will stay unencrypted|
Name: Verify SSL certificate
Description: PHP 5.6 enables by default SSL verification when encryption is applied to the connection. With this you can manipulate that behavior as its not guaranteed that this works properly. Most likely reason that it does not work is if PHP is unable to access the OS-managed cert stores and the OpenSSL variables (openssl.cafile OR openssl.capath) in PHP configuration file are not properly set
Please read this “Don’t turn off CURLOPT_SSL_VERIFYPEER, fix your PHP configuration”
Description: The username of the mailbox on the mail server
Description: The password of the mailbox on the mail server. It is stored with backwards encryption so is not really that secure
Name: Authentication method
Description: Supports various authentication methods that might be required for authentication to your mail server. Usually the default will suffice. Below you will find a table with the authentication methods supported towards POP3 and IMAP
Name: Basefolder (optional)
Description: This is the IMAP folder from which EmailReporting will read emails. If left empty it will default to the Inbox folder
Name: Create project subfolder structure
Description: If you set this to “Yes” EmailReporting will create a sub folder for every project in MantisBT. Any emails in those sub folders will be imported into the corresponding project. In this case it will not process the Basefolder, only the subfolders of the Basefolder.
If you set this to “No” only the Basefolder will be processed.
Keep in mind that some IMAP servers do not allow emails in a folder when that folder contains subfolders
Name: Select a project
Description: Select the project where issues should be imported to. This will be ignored if “Create project subfolder structure” is enabled for IMAP mailboxes
Only applicable to newly created issues, not for notes.
Name: Select a category
Description: It is advised to select a global category here (especially if “Create project subfolder structure” is enabled for IMAP mailboxes). But its possible to also select other categories even though they are not part of the selected project even though this might create other issues in MantisBT.
Only applicable to newly created issues, not for notes.
Name: Select mailbox
Description: Here you can select a mailbox and perform various actions on it. I believe most actions will be self explanatory but here they are
|Add||Default action and will allow you to add new mailboxes|
|Copy||Copy an existing mailbox|
|Edit||Edit an existing mailbox|
|Delete||Delete an existing mailbox|
|Test||Test a mailbox. This will test as much as possible without actually processing any emails in the mailbox|
|Complete test||This will fully process a individual mailbox. Any emails will be imported to new issues or notes|
Entries in the dropdown box prepended with a “*” have the Enabled setting set to “No”