SMTP-to-SMS Gateway

A lightweight SMTP-to-SMS gateway that converts incoming emails to SMS messages. Send SMS by simply sending an email to phonenumber@yourdomain.com.

Features

• SMTP Server: Receives emails on port 2525
• SMS Providers: Support for Twilio, AWS SNS, and custom webhooks
• Web Interface: Modern Bootstrap 5 dashboard with HTTPS support
• Security: CSP, HSTS, X-Frame-Options, XSS-Protection, and more
• Phone Management: Allowlist for restricting which numbers receive SMS
• Message Logging: Dashboard to view sent messages
• Self-signed SSL: Auto-generated certificates for HTTPS
• Mobile Responsive: Hamburger menu for mobile devices

Screenshots

Login Page

Desktop	Tablet	Mobile

Dashboard

Desktop	Tablet	Mobile

Messages

Desktop	Tablet	Mobile

Settings Pages (Desktop)

SMTP Server	Phone Numbers

Gateway	Authentication

Security

Requirements

• Node.js 18 or higher
• npm
• Twilio account (or AWS SNS or custom webhook)

Installation

1. Clone the Repository

git clone https://github.com/jsmeyers/smtp-to-sms.git
cd smtp-to-sms

2. Install Dependencies

npm install

3. Configure the Gateway

Copy the example configuration files:

cp config/gateway.json.example config/gateway.json
cp config/web.json.example config/web.json
cp config/smtp.json.example config/smtp.json
cp config/phones.json.example config/phones.json

Edit the configuration files with your settings:

# Configure SMS gateway (Twilio, SNS, or webhook)
nano config/gateway.json

# Configure web interface
nano config/web.json

4. Start the Server

npm start

The server will start:

• SMTP Server: Port 2525
• HTTP Web Interface: Port 8080 (redirects to HTTPS)
• HTTPS Web Interface: Port 8443

5. Initial Setup

1. Open https://localhost:8443 (or your server's IP)
2. Accept the self-signed certificate warning
3. Create an admin account
4. Configure your SMS gateway settings

Configuration

SMS Gateway

Edit config/gateway.json:

Twilio

{
  "type": "twilio",
  "twilio": {
    "accountSid": "YOUR_ACCOUNT_SID",
    "authToken": "YOUR_AUTH_TOKEN",
    "fromNumber": "+1234567890"
  }
}

AWS SNS

{
  "type": "sns",
  "sns": {
    "accessKeyId": "YOUR_ACCESS_KEY",
    "secretAccessKey": "YOUR_SECRET_KEY",
    "region": "us-east-1"
  }
}

Webhook

{
  "type": "webhook",
  "webhook": {
    "url": "https://your-webhook.com/sms",
    "method": "POST",
    "headers": {},
    "phoneField": "phone",
    "messageField": "message"
  }
}

SMTP Server

Edit config/smtp.json:

{
  "listenIp": "0.0.0.0",
  "port": 2525,
  "ipMode": "all",
  "allowedIps": [],
  "domain": "localhost"
}

• ipMode: all, subnet, or list
• allowedIps: Array of IPs when ipMode is list

Web Interface

Edit config/web.json:

{
  "port": 8080,
  "httpsPort": 8443,
  "forceHttps": true,
  "sslCN": "localhost",
  "username": "",
  "passwordHash": ""
}

• forceHttps: Redirect HTTP to HTTPS
• sslCN: Common Name for self-signed certificate

Phone Numbers

Edit config/phones.json:

{
  "mode": "all",
  "numbers": []
}

• mode: all (accept all) or list (whitelist only)
• numbers: Array of allowed phone numbers (when mode is list)

Usage

Sending SMS via Email

Send an email to phonenumber@yourdomain.com:

To: 15551234567@yourdomain.com
Subject: Test Message

This is the SMS body text.

The gateway will:

1. Extract the phone number from the email address
2. Check if the phone number is allowed
3. Send the SMS via your configured provider
4. Log the result in the web dashboard

Email Address Format

Format	Phone Extracted
15551234567@domain.com	15551234567
5551234567@domain.com	15551234567 (adds 1)
+15551234567@domain.com	15551234567

Web Interface

Access the dashboard at https://your-server:8443:

• Dashboard: Overview of message activity
• Messages: View sent message history
• Settings: Configure SMTP, phone numbers, gateway, authentication
• Security: Configure HTTPS and security settings

Security

Authentication

The web interface requires authentication. On first run, you'll be prompted to create an admin account.

HTTPS

The gateway auto-generates self-signed SSL certificates stored in ssl/. For production:

1. Replace ssl/server.crt and ssl/server.key with certificates from a trusted CA
2. Or use a reverse proxy (nginx, Apache) for TLS termination

Security Headers

The gateway implements OWASP-recommended security headers:

Header	Value
Content-Security-Policy	Configured for self-hosted resources
Strict-Transport-Security	max-age=31536000; includeSubDomains; preload
X-Frame-Options	DENY
X-XSS-Protection	0
X-Content-Type-Options	nosniff
Referrer-Policy	strict-origin-when-cross-origin
Cross-Origin policies	Enabled for HTTPS

IP Restrictions

Restrict SMTP access by IP:

// Allow only specific IPs
{
  "ipMode": "list",
  "allowedIps": ["192.168.1.100", "10.0.0.0/24"]
}

// Allow local subnet only
{
  "ipMode": "subnet"
}

Troubleshooting

Enable Debug Logging

The server includes detailed logging. Check logs for:

• SMTP connections
• Email parsing
• Phone number extraction
• SMS sending attempts
• Twilio responses

Common Issues

Email not being processed:

• Ensure SMTP client sends proper DATA command
• Email must end with . on its own line
• Check server logs for parsing errors

SMS not sent:

• Verify Twilio credentials
• Check phone number format (10 or 11 digits)
• Verify phone is in the allowed list (if using list mode)

HTTPS certificate warning:

• Self-signed certificates will show browser warnings
• For production, use trusted certificates

Testing SMTP

# Connect to SMTP server
telnet localhost 2525

# Send test email
HELO localhost
MAIL FROM:<test@example.com>
RCPT TO:<15551234567@localhost>
DATA
Subject: Test

This is a test message.
.
QUIT

Project Structure

smtp-to-sms/
├── config/              # Configuration files
│   ├── gateway.json     # SMS provider settings
│   ├── web.json         # Web interface settings
│   ├── smtp.json        # SMTP server settings
│   └── phones.json      # Phone number allowlist
├── src/
│   ├── index.js         # Main entry point
│   ├── smtp-server.js   # SMTP server
│   ├── sms/             # SMS providers
│   ├── web/             # Web interface
│   └── config.js        # Configuration loader
├── views/               # EJS templates
├── public/              # Static assets
│   ├── css/
│   ├── js/
│   └── vendor/          # Bootstrap
├── ssl/                 # SSL certificates (generated)
├── data/                # Message logs
└── package.json

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.