Initial commit

README.md

@@ -0,0 +1,146 @@
+# 📬 Mail2SMS
+
+A production-ready Mail-to-SMS gateway.
+
+This service monitors an IMAP inbox in real-time (IMAP IDLE) and sends SMS messages through an external SMS API: sms-gate private server https://sms-gate.app
+
+---
+
+## 🚀 Features
+
+- 📡 Real-time IMAP IDLE monitoring
+- 🔄 Automatic reconnection handling
+- 📤 SMS sending via HTTP API (Basic Auth)
+- 🧠 Dynamic subject parameter parsing
+- 📧 Status email feedback
+- 🐳 Docker-ready
+- ⚙ Environment-based configuration
+
+---
+
+## 🧩 How It Works
+
+An email must contain parameters in the **subject line**:
+
+```
+to=+33612345678 deviceId=ABC123 simNumber=2
+```
+
+### Supported Subject Parameters
+
+| Parameter  | Required | Description |
+|------------|----------|-------------|
+| `to`       | ✅ Yes   | Destination phone number (E.164 format) |
+| `deviceId` | ❌ No    | SMS gateway device ID |
+| `simNumber`| ❌ No    | SIM slot number |
+| `login`    | ❌ No    | login/username API |
+| `password` | ❌ No    | password API |
+
+If 'deviceId' or 'simNumber' are not provided, then try using the environment variables, and otherwise don't pass them to the API which will take automatic values.
+
+# 🛠 Installation
+
+## 1️⃣ Clone the repository
+
+```bash
+git clone https://git.celjim.fr/jimmyGALLAND/mail2sms.git
+```
+
+---
+
+## 2️⃣ Create environment file
+
+Create a `.env` file:
+
+```env
+### Required ###
+IMAP_SERVER=imap.example.com
+EMAIL_ACCOUNT=mail@example.com
+EMAIL_PASSWORD=yourpassword
+SMTP_SERVER=smtp.example.com
+API_URL=https://api.sms-gateway.com/3rdparty/v1/message
+
+### Optional ###
+API_USERNAME=apiuser
+API_PASSWORD=apipassword
+DEFAULT_DEVICE_ID=XXXXXXXX
+DEFAULT_SIM_NUMBER=1
+IMAP_PORT=993
+SMTP_PORT=587
+```
+
+---
+
+# 🐳 Docker Deployment
+
+## Build Docker image
+
+```bash
+cd mail2sms
+docker build -t mail2sms:latest .
+```
+
+## Run container
+
+```bash
+docker run -d \
+  --name mail2sms \
+  --env-file .env \
+  --restart unless-stopped \
+  mail2sms:latest
+```
+
+---
+
+# 🔁 Updating the Service
+
+```bash
+git pull
+docker build -t mail2sms:latest .
+docker stop mail2sms
+docker rm mail2sms
+docker run -d --name mail2sms --env-file .env --restart unless-stopped mail2sms:latest
+```
+
+---
+
+# 📧 Email Usage Example
+
+### Subject:
+```
+to=+33612345678 [login=yourApiLogin password=yourApiPssword deviceId=ABC123 simNumber=2]
+```
+
+### Body:
+```
+Hello from Mail2SMS!
+```
+
+---
+
+# 🛡 Production Notes
+
+- Uses persistent IMAP connection (IDLE mode)
+- Auto-reconnects on network failure
+- Handles SMTP/API timeouts
+- Safe for long-running container environments
+
+---
+
+# 📊 Improvements envisaged in the future
+
+- Healthcheck route for Docker
+- Webhook support for delivery confirmation
+- Rate limiting and retry backoff
+
+---
+
+# 📜 License
+
+Apache License
+[Read Licence](https://git.celjim.fr/jimmyGALLAND/mail2sms/src/LICENSE)
+
+---
+
+# 👤 Author
+Jimmy GALLAND