{"id":13553039,"url":"https://github.com/kamax-matrix/matrix-appservice-email","last_synced_at":"2025-04-03T04:31:55.983Z","repository":{"id":215841230,"uuid":"89535291","full_name":"kamax-matrix/matrix-appservice-email","owner":"kamax-matrix","description":"Matrix \u003c--\u003e E-mail Bridge","archived":true,"fork":false,"pushed_at":"2019-06-20T20:29:18.000Z","size":281,"stargazers_count":39,"open_issues_count":15,"forks_count":11,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-21T00:02:28.177Z","etag":null,"topics":["bridge","e-mail","email","java","matrix"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kamax-matrix.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-04-26T23:24:31.000Z","updated_at":"2024-05-18T17:50:44.000Z","dependencies_parsed_at":"2024-01-15T09:05:32.602Z","dependency_job_id":"58bd0f12-6a84-4f8a-bac4-8bca568f30fc","html_url":"https://github.com/kamax-matrix/matrix-appservice-email","commit_stats":null,"previous_names":["kamax-matrix/matrix-appservice-email","kamax-io/matrix-appservice-email"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamax-matrix%2Fmatrix-appservice-email","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamax-matrix%2Fmatrix-appservice-email/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamax-matrix%2Fmatrix-appservice-email/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kamax-matrix%2Fmatrix-appservice-email/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kamax-matrix","download_url":"https://codeload.github.com/kamax-matrix/matrix-appservice-email/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246939195,"owners_count":20857916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bridge","e-mail","email","java","matrix"],"created_at":"2024-08-01T12:02:16.088Z","updated_at":"2025-04-03T04:31:50.975Z","avatar_url":"https://github.com/kamax-matrix.png","language":"Java","funding_links":[],"categories":["Java","java"],"sub_categories":[],"readme":"Matrix \u003c--\u003e E-mail bridge\n-------------------------\n[![Build Status](https://travis-ci.org/kamax-matrix/matrix-appservice-email.svg?branch=master)](https://travis-ci.org/kamax-matrix/matrix-appservice-email)\n\n[Features](#features)  \n[Overview](#overview)  \n[Requirements](#requirements)  \n[Setup](#setup)  \n[Integration](#integration)  \n[Usage](#usage)\n\n---\n\n**This project is no longer maintained.**\n\n---\n\nThis is an E-mail bridge for Matrix using the Application Services (AS) API.\n\nThis bridge will pass all Matrix messages from rooms where E-mail virtual users are invited via E-mail, and all E-mail\nmessages into the corresponding Matrix room.\n\n# Features\n\n- Matrix to E-mail forwarding\n- E-mail to Matrix forwarding\n- E-mail \u003c-\u003e Matrix \u003c-\u003e E-mail forwarding, if several bridge users are present within a room\n- Fully configuration notification templates, per event\n- Subscription portal where E-mail users can manage their notifications\n\n# Overview\nThis bridge will map single virtual users to single e-mail addresses, allowing people without Matrix account to be invited\nand participate into Matrix rooms.  \nE-mail users can only participate in a room after being invite into it, and cannot subscribe/join on their own.\n\nThis bridge does NOT (currently) map entire rooms to a single E-mail address, like a mailing-list.\n\n# Requirements\nYou will need Java 8 to build and run this bridge.\n\nDue to the current Matrix protocol and various implementations/workflows, this bridge relies on on a custom Identity Server\nthat proxy to this AS any 3PID requests that have no match.  \nThis allows a smooth user experience, where someone can always be invited by e-mail using a regular Matrix client use case,\nusing its Matrix ID if one is found, or inviting a virtual user to directly enable bridging for the given user in the room.\n\n# Setup\nSetup can either be done via manually running the bridge or using a Docker image.\nYou will require Java 1.8 or higher to compile and run this bridge.\n\n## Steps overview\n1. [Build the bridge](#build)\n2. [Configure the bridge](#configure)\n3. [Run the bridge](#run) manually or via Docker\n4. [Configure your HS](#homeserver) to read the bridge registration file\n5. [See Usage instructions](#usage) to see how to interact with the bridge\n6. Start chatting!\n\n## Build\nCheckout the repo and initialize the submodules\n```\ngit clone https://github.com/kamax-matrix/matrix-appservice-email.git\ncd matrix-appservice-email\ngit submodule update --init\n```\n### Manual\nRun the following command in the repo base directory to produce the distribution directory `build/dist/bin` which will\ncontain all required files and will allow you to test the bridge quickly.  \n**It is highly recommended to use a less volatile directory to store those as this directory can be remove with a clean command!**\n```\n./gradlew buildBin\n```\n\n### Docker\nRun the following command in the repo base directory to produce a Docker image `kamax.io/mxasd-email`\n```\n./gradlew buildDocker\n```\nThis command expects you to be able to run `docker` commands without sudo, and without the Gradle daemon running which\nwill interfere with the build (`permission denied` to connect to the Docker socket).\n\nIf you cannot fulfil these requirements and need to manually build the Docker image, prepare the staging directory:\n```\n./gradlew buildBin\ncp src/main/docker/Dockerfile build/dist/bin\n```\nYou can then run your usual build command pointing to `build/dist/bin` like so\n```\nsudo docker build build/dist/bin -t kamax.io/mxasd-email\n```\n\n## Configure\nCopy the default config file located in `src/main/resources/application.yaml` into a permanent directory depending on your build type:\n- In `build/dist/bin` by default if you went for the manual build method, but **you should use a less volatile location**\n- A dedicated directory which will be presented as a volume, if you went for the Docker build method, e.g. `/data/mxasd-email`\n\nThe configuration file contains a detailed description for each possible configuration item.\n\n## Run\n### Manual\nChange into the directory containing the main jar (`build/dist/bin` by default) and run it:\n```\ncd build/dist/bin\n./matrix-appservice-email.jar\n```\n\n### Docker\nRun a new container for the newly created image, and make sure `/data/mxasd-email` is adapted to your actual location:\n```\ndocker run -p 8091:8091 -v /data/mxasd-email:/data kamax.io/mxasd-email\n```\n# Integration\n## Homeserver\nLike any bridge, a registration file must be generated which will then be added to the HS config.  \nCurrently, there is no mechanism to automatically generate this config file.\n\nYou will find a working example at `registration-sample.yaml`, which you should copy at the same location as the Bridge configuration file.  \nConfiguration must match the `matrix` section in the bridge config file.\n\nThe Homeserver can then be configured with:\n```\napp_service_config_files:\n    - \"/path/to/registration.yaml\"\n```\n\n## mxisd\nFollow instructions on the [git repo README](https://github.com/kamax-matrix/mxisd/blob/master/README.md) until you have a working setup.\n\nAdd/edit the following sections in the mxisd configuration file, adapt the AS URL, and restart if needed:\n```\nlookup:\n  recursive:\n    bridge:\n      enabled: true\n      mappings:\n        email: 'http://localhost:8091'\n```\n\n# Usage\n## Via Identity Server\n1. [Install and Configure mxisd](#mxisd) to use this bridge for unknown 3PID lookup\n2. Configure your Matrix client to use mxisd as the Identity Server\n3. Invite someone to a room with an e-mail which has no 3PID mapping. In Riot, use \"Invite to this room\" feature.\n\n## Manual\n1. Invite the AS user to a new chat or in an existing room (replace the Matrix ID to the appropriate value):\n```\n/invite @appservice-email:localhost\n```\n\n2. Send the command into the room/chat to get the Matrix ID for a given e-mail (replace with appropriate value):\n```\n!email mxid john.doe@example.org\n```\nYou should get an answer from the AS user, which will look like this:\n```\nMXID for john.doe@example.org:\n\n   @email_john.doe=40example.org:localhost\n```\n\n3. Use the given MAtrix ID  to invite the Bridge user into a room or chat.\n4. The E-mail user will receive a notification of the next conversation.\n5. Start chatting!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamax-matrix%2Fmatrix-appservice-email","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkamax-matrix%2Fmatrix-appservice-email","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkamax-matrix%2Fmatrix-appservice-email/lists"}