Skip to content

Send out email invitations for Matrix rooms & spaces πŸ“¨ πŸš€

License

Notifications You must be signed in to change notification settings

medienhaus/matrix-email-onboarding

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

30 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation


πŸ–€ 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
Screenshot 2023-06-30 at 15-51-10 matrix-email-onboarding Screenshot 2023-06-30 at 15-50-58 matrix-email-onboarding

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.

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