# 📬 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