Even though electronic mail is a very legacy transport, it is well supported in many application servers. There barely exists any application without a support for sending notifications via email.
Making Matrix pipes from all kinds of message passing facilities there exists today would be so pointless work because the payload needs to be decoded differently, anyway.
This repository has support for the following sources:
- UniFi Video by Ubiquiti. Sends motion alerts with pictures to a Matrix room.
- Asterisk voicemail. Sends voice mail message audio clips in Ogg Opus format to a Matrix room.
- Asterisk fax. Receives faxes and delivers them to matrix rooms.
- Wordpress Contact Form 7 by Takayuki Miyoshi. Sends contact form data to a Matrix room as a table.
The principle is the same: Your email server's pipe transport runs the command and the corresponding script parses the message and delivers the message to Matrix.
You don't need your own Matrix homeserver but you need a mail server. The mail server doesn't necessarily need to be open on the Internet. You can have one in your local network where the services are.
On our hackerspace we have some UniFi surveillance cameras which send email on motion. They send alerts by email which is pretty messy. This script listens to incoming emails and tralates them to Matrix picture messages.
Also, it suppresses sending messages if the alarm has been disarmed. For that purpose we have an API endpoint where to check arming status.
Finally, we had a need to deliver voice mail messages to our chat room and also process our membership form data in GDPR compliant fashion (i.e. without sending them to Google Mail).
sudo apt install jq uuid-runtime curl mpack pandoc opus-toolsVersion 1.6 or newer is required for jq. Otherwise --rawfile
switch doesn't work.
Pandoc is required in Wordpress contact form parser. It is not used elsewhere.
Opus-tools is only needed by Asterisk voicemail script.
Copy template as your configuration file and set URLs, room name, and Matrix access token.
cp matrix.conf.example matrix.conf
$EDITOR matrix.confAdd pipe transport to your email server configuration. See Exim documentation of pipe transport for example. It works with variety of email servers but the examples here are for Exim virtual domain configuration.
See your mail server documentation or make a little test script to find out which user it is run by if you have any issues.
The bot doesn't automatically join on invite, currently. You need to join the room using the bot. Remember to add room aliases you need.
Add an transport script to your email server. In Exim:
unifi-matrix : |/opt/email-to-matrix/unifi_parser
Ensure the script is executable and its configuration file is readable
by the mail user. For example in Debian and Exim, the user is
Debian-exim. Reload Exim configuration.
Enable email alerts from UniFi Video to send the email to that address on your server.
We use Sangoma's FreeBPX distribution which comes with Exim but we don't want to use full email server because it's easier to configure ssmtp to send the email to our main server.
First, install ssmtp and optionally remove Exim. yum install ssmtp. Then, set ssmtp as default agent with update-alternatives --config mta.
Configure ssmtp by editing /etc/ssmtp/ssmtp.conf. The only option
you really need is mailhub=ADDRESS where ADDRESS is the IP or host
name of the upstream email server.
Add the transport script to your email server:
voicemail : |/opt/email-to-matrix/asterisk_voicemail_parser
Ensure the script is executable and its configuration file is readable
by the mail user. For example in Debian and Exim, the user is
Debian-exim. Reload Exim configuration.
Configure your voicemail account to send email to that email address. Remember to tick option "Email attachment" because otherwise the audio file is not there. If you want to receive the voice mail only via Matrix, tick "Delete voicemail".
Add alias #tele-EXTENSION@homeserver to the room where you want to
receive the voice mail for given extension. For example in our
hackerspace our internal extension is 6906 so the alias should be
#tele-6906:hacklab.fi. The home server can be any server and can be
configured in matrix.conf.
NB! The script expects default mail template. If you change the template, remember to modify the asterisk_voicemail_parser accordingly.
Add the transport script's email address to the FreePBX user email address and enable Fax (also possible Fax detection) for your inbound route or multiple routes. The script parses the last 4 digits of the phone number and uses that as the target extension number.
The same idea of #tele-EXTENSION as in Asterisk voice mail parser is used to route the message to the correct matrix room.
Use PDF format in Asterisk (default). TIFF not supported.
The script memberbot_parser is very specific to our hackerspace membership form. You most likely need to edit it to match your needs. Also, you might need WP Mail SMTP to get the email out of your Wordpress server.
We have the following message body:
name [your-name]
born [your-year]
email [your-email]
city [your-city]
tel [your-phone]
nick [your-irc]
fee [jasenyys]
member [member]
lang en
msg
[your-message]
The important part is to have multi-line message [your-message] as
last row and have msg on a line of its own. Otherwise the parser
fails. But again, this form parser probably needs a rewrite if you use
it in a different setup.
The script doesn't currently support encrypting the messages. So do not use it on encrypted channels. Also, the email addresses used should be kept private because the scripts are not validating where the email is coming from. However, if you run the MTA on your intranet, the issue is minor.
The repository also contains fax script for Asterisk, used to send PDF files to a given fax number. That script needs to be run on the Asterisk server itself (not your mail server probably). It requires ghostscript for PDF to TIFF conversion.