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