147 lignes
2.8 KiB
Markdown
147 lignes
2.8 KiB
Markdown
# 📬 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
|