The EmailReporting plugin allows you to report an issue in Mantis by sending an email to a particular mail account.

• Create an issue
• Add notes to an existing issue
• Add attachments
• Filter email accounts

• MantisBT 1.3.0 or higher

• MantisBT 1.2.6 until 1.3.99

• PHP 7.0 is supported from EmailReporting 0.9.2 and higher
• PHP 7.1 is supported from EmailReporting 0.10.0 and higher

• MantisBT 1.2.0 until 1.2.5

• Ability to set scheduled / cron jobs on the webserver
• /api/soap/mc_file_api.php is required for EmailReporting to function properly

• core pear files
• Auth_SASL
• Mail_mimeDecode
• Net_IMAP
• Net_POP3
• Net_Socket

• PHP Simple HTML DOM Parser
• Markdownify
• EmailReplyParser

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

• Net_IMAP numMsg function does not work. Replaced with getListing
• Net_IMAP getListing function returns an error when there are no emails in an IMAP folder. Added examineMailbox to prevent this error and check whether there are emails in the folder
• After 10 errors Exchange will ignore the connection and any further commands will fail with “, ”. 10 errors or more can happen when imap_createfolderstructure is ON and there are more then 10 projects to process.

README

Changelog

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

1. /mantisbt/plugins/EmailReporting/scripts/bug_report_mail.php
2. /mantisbt/plugin.php?page=EmailReporting/bug_report_mail

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)

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 because of “Maximum size of the description or note being added to the issue” 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:

Name: Preferred realname for new user creations

Description: Is mostly the same as Preferred username for new user creations but has one extra option

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:

• “MantisBT Formatting” plugin needs to be enabled.
• “Markdown Processing” needs to be turned on in the “MantisBT Formatting” plugin
• “Parse HTML emails” needs to be turned on in EmailReporting

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

Here are some example to give you an idea of what the results will be

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

EmailReporting will check the MantisBT configuration options $g_allowed_files and $g_disallowed_files so you can also block based on extension if you so wish

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.

If you block .txt files using $g_allowed_files and $g_disallowed_files then this file will be blocked as well

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:

• X-Autoreply
• X-Autorespond
• auto-submitted with a value of “auto-replied”

Based on: https://www.jitbit.com/maxblog/18-detecting-outlook-autoreplyout-of-office-emails-and-x-auto-response-suppress-header/

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

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: Extension used for the complete email attachment

Description: This will allow you to change the extension used for the attachment (see “Add the complete email into the attachments”). Popular extensions are “txt” and “eml”.

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

Name: Enabled

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

Name: Description

Description: Helpful description of the record so that you easily find it again

Name: Mailbox type

Description: Currently only IMAP and POP3 are supported.

Name: Hostname

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.

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”

Name: Username

Description: The username of the mailbox on the mail server

Name: Password

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

Entries in the dropdown box prepended with a “*” have the Enabled setting set to “No”

1. Reporting via Email