This is an old revision of the document!
Table of Contents
EmailReporting Plugin
Overview
The EmailReporting plugin allows you to report an issue in Mantis by sending an email to a particular mail account.
Features
- Create an issue
- Add notes to an existing issue
- Add attachments
- Filter email accounts
Requirements
EmailReporting v0.10.0 and later versions
- MantisBT 1.3.0 or higher
EmailReporting v0.9.x
- MantisBT 1.2.6 until 1.3.99
Optional
- PHP 7.0 is supported from EmailReporting 0.9.2 and higher
- PHP 7.1 is supported from EmailReporting 0.10.0 and higher
EmailReporting v0.8.4 and earlier versions
- MantisBT 1.2.0 until 1.2.5
All versions
- Ability to set scheduled / cron jobs on the webserver
- /api/soap/mc_file_api.php is required for EmailReporting to function properly
Includes thirdparty packages
PEAR
Libraries
Download
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
Source code
EmailReporting plugin is hosted in GitHub along with other plugins. GitHub URL: https://github.com/mantisbt-plugins/EmailReporting
Support
Forum
Please use forum to get help in installing and using EmailReporting plugin. Visit EmailReporting Forum.
Bug Tracker
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)
Compatibility issues
TriggerClose
Currently it seems EmailReporting is having compatibility issues with another plugin called “TriggerClose”
See this MantisBT issue for further information: 20399
Microsoft Exchange mail servers
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.
Documentation
Setting up a scheduled / cron job for 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
- /mantisbt/plugins/EmailReporting/scripts/bug_report_mail.php
- /mantisbt/plugin.php?page=EmailReporting/bug_report_mail
MantisBT Configuration options
Maximum attachment size
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 |
---|---|---|
PHP | upload_max_filesize | http://php.net/manual/en/ini.core.php#ini.upload-max-filesize |
PHP | post_max_size | http://php.net/manual/en/ini.core.php#ini.post-max-size |
MantisBT | $g_max_file_size | https://www.mantisbt.org/manual/admin.config.uploads.html |
MySQL | max_allowed_packet | http://dev.mysql.com/doc/refman/5.7/en/packet-too-large.html |
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.
"From" address for MantisBT Notification emails
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
Readonly threshold for 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
Configuration options
The sections below are reached the easiest by clicking on the [?] next to the option within the EmailReporting interface
mail_secured_script
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
mail_secured_ipaddr
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
mail_delete
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
mail_max_email_body
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 65535 bytes because that used to be the default for old MantisBT versions prior to mid 2007 using MySQL. 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
mail_max_email_body_text
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
mail_max_email_body_add_attach
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
mail_use_reporter
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
mail_fallback_mail_reporter
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.
mail_reporter_id
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
mail_auto_signup
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
mail_preferred_username
Name: Preferred username for new user creations
Description: Set the preferred username for new user accounts that are created by EmailReporting. Possible options are:
Option | Result |
---|---|
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 |
mail_preferred_realname
Name: Preferred realname for new user creations
Description: Is mostly the same as Preferred username for new user creations but has one extra option
Option | Result |
---|---|
Full “From” address | Will use the complete “From” field from the email. The same limitation applies as for “Email address” |
mail_disposable_email_checker
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
mail_add_bug_reports
Name: Create new issues
Description: Whether or not to allow the creation of new issues by EmailReporting. If this is disabled and an email cannot be added as a note, the email will be deleted from the mailbox without further processing
mail_add_bugnotes
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
mail_rule_system
Name: Rule system
Description: This is a system that is currently in development. Best comparison is probably the rule wizard in Microsoft Outlook
mail_parse_html
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
mail_email_receive_own
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
mail_save_from
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
mail_save_subject_in_note
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
mail_subject_id_regex
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
ID Search | Explanation |
---|---|
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 [123] anything here” | Balanced |
“anything here [ 123] anything here” | Relaxed |
“anything here [ 123 ] anything here” | Relaxed |
mail_use_message_id
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
mail_add_users_from_cc_to
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
mail_use_bug_priority
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
mail_bug_priority
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”
mail_block_attachments_md5
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
mail_block_attachments_logging
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
mail_strip_signature
Name: Strip signature from email body
Description: Strip an email signature from the issues and 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)
mail_strip_signature_delim
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
mail_nosubject
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.
mail_nodescription
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?
mail_remove_replies
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”
mail_remove_replies_after
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
mail_strip_gmail_style_replies
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.
mail_remove_mantis_email
Name: Remove MantisBT notification emails from replies
Description: Will search for the MantisBT notification email and remove as much as possible from the email
mail_removed_reply_text
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
mail_debug
Name: Debug mode
Description: Debug mode will show more information about whats going on when EmailReporting is processing a email.
mail_debug_directory
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 |
mail_add_complete_email
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
mail_debug_show_memory_usage
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
Mailbox settings
enabled
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
description
Name: Description
Description: Helpful description of the record so that you easily find it again
mailbox_type
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” |
hostname
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
port
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)
Mailbox type | Normal | Encrypted |
---|---|---|
POP3 | 110 | 995 |
IMAP | 143 | 993 |
encryption
Name: Connection encryption
Description: Here you select the encryption you want to use.
Encryption | Default port | Comments |
---|---|---|
None | Normal | No encryption |
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 |
ssl_cert_verify
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
erp_username
Name: Username
Description: The username of the mailbox on the mail server
erp_password
Name: Password
Description: The password of the mailbox on the mail server. It is stored with backwards encryption so is not really that secure
auth_method
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
Mailbox type | DIGEST-MD5 | CRAM-MD5 | APOP | PLAIN | LOGIN | USER |
---|---|---|---|---|---|---|
POP3 | Disabled | Yes | Yes | Yes | Yes | Yes |
IMAP | Yes | Yes | No | No | Yes | No |
imap_basefolder
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
imap_createfolderstructure
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
project_id
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.
global_category_id
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.
select_mailbox
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
Action | Explanation |
---|---|
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”