User Tools

  • Logged in as: anonymous (anonymous)
  • Log Out

Site Tools


mantisbt:plugins:emailreporting

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

  1. /mantisbt/plugins/EmailReporting/scripts/bug_report_mail.php
  2. /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)

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 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

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 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

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_respect_permissions

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.

mail_add_bug_reports

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

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 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_ignore_auto_replies

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/

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_add_complete_email_ext

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”.

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

Please read this “Don’t turn off CURLOPT_SSL_VERIFYPEER, fix your PHP configuration

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”

References

mantisbt/plugins/emailreporting.txt · Last modified: 2022/10/23 09:12 by SL-Gundam

Driven by DokuWiki