SMS Campaign Manager

Dockerized SMS automation system with Android device integration via Termux API.

Features

• Campaign Management: Create, schedule, and monitor SMS campaigns
• Contact Import: Upload contacts from CSV files with template variables
• Android Integration: Send SMS through Termux API with ADB fallback
• User Authentication: Web login and API key access
• Real-time Analytics: Track delivery status and responses

Architecture

Ubuntu Server (Docker)          Android Device (Termux)
┌─────────────────────┐        ┌─────────────────────┐
│  Flask Web App      │◄──────►│  Termux SMS API     │
│  Port 5000          │        │  Port 5001          │
└─────────────────────┘        └─────────────────────┘

Quick Start

# 1. Configure environment
cp .env.example .env
nano .env  # Set your Android device IP and credentials

# 2. Generate API keys
python3 src/core/auth.py

# 3. Deploy to Android
./scripts/deploy-android.sh

# 4. Start the application
docker compose up -d

# 5. Open web dashboard
open http://localhost:5000

Requirements

Ubuntu Server

• Docker and Docker Compose
• Tailscale (recommended) or local network access

Android Device

• Termux (from F-Droid)
• Termux:API (from F-Droid)
• SSH server enabled

Documentation

Full documentation is available in the docs/ directory:

Getting Started

• Installation Guide - Complete setup instructions
• Quick Start - Rapid deployment
• Authentication - User login configuration

Configuration

• Security Setup - API keys and Docker security
• Environment Variables - All configuration options

User Guides

• User Management - Managing users and roles
• Testing Guide - Verification procedures
• Troubleshooting - Common issues

Reference

• API Endpoints - Complete API reference
• Deployment Guide - Production deployment

Project Structure

campaign_connector/
├── src/               # Flask application
├── android/           # Termux server scripts
├── docs/              # Documentation
├── scripts/           # Deployment scripts
├── docker/            # Docker configuration
├── data/              # SQLite database (runtime)
├── uploads/           # CSV uploads (runtime)
└── logs/              # Application logs (runtime)

Common Commands

# Start services
docker compose up -d

# View logs
docker compose logs -f sms-campaign

# Stop services
docker compose down

# Manage users
python3 manage_users.py

Support

For issues:

1. Check Troubleshooting
2. Review logs: docker compose logs
3. Verify configuration in .env

License

Copyright 2025 Campaign Connector Team