SETUP.md

EMAILOUT Setup Guide

Prerequisites

1. OpenAI API Key - Get one from https://platform.openai.com/api-keys

Hugging Face Spaces Setup

1. Create a new Space:

   • Go to https://huggingface.co/spaces
   • Click "Create new Space"
   • Select "Docker" as the SDK
   • Name it "EMAILOUT" (or your preferred name)

2. Add OpenAI API Key as Secret:

   • Go to your Space Settings
   • Navigate to "Secrets" section
   • Add a new secret:
     • Key: OPENAI_API_KEY
     • Value: Your OpenAI API key

3. Upload Files:

   • Upload all project files to your Space
   • The Dockerfile will handle the build process

4. Deploy:

   • The Space will automatically build and deploy
   • Monitor the logs for any build errors

Local Development

1. Install Dependencies:

   # Backend
   cd backend
   pip install -r requirements.txt
   
   # Frontend
   cd ../frontend
   npm install
   

2. Set Environment Variables:

   export OPENAI_API_KEY=your_api_key_here
   

   Google Sign-In (optional) — create an OAuth Web application client in Google Cloud Console (APIs & Services → Credentials). Under Authorized redirect URIs add exactly:

   • Local (Vite dev): http://localhost:5173/api/auth/google/callback
   • Docker / Hugging Face / your public URL: https://<your-host>/api/auth/google/callback

   Then set:

   export GOOGLE_CLIENT_ID=...
   export GOOGLE_CLIENT_SECRET=...
   # Must match the redirect URI above (recommended for dev):
   export FRONTEND_ORIGIN=http://localhost:5173
   # Or set the full callback explicitly:
   # export GOOGLE_REDIRECT_URI=http://localhost:5173/api/auth/google/callback
   # Strong random secret for signed session cookies (required in production):
   export SESSION_SECRET=$(openssl rand -hex 32)
   

   For Hugging Face Spaces, set FRONTEND_ORIGIN to https://, e.g. https://your-space.hf.space (not http://). Google’s OAuth policy rejects http:// redirect URIs for public hosts; the Authorized redirect URI in Google Cloud must be the https callback, e.g. https://your-space.hf.space/api/auth/google/callback.

   For HTTPS deployments, also set HTTPS_ONLY_COOKIES=1 and add your public origin to CORS_ORIGINS if the browser origin differs from the API host.

   Multi-tenant / workspaces: After sign-in, each user gets a workspace; the first user on an empty database becomes admin of the default workspace. Admins can invite others (Google accounts only) via the header; invitees open the link, then sign in with the same email as invited. Smartlead webhook URL must include your workspace id, e.g. https://your-host/api/webhooks/smartlead?tenant_id=1 (replace 1 with your workspace id from the header switcher).

3. Run Backend:

   cd backend
   uvicorn app.main:app --reload --port 8000
   

4. Run Frontend:

   cd frontend
   npm run dev
   

Project Structure

EMAILOUT/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py          # FastAPI application
│   │   ├── database.py      # SQLite database models
│   │   ├── models.py         # Pydantic models
│   │   └── gpt_service.py   # OpenAI GPT integration
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── pages/
│   │   │   └── EmailSequenceGenerator.jsx
│   │   ├── components/
│   │   │   ├── upload/
│   │   │   ├── products/
│   │   │   ├── prompts/
│   │   │   ├── sequences/
│   │   │   └── ui/
│   │   └── ...
│   └── package.json
├── Dockerfile
└── README.md

Features

• ✅ CSV Upload from Apollo
• ✅ Product Selection with Custom Products
• ✅ Prompt Template Editor
• ✅ GPT-Powered Sequence Generation
• ✅ Real-time Streaming Results
• ✅ CSV Export for Klenty/Outreach

API Endpoints

• POST /api/upload-csv - Upload CSV file
• POST /api/save-prompts - Save prompt templates
• GET /api/generate-sequences - Generate sequences (SSE stream)
• GET /api/download-sequences - Download sequences as CSV

Database

SQLite database is stored at /data/emailout.db (persistent in HF Spaces).

Uploaded files are stored at /data/uploads/.