119 lines
3.3 KiB
Markdown
119 lines
3.3 KiB
Markdown
# Email to Matrix SMS Gateway
|
||
|
||
With many cell providers closing down their email-to-text gateways, this project serves as a **self-hostable almost-equivalent solution**.
|
||
|
||
Matrix-SMS-Gateway is a simple **FastAPI** server built to receive incoming POST requests from an SMTP server or email webhook (e.g., Mailgun). It relays those messages to a connected Matrix account, which is tied to a JMP.chat phone number, thereby enabling SMS sending via Matrix.
|
||
|
||
|
||
## Setup
|
||
|
||
Everything should be fairly straightforward to set up:
|
||
|
||
### Prerequisites
|
||
|
||
- A Matrix account connected to JMP.chat (your phone number bridged as a Matrix user).
|
||
- An SMTP server or email forwarding service configured to send inbound emails as POST requests.
|
||
- Python 3.11+ (if running locally) or Docker compatible environment.
|
||
- Optional: Mailgun account for inbound message forwarding.
|
||
|
||
### Installation
|
||
|
||
You can run the gateway in several ways:
|
||
|
||
#### 1. Using Docker
|
||
|
||
Build and run with your preferred tool (e.g., Docker Compose):
|
||
|
||
```
|
||
docker build -t matrix-sms-gateway .
|
||
docker run -e MATRIX_HOMESERVER="https://aria-net.org"
|
||
-e MATRIX_USER_ID="@user:aria-net.org"
|
||
-e MATRIX_PASSWORD="your_password"
|
||
-p 8080:8080
|
||
matrix-sms-gateway
|
||
```
|
||
|
||
|
||
#### 2. Running Locally
|
||
|
||
Install requirements and launch:
|
||
|
||
```
|
||
pip install -r requirements.txt
|
||
uvicorn app:app --host 0.0.0.0 --port 8080
|
||
```
|
||
|
||
|
||
### Configuration
|
||
|
||
Set environment variables to connect the gateway to your Matrix account:
|
||
|
||
- `MATRIX_HOMESERVER` — Your homeserver URL (e.g., https://aria-net.org)
|
||
- `MATRIX_USER_ID` — Your full Matrix user ID (e.g., @user:aria-net.org)
|
||
- `MATRIX_PASSWORD` — Your Matrix account password or access token
|
||
|
||
### Mailgun Setup (Optional)
|
||
|
||
1. Create an inbound route for your receiving email domain.
|
||
2. Forward inbound messages as HTTP POST to your gateway's `/mailgun-webhook` endpoint.
|
||
3. Configure Mailgun to send the form fields `recipient`, `subject`, and `body-plain` in the request.
|
||
|
||
---
|
||
|
||
## Example Docker Compose Setup
|
||
|
||
```
|
||
version: "3.9"
|
||
|
||
services:
|
||
matrix-sms-gateway:
|
||
build: .
|
||
container_name: matrix-sms-gateway
|
||
environment:
|
||
MATRIX_HOMESERVER: "https://aria-net.org"
|
||
MATRIX_USER_ID: "@user:aria-net.org"
|
||
MATRIX_PASSWORD: "your_password"
|
||
ports:
|
||
- "8080:8080"
|
||
restart: unless-stopped
|
||
```
|
||
|
||
|
||
Run with:
|
||
|
||
```
|
||
docker-compose up -d
|
||
```
|
||
|
||
|
||
---
|
||
|
||
## Mailgun Integration Example
|
||
|
||
### Steps to set up Mailgun inbound email routing:
|
||
|
||
1. In [Mailgun Control Panel > Routes](https://app.mailgun.com/app/routes), create a new route:
|
||
|
||
- **Filter expression:** `match_recipient("your-phone-number@yourdomain.com")` (or use a wildcard or catch-all to allow all phone numbers)
|
||
- **Actions:** `forward("http://your-server-ip-or-domain:8080/mailgun-webhook")`
|
||
- **Description:** "Forward SMS emails to Matrix SMS Gateway"
|
||
|
||
2. **Test sending an email** to your forwarded address (e.g., `14155551212@yourdomain.com`).
|
||
|
||
3. The gateway receives the POST request, extracts recipient number, message body, and forwards as SMS.
|
||
|
||
---
|
||
|
||
## Testing with curl
|
||
|
||
You can simulate Mailgun’s webhook POST for quick testing:
|
||
|
||
```
|
||
curl -X POST http://localhost:8080/mailgun-webhook
|
||
-F recipient="14155551212@yourdomain.com"
|
||
-F subject="Test SMS"
|
||
-F "body-plain=Hello from Mailgun!"
|
||
```
|
||
|
||
Because the system only relies on those three form fields, you can also use this with any system that can send a POST request, not just mailgun or other SMTP service.
|