Email Integration for Mattermost
Clone or download
Latest commit cda5684 Oct 25, 2018

README.md

mattermail icon MatterMail

MatterMail is an integration service for Mattermost, MatterMail listen an email box and publish all received emails in channels or users in Mattermost.

Build Status Coverage Status

mattermail screenshot

Install

Download the Latest Version

Usage

  1. You need to create an user in Mattermost server and you can use MatterMail icon as profile picture.

  2. Get the Team and Channels and check if the user has permission to post in these channels

  3. Edit the file config.json

  4. Execute the command to put in background

./mattermail > /var/log/mattermail.log 2>&1 &

Migrate configuration

To upgrade the config.json to new version using this command:

./mattermail migrate -c ./config.json > ./new_config.json

Configuration

Minimal configuration:

{
    "Directory": "./data/",
    "Profiles":[
        {
            "Name":              "Orders",
            "Channels":          ["#orders"],

            "Email":{
                "ImapServer":        "imap.example.com:143",
                "Username":          "orders@example.com",
                "Password":          "password"
            },

            "Mattermost":{
                "Server":   "https://mattermost.example.com",
                "Team":     "team1",
                "User":     "mattermail@example.com",
                "Password": "password"
            }
        }
    ]
}

Directory

Location where the cache is stored, default value is ./data/

Profiles

You can set multiple profiles using different names

Field Type Default Obrigatory Information
Name string Name of profile, used to log
Channels array List of channels where the email will be posted. You can use #channel or @username
Email object Configuration of Email (details)
Mattermost object Configuration of Mattermost (details)
MailTemplate string Template used to format message to post (details)
LinesToPreview int 10 Number of email lines that will be posted
Attachment boolean true Inform if attachments will be posted in Mattermost
Disabled boolean false Disable this profile
RedirectBySubject boolean true Inform if redirect email by subject (details)
Filter object Filter used to redirect email (details)

Email

Email configuration, used to access IMAP server

Field Type Default Obrigatory Information
ImapServer string Address of imap server with port number ex: imap.example.com:143
Username string Email address or username used authenticate on email server
Password string Password used authenticate on email server
StartTLS boolean false Enable StartTLS connection if server supports
TLSAcceptAllCerts boolean false Accept insecure certificates with TLS connection
DisableIdle boolean false Disable imap idle and check email after 1 minute. Used in case of problems

Mattermost

Mattermost configuration

Field Type Default Obrigatory Information
Server string Address of mattermost server. Please inform protocol and port if its necessary ex: https://mattermost.example.com:8065
Team string Team name. You can find teams name by (URL)
User string User used to authenticate on Mattermos server
Password string Password used to authenticate on Mattermos server
UseAPIv3 boolean false Set to use Mattermost Api V3

MailTemplate

This configuration formats email message using markdown to post on Mattermost. The default configuration is :incoming_envelope: _From: **{{.From}}**_\n>_{{.Subject}}_\n\n{{.Message}}, in this example when Mattermail receives a message from john@example.com, with subject Hello world and message body Hi I'm John. This email will be formated to:

:incoming*envelope: _From: john@example.com*

Hello world

Hi I'm John

RedirectBySubject

If the option RedirectBySubject is true the Mattermail will try to redirect an email and post it using the subject, ex:

Subject Destination
[#orders] blah channel orders
[#orders #info] blah channel orders and info
Fwd [#orders][#info] blah channel orders and info
[1234#orders] foo channel orders
[@john] blah user john
[@john #orders] blah user john and channel orders

Filter

This option is used to redirect email following the rules.

"Filter":            [
    /* if subject contains 'Feature' redirect to #feature */
    {"Subject":"Feature", "Channels": ["#feature"]},

    /* if from contains 'test@gmail.com' and subject contains 'to me' redirect to @test2*/
    {"From":"test@gmail.com", "Subject":"To Me", "Channels": ["@test2"]},

    /* if from contains '@companyb.com' redirect to #companyb and @john */
    {"From":"@companyb.com", "Channels": ["#companyb", "@john"]} /**/
]

Team/Channel

You can find team and channel name by URL ex:

mattermail teamchannel

Sequence that the email will be redirected

Mattermail post the email using this rules:

1 - Try to post using the subject if the option RedirectBySubject is true

2 - Try to post following the Filter configuration.

3 - Post on channels/users defined on field Channels in config.json

Options

$ ./mattermail --help
Usage:
    mattermail server  Starts Mattermail server
    mattermail migrate Migrates config.json to new version

For more details execute:

    mattermail [command] --help

Building

You need Go to build this project

go get github.com/rodcorsi/mattermail

Mattermail as a service

Using systemd

Considering your installation under /opt/mattermail, add /etc/systemd/system/mattermail.service file with the following content:

# mattermail
[Unit]
Description=mattermail server

[Service]
Type=simple
WorkingDirectory=/opt/mattermail
ExecStart=/opt/mattermail/mattermail server -c config.json
Nice=5

[Install]
WantedBy=multi-user.target

Enable service:

systemctl enable mattermail

Start service:

systemctl start mattermail

View status:

systemctl status mattermail

View log:

journalctl -f -u mattermail.service