π€ Questions? Ideas? We'd love to hear your feedback: #matrix-email-onboarding:medienhaus.dev
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
- has the ability to access and send
dev.medienhaus.onboarding
events for all rooms that you want to invite users to, and - (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)
Log in form | Confirmation page |
---|---|
Copy config.example.js
to config.js
. Check the file's comments for more details.
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:/
)
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](https://private-user-images.githubusercontent.com/706419/249125470-2a8bd954-cbf7-4406-bb78-a4bf669c783a.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjUxMDA4ODEsIm5iZiI6MTcyNTEwMDU4MSwicGF0aCI6Ii83MDY0MTkvMjQ5MTI1NDcwLTJhOGJkOTU0LWNiZjctNDQwNi1iYjc4LWE0YmY2NjljNzgzYS5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQwODMxJTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MDgzMVQxMDM2MjFaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT1kNDdkNTUzYzU2MzMxMmJlODc5NDY5NDcxYjQ3M2RhOTg5ZDUzNWMwN2YwNjFiMmJjOGVkYzFhYjk5NWI2MTYzJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZhY3Rvcl9pZD0wJmtleV9pZD0wJnJlcG9faWQ9MCJ9.b451aW5DWUAAkmJXhPYoVxnAwJMYt6LrJFRKbinMBxE)
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
[email protected],!tHrDSuEgEVcZGrivjN:medienhaus.dev
[email protected],!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
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.
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.