TagAlong

TagAlong is a Kanboard plugin that supercharges email handling and groups every email for a task into one thread, points Reply-To to the reply-by-email address, and lets admins customize the email subject format.

It can also filter out autoreplies (like out-of-office messages), email signatures and quoted text from incoming emails.

TagAlong requires Mailmagik. When installed together, "[CommentOnTask#12345]" is appended to the subject of outgoing task and comment notification emails (e.g. [Test] New comment on task #12345 [CommentOnTask#12345]), so an email reply from a project member becomes a comment on a task.

Screenshots

Settings -> Email settings -> TagAlong sets the email subject formats and the incoming mail filters.

Quick start

1. Copy the TagAlong folder into Kanboard's plugins/ directory.
2. Customize the email subject formats and filters in Settings -> Email settings -> TagAlong (options include Remove signatures from emailed comments, Remove quoted text from emailed comments, and Ignore automatic replies and email from the Mailmagik mailbox).
3. TagAlong needs Mailmagik, so install it and then:
   • Configure Mailmagik at Settings -> Email settings -> Task- and Comment-Creation and select "Parse from the SUBJECT field"*
   • On each project that should accept replies, go to Configure this project -> Automatic actions and add Mailmagik's "Automatically Convert Emails to Comments" action with "Trigger Mailmagik's mail fetching".
   • In Kanboard's Settings -> Email settings set the sender email to the mailbox that Mailmagik uses, and replies will turn into task comments (see Reply-To handling).

*Mailmagik's "TO" field mode is unsupported. Don't use Mailmagik's "TO" field mode. Friends don't let friends use Mailmagik's "TO" field mode.

INSTALL.md covers the requirements, removal, and compatibility.

Email subject formats

TagAlong adds a setting in Settings -> Email settings for Kanboard's task notifications, and a second one for NotifyMe emails that shows only when NotifyMe is installed. An empty field keeps the default email subject.

Placeholder	Value
{project}	Project name
{task_id}	Task number
{task_title}	Task title
{event}	Short label such as "New comment" or the full title for an event with no label
{title}	Kanboard's full title, such as "New comment on task #12345". In NotifyMe emails it is the event's label, such as "New comment"

Kanboard's default is [{project}] {title}. NotifyMe emails use {project}: {task_title} (#{task_id}) {event} until you save the setting, and saving it empty keeps NotifyMe's own [{project}] {task_title} (#{task_id}). The reply token is always appended to the subject no matter what the format says.

Each emailed comment starts with the subject line, for example Re: [Test] New comment on task #12345 since Mailmagik makes the subject the comment's first line.

Email threads

Every email whose subject ends in a reply token gets In-Reply-To and References pointing at one ID per task (task-ID.tagalong@<sender domain>), so email clients that thread by those headers group "New comment", "Task updated", and the rest under the task. Gmail also needs matching email subjects, so it only groups emails with the same event label.

TagAlong copies Kanboard's three email transports (smtp, sendmail, and mail) and adds support for the headers. It does this in onStartup(), so it also replaces a transport another plugin set in its initialize(). A transport that was already in use when TagAlong starts can't be replaced, and that failure is logged and leaves the transport as it was.

Incoming email filters

Everything below removes text from incoming email before Mailmagik saves it, and the removed text isn't kept anywhere in Kanboard. The original email stays in the mailbox (either marked as read or deleted if Mailmagik is set to delete processed email).

Reply-above line (recommended)

Set a Reply-above line in Settings -> Email settings -> TagAlong, e.g.: --Reply above this line--

TagAlong then:

1. Puts that line at the top of every task email that can be replied to.
2. Trims an emailed comment from that line on, wherever it is in the email, together with the "On ... wrote:" line or Outlook From: / Sent: block the mail client put just above it.

This line works regardless of mail client's quote format, including for replies with quotes that don't have > marks, which the quoted-text filter below leaves alone.

• Empty (the default) turns both sides off.
• The match ignores > quote marks, formatting, case, repeated spaces, and dash changes, so a client that turns -- into a dash or quotes the line with > still matches.
• If the line is the first thing in the email, because the reply was typed below the quote, nothing is trimmed.
• Replies to emails sent before the line was set, and clients that drop it, are handled by the filters below.
• Trim incoming comments after these lines adds more lines, one per line: plain text matches a whole line ignoring case, and /pattern/ is a regular expression. The first match and everything after it is removed.
• Only emailed comments are trimmed, not the bodies of new tasks.

The filters in this section run in this order: reply-above line, quoted text, -- signatures, then the signature list.

Other filters

There are three checkboxes in Settings -> Email settings, and all off by default:

1. Ignore automatic replies and email from the Mailmagik mailbox. Mail with Auto-Submitted (anything but no), X-Auto-Response-Suppress: OOF or All, or Precedence: bulk, auto_reply, or junk is marked as read and never becomes a task or comment. So is email sent from Mailmagik's own address, its login, or Kanboard's sender address.
2. Remove quoted text from emailed comments. The cut starts at an "On ... wrote:" line that has a digit, an "Original Message" line, an Outlook From: / Sent: header block, or a > line, and runs to the end. An "On ... wrote:" or > line only counts when everything after it is quoted, so an inline or bottom-posted reply is kept whole. Text typed directly above a quoted block is kept apart from the quote's >.
3. Remove signatures from emailed comments. The cut starts at the first standard -- line.

TagAlong can also filter out email signatures (like the scourge that is "Sent from my iPhone") in emailed comments and in the bodies of tasks created from email:

• The last matching line and everything after it is removed, but only when the match is found in the last 10 non-empty lines of the email.
• List only the first line of an email signature. Formatting is ignored when matching: bold, italics, and link markup are removed from a line, too.
• Plain text matches a whole line exactly (ignoring case), and /pattern/ is a regular expression tested against each line.
• TagAlong includes a few common lines from phone email clients and Outlook.
• The filters run in order: reply-above line, quoted text, then -- email signatures, then the list.
• An invalid pattern is skipped and logged.
• Inline images aren't embedded. Mailmagik's task attribute parsing reads that text in place of the plaintext part.

Reply-To handling

Replies go to the email's Reply-To address, and Kanboard sets that to the user who triggered the email. Replies need to go to Mailmagik's mailbox instead, so TagAlong sets Reply-To to Kanboard's sender address on the notifications it tags. With no sender address set, Kanboard's behavior is unchanged.

Works with NotifyMe

NotifyMe calls the notifyme:email:subject hook with subject, task_id, project_name, task_title, event_name, and action. TagAlong applies the NotifyMe subject format and appends the token. NotifyMe's notifyme:email:reply_to hook gets the sender address.

What it overrides

TagAlong doesn't change any Kanboard core files or any other plugin's files. It replaces these at runtime:

Part	Owner	Replaced with	Without Mailmagik
Email notification type (MailNotification)	Mailmagik, which replaced Kanboard's	Subclass adding the email subject format, token, and Reply-To (getMailSubject(), notifyUser())	Not registered
mailHelper helper	Mailmagik	Subclass adding the incoming email filters (getUnseenMails(), getItemId())	Not registered
smtp, sendmail, and mail transports on the emailClient service	Kanboard, or NotKanboard when it owns emailClient	Copies of core's sendEmail() adding thread headers	Not registered
Settings, Email settings form	Kanboard	Adds a TagAlong fieldset through the template:config:email hook	Still shown

The transport copies duplicate core 1.2.54's sendEmail(). Recheck them after a Kanboard update.

Limitations

• Mailmagik really needs to be in "SUBJECT" mode. In "TO" mode, email threads and email tokens aren't very useful because replies to the Kanboard sender address just stay unread in the Mailmagik mailbox. The filters will work in either mode, but "TO" mode also risks adding countless new email addresses to the address books in Kanboard users' email clients (one address book entry per project task ID per person).
• TagAlong adds the reply token to the end of the subject. If the subject already contains CommentOnTask#ID (because, for example, it's in a task title), TagAlong changes it to CommentOnTask # first. This prevents a title from sending email replies to a different task.
• Anything after the last matching filter line that's in the last 10 lines of an email gets filtered and removed (e.g. a P.S. under "Sent from my iPhone").
• With the autoreply filter on, email from Kanboard's sender address, Mailmagik's address, or Mailmagik's login is discarded. If one of these is a person's own address, their replies are dropped, too, so use a dedicated mailbox.
• The quoted text feature looks for text in emails that starts with "On " and ends with "wrote:" with at least one digit in between, so any date format works. Other languages (like German's "Am ... schrieb") aren't recognized. Contributions are welcome: fork TagAlong on GitHub and create a pull request.
• TagAlong supports Mailmagik 1.6.1, so check for an update to TagAlong if Mailmagik also gets an update.
• Mailmagik 1.6.1 has a one-character bug that allows any Kanboard user to add a comment to any task in any project, so chime in on Mailmagik issue 55 to help get it fixed.

Compatibility

• Kanboard >= 1.2.20
• Mailmagik 1.6.1
• No database changes

Other plugins

TagAlong works by itself and plays nicely with several other plugins by the same author:

• BusyBee adds one-click questions about your projects and tasks, such as "What is late?" and "What is blocked?", to the top of Kanboard's My dashboard pages. If SortaFolders is installed, the same questions also show at the top of its My folders page.
• CommentTater lets you update a task's fields while posting a comment. Changes made to the task from the comment are shown on the posted comment and are included in Kanboard email notifications, too.
• NotifyMe emails you about your own actions in a project, adds a vacation mode, notifies users of failed login attempts, and gives admins control of how many notifications are shown in the Notifications menu. Its email footer uses NotKanboard's name when both are installed.
• NotKanboard helps whitelabel Kanboard and replaces "Kanboard" in page titles, outgoing emails, and a few other places with your own product name.
• SortaFolders sorts projects into folders. Kanboard doesn't let you group projects together or classify a project by putting it in another project, so SortaFolders adds nestable folders up to 5 levels deep and a dedicated My folders page on your dashboard that lists your projects by folder.

License

GNU General Public License v2.