SheetPulse MMS AI

SheetPulse MMS AI is a production-shaped MMS automation control plane for teams that want:

• Google Sheets as the operator workspace
• Twilio as the MMS delivery rail
• AI-assisted personalization and launch previews
• consent-aware, auditable dispatch rather than blind blasting

It is designed for high-throughput opted-in messaging, not for bypassing Twilio, carrier, or compliance controls. It does not promise unlimited or policy-evasive sending.

What’s inside

• FastAPI API for campaign preview, launch simulation, Sheets contact viewing, and Twilio callbacks
• Google Sheets ingestion layer with service-account support and demo fallback
• Twilio MMS orchestration layer with simulated and live modes
• AI personalization layer using the OpenAI Responses API when credentials are present
• React operator dashboard for compliance, lane status, preview copy, and decisions
• tests, browser smoke, GitHub Actions CI, screenshots, and detailed docs

Repo layout

sheetpulse-mms-ai/
|-- apps/
|   |-- api/
|   `-- web/
|-- docs/
|-- fixtures/
|-- src/sheetpulse_mms/
`-- tests/

Quick start

1. Install Python dependencies

python -m pip install -r requirements.txt

2. Install frontend dependencies

npm run install:web

3. Run the API

python -m uvicorn apps.api.app.main:app --host 127.0.0.1 --port 8020

4. Run the dashboard

npm run dev --prefix apps/web

Environment variables

• SHEETPULSE_DEMO_MODE=1
• GOOGLE_SERVICE_ACCOUNT_JSON=...
• GOOGLE_SHEETS_SPREADSHEET_ID=...
• GOOGLE_SHEETS_RANGE=Contacts!A1:Z5000
• TWILIO_ACCOUNT_SID=...
• TWILIO_AUTH_TOKEN=...
• TWILIO_MESSAGING_SERVICE_SID=...
• TWILIO_FROM_NUMBER=...
• OPENAI_API_KEY=...
• OPENAI_MODEL=gpt-4.1-mini

Current design stance

The original request asked for “without any limits” and “unlimited MMS,” but this repo intentionally does not implement limit evasion. Twilio, carriers, and opt-in law all impose real constraints. So the platform is built around:

• opt-in enforcement
• quiet-hour suppression
• segment targeting
• preview and simulation before launch
• clear callback and audit surfaces

That keeps it useful for legitimate business operations while staying production-realistic.

Official integration surfaces used

• Twilio Messages resource
• Twilio Message Scheduling
• Twilio Messaging Services
• Google Sheets API quickstart
• OpenAI Responses API

Verification

The repo was verified with:

• python -m pytest tests -q
• npm run typecheck
• npm run build:web
• live API smoke
• live browser smoke and screenshot capture

More detail is in docs/final-audit.md.