medienhaus/matrix-email-onboarding

Send out email invitations for Matrix rooms & spaces 📨 🚀

🖤 Questions? Ideas? We'd love to hear your feedback: #matrix-email-onboarding:medienhaus.dev

---

matrix-email-onboarding

A microservice to invite users to Matrix rooms (or spaces) via their email addresses, even before they might have a Matrix account.

Do you have a list of email addresses and Matrix rooms (or spaces) which you wish to invite them to? And you don't know their Matrix usernames or if they even have a Matrix account yet? This is for you. ✨

• Comes with a CLI tool to send out emails 📨 with a link (containing a secret token) for your user to click on
• Node.js server-side application to handle web requests to
  • (1) check a given secret onboarding token 🔍 and list the linked Matrix rooms or spaces
  • (2) let the user sign in ☑️ with their Matrix account and automatically join the given rooms or spaces
  • (3) (optionally) promote those newly joined users to become moderators or administrators 🧑‍⚖️

The only requirement for this is a Matrix user (or a bot) that

1. has the ability to access and send dev.medienhaus.onboarding events for all rooms that you want to invite users to, and
2. (optionally) has a power level at least as high as what you're trying to promote users to. (e.g. needs to be at least a moderator, if you want to make everyone a moderator)

Screenshots

Log in form	Confirmation page

Configuration

Copy config.example.js to config.js. Check the file's comments for more details.

Running

As a first, run npm install to install all the required dependencies.

npm start

You can make use the following environment variables to adjust your deployment:

• PORT Which port the service should run on (default: 3000)
• GLOBAL_PREFIX If you are running the service in a certain subdirectory, e.g. behind a reverse-proxy (default: /)

Scripts

send-emails - Sends out one email per unique email address in a given .csv file, and adds one dev.medienhaus.onboarding event per email address to each Matrix room/space containing an encrypted identifier unique to the recipient of the email. You can be assured that this script is going to triple-quadruple check back with you, before it actually starts sending out real emails. For testing the sending of emails using something like Mailpit is recommended.

Usage: npm run cli send-emails -- [options]

Send out invitations via email

Options:
  -f, --file <filePathEmailAddressesRoomIdsCsv>  path to .csv file containing email addresses and room IDs
  -b, --body <filePathEmailBody>                 (optional) path to .txt file containing the email body

The .csv file might look like this:

email,roomId
marcel@medienhaus.dev,!tHrDSuEgEVcZGrivjN:medienhaus.dev
andi@medienhaus.dev,!QQpfJfZvqxbCfeDgCj:matrix.org

In your email body you can include the following placeholders which will be then replaced with its respective meaningful content:

• <LINK> The link that brings the user to the login form where they can login using a Matrix account to accept the invitation
• <ROOMS> A list of Matrix room names (separated by \n) the user is being invited to

Credits

Written in JavaScript with the NestJS framework for Node.js, with the help of the matrix-js-sdk, Handlebars and ECIES. Includes a CLI tool made possible by nest-commander, Inquirer and Nodemailer.

License

Public money, public code. The development of this project was funded and supported by public institutions. The code was written and is being maintained by medienhaus/ and our friends.