popsy-ai

Name	popsy-ai JSON
Version	0.0.5 JSON
	download
home_page	None
Summary	Reddit DM automation CLI using Popsy AI for lead generation and outreach
upload_time	2025-07-10 10:50:04
maintainer	None
docs_url	None
author	None
requires_python	>=3.9
license	Copyright 2025 Popsy Labs, Inc.
keywords	ai automation dm lead-generation outreach reddit
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Reddit DM Automation - Unified API & Browser Integration

## What You Need:
- MacBook with macOS 10.15 or newer
- Reddit account
- Popsy API token
- 30 minutes for setup

---

## Step 1: Install Python 3.11.9

### Check if you have Python:
```bash
python3 --version
```

### If you don't have Python 3.11.9, install it:
```bash
# Install Homebrew first (copy and paste this whole line)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python 3.11.9
brew install python@3.11
```

---

## Step 2: Install Required Software

```bash
# Install the required libraries
pip3 install requests "camoufox[geoip]" browserforge

# Download the special browser (this takes a few minutes)
python3 -m camoufox fetch
```

---

## Step 3: Unzip and go to the folder

```bash
# Go to the folder
cd reddit-automation
```

---

## Step 4: Get Your API Token

1. **Login to Popsy Dashboard**
2. **Get your API token** from settings
3. **Set environment variable:**
```bash
export POPSY_API_TOKEN="your-token-here"
```

Or create a config file:
```bash
# Create config.json
{
  "token": "your-api-token-here",
  "base_url": "https://app.popsy.ai",
  "min_relevancy": 10,
  "max_threads": 5,
  "show_new": false,
  "hide_already_dmed": true,
  "sort_by": "by_relevancy"
}
```

---

## Step 5: Test the Connection (NEW Unified CLI)

```bash
# Test with simulation mode (no actual DMs sent)
python3 main.py --dry-run --verbose --min-relevancy 80

# Test with detailed debugging
python3 main.py --debug --dry-run --show-new
```

---

## Step 6: Choose Your Automation Mode

### 🔹 **API Simulation Mode** (Default - Safe Testing)
```bash
# Basic simulation - see what would happen
python3 main.py --dry-run --verbose

# Live simulation with API tracking
python3 main.py --min-relevancy 80 --max-threads 3
```

### 🔹 **Live Browser Automation** (Real DM Sending)
```bash
# Live browser automation with visible browser
python3 main.py --browser --min-relevancy 80 --max-threads 3

# Headless browser automation (background)
python3 main.py --browser --headless --min-relevancy 9 --max-threads 2
```

---

## 🆕 New Advanced Features:

### **Smart Configuration Management**
- **Precedence**: CLI arguments → config.json → defaults
- **Verbose mode**: See exactly what configuration is being used
- **Debug mode**: Full API request/response logging

```bash
# See all configuration details
python3 main.py --verbose --dry-run

# Debug API calls and responses
python3 main.py --debug --dry-run
```

### **Flexible Thread Filtering**
```bash
# Include new threads (default: false)
python3 main.py --show-new --verbose

# Hide threads from already-DMed authors (default: true)
python3 main.py --hide-already-dmed

# Show threads from already-DMed authors
python3 main.py --show-already-dmed

# Sort by relevance or recency
python3 main.py --sort-by by_relevancy
python3 main.py --sort-by by_date
```

### **Multiple Processing Modes**
```bash
# DM mode (default)
python3 main.py --mode dm --browser

# Comment mode (simulation only)
python3 main.py --mode comment --dry-run
```

---

## Daily Use Examples:

### **Conservative Automation** (Recommended)
```bash
# High-quality leads only, visible browser
python3 main.py --browser --min-relevancy 90 --max-threads 3 --verbose
```

### **Testing New Filters**
```bash
# Test different relevancy thresholds
python3 main.py --dry-run --min-relevancy 60 --show-new --verbose

# Test specific subreddit
python3 main.py --subreddit-id 123 --dry-run --debug
```

### **Bulk Processing** (Advanced Users)
```bash
# Background automation with higher volume
python3 main.py --browser --headless --min-relevancy 80 --max-threads 10
```

---

## 🚀 Complete Configuration Options:

### **Core Settings:**
- `--token`: Your Popsy API authentication token
- `--base-url`: API base URL (default: https://app.popsy.ai)
- `--config`: Configuration file path (default: config.json)

### **Thread Filtering:**
- `--min-relevancy`: Minimum relevancy score 1-10 (default: 7)
- `--max-threads`: Maximum threads to process (default: 100)
- `--subreddit-id`: Filter by specific subreddit ID
- `--page-size`: Threads per API page (default: 50)
- `--sort-by`: Sort by 'by_relevancy' or 'by_date' (default: by_date)

### **Thread Type Filters:**
- `--show-new`: Include new threads (default: false)
- `--dm-sent`: Include threads with DMs sent (default: false)
- `--comment-sent`: Include threads with comments sent (default: false)
- `--show-deleted`: Include deleted threads (default: false)
- `--hide-already-dmed`: Hide previously contacted authors (default: true)
- `--show-already-dmed`: Override hide setting

### **Processing Mode:**
- `--mode`: Choose 'dm' or 'comment' processing (default: dm)
- `--dry-run`: Test without sending actual DMs/comments

### **Browser Automation:**
- `--browser` / `--live`: Use live browser automation (requires camoufox)
- `--headless`: Run browser in background mode
- `--browser-delay`: Custom delay between actions (seconds)

### **Debugging & Logging:**
- `--verbose` / `-v`: Show detailed configuration and processing info
- `--debug`: Enable full API request/response logging

---

## File Structure:

```
reddit-dm-tool/
├── main.py                   # 🆕 Unified CLI interface
├── api.py                    # Core API client library
├── dm_automation.py          # Browser automation library
├── config.json              # Your configuration
├── logs/
│   ├── api_client_YYYY-MM-DD.log
│   ├── sent_messages_YYYY-MM-DD.csv
│   └── sent_comments_YYYY-MM-DD.csv
└── browser_data/            # Persistent browser session
```

---

## 🆕 Enhanced Features:

### **Smart Configuration Display**
```bash
python3 main.py --verbose --dry-run
```
Shows:
- ✅ **Command line arguments** you used
- ✅ **Configuration file values** loaded
- ✅ **Environment variables** detected
- ✅ **Effective values** after precedence resolution

### **Robust Error Handling**
- ✅ **API response validation** (handles different response formats)
- ✅ **Browser dependency checking** (graceful fallback if camoufox not installed)
- ✅ **Configuration validation** (ensures compatible settings)

### **Flexible Automation**
- ✅ **Simulation mode**: Test with API tracking but no actual sends
- ✅ **Browser mode**: Live DM sending with real browser
- ✅ **Headless mode**: Background automation for scheduled runs

---

## Configuration Examples:

### **Conservative Setup** (config.json)
```json
{
  "token": "your-token-here",
  "base_url": "https://app.popsy.ai",
  "min_relevancy": 90,
  "max_threads": 3,
  "show_new": false,
  "hide_already_dmed": true,
  "sort_by": "by_relevancy"
}
```

### **Testing Setup** (config.json)
```json
{
  "token": "your-token-here",
  "min_relevancy": 60,
  "max_threads": 10,
  "show_new": true,
  "hide_already_dmed": false,
  "sort_by": "by_date"
}
```

---

## Troubleshooting:

**🔧 Browser Issues:**
```bash
python3 -m camoufox remove
python3 -m camoufox fetch
```

**🔧 Configuration Issues:**
```bash
# See what configuration is actually being used
python3 main.py --verbose --dry-run

# Debug API communication
python3 main.py --debug --dry-run
```

**🔧 No threads found?**
- Check your API token is valid: `--debug` shows request details
- Lower the `--min-relevancy` score
- Try `--show-new` to include new threads
- Use `--show-already-dmed` to see previously contacted authors
- Verify you have tracked subreddits in Popsy dashboard

**🔧 API connection failed?**
- Check internet connection
- Verify `--base-url` is correct with `--verbose`
- Ensure token hasn't expired with `--debug`

---

## Migration from Old Version:

If you were using the old separate scripts:

```bash
# Old way:
python3 api.py --token TOKEN --dry-run
python3 dm_automation.py --token TOKEN

# New unified way:
python3 main.py --dry-run --verbose                    # Simulation
python3 main.py --browser --verbose                    # Browser automation
```

---

## ✅ What's New in This Version:

- 🆕 **Unified CLI**: Single `main.py` for all automation modes
- 🆕 **Smart Configuration**: CLI → config.json → defaults precedence
- 🆕 **Verbose & Debug Modes**: See exactly what's happening
- 🆕 **Browser Integration**: Seamless switch between simulation and live automation
- 🆕 **Enhanced Filtering**: More control over thread selection
- 🆕 **Better Error Handling**: Graceful failures and helpful error messages
- 🆕 **Configuration Display**: See effective settings before running
- 🆕 **API Compatibility**: Handles different API response formats

The new system provides:
- ✅ **Smart targeting** with AI relevancy scoring
- ✅ **Flexible automation** modes (simulation vs live browser)
- ✅ **Advanced configuration** management with precedence rules
- ✅ **Comprehensive logging** and debugging capabilities
- ✅ **Better user experience** with verbose feedback
- ✅ **Robust error handling** and validation


# How to build the package

```bash
uv build
uv run twine upload dist/*
```

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "popsy-ai",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.9",
    "maintainer_email": null,
    "keywords": "ai, automation, dm, lead-generation, outreach, reddit",
    "author": null,
    "author_email": "Popsy AI <support@popsy.ai>",
    "download_url": null,
    "platform": null,
    "description": "# Reddit DM Automation - Unified API & Browser Integration\n\n## What You Need:\n- MacBook with macOS 10.15 or newer\n- Reddit account\n- Popsy API token\n- 30 minutes for setup\n\n---\n\n## Step 1: Install Python 3.11.9\n\n### Check if you have Python:\n```bash\npython3 --version\n```\n\n### If you don't have Python 3.11.9, install it:\n```bash\n# Install Homebrew first (copy and paste this whole line)\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# Install Python 3.11.9\nbrew install python@3.11\n```\n\n---\n\n## Step 2: Install Required Software\n\n```bash\n# Install the required libraries\npip3 install requests \"camoufox[geoip]\" browserforge\n\n# Download the special browser (this takes a few minutes)\npython3 -m camoufox fetch\n```\n\n---\n\n## Step 3: Unzip and go to the folder\n\n```bash\n# Go to the folder\ncd reddit-automation\n```\n\n---\n\n## Step 4: Get Your API Token\n\n1. **Login to Popsy Dashboard**\n2. **Get your API token** from settings\n3. **Set environment variable:**\n```bash\nexport POPSY_API_TOKEN=\"your-token-here\"\n```\n\nOr create a config file:\n```bash\n# Create config.json\n{\n  \"token\": \"your-api-token-here\",\n  \"base_url\": \"https://app.popsy.ai\",\n  \"min_relevancy\": 10,\n  \"max_threads\": 5,\n  \"show_new\": false,\n  \"hide_already_dmed\": true,\n  \"sort_by\": \"by_relevancy\"\n}\n```\n\n---\n\n## Step 5: Test the Connection (NEW Unified CLI)\n\n```bash\n# Test with simulation mode (no actual DMs sent)\npython3 main.py --dry-run --verbose --min-relevancy 80\n\n# Test with detailed debugging\npython3 main.py --debug --dry-run --show-new\n```\n\n---\n\n## Step 6: Choose Your Automation Mode\n\n### \ud83d\udd39 **API Simulation Mode** (Default - Safe Testing)\n```bash\n# Basic simulation - see what would happen\npython3 main.py --dry-run --verbose\n\n# Live simulation with API tracking\npython3 main.py --min-relevancy 80 --max-threads 3\n```\n\n### \ud83d\udd39 **Live Browser Automation** (Real DM Sending)\n```bash\n# Live browser automation with visible browser\npython3 main.py --browser --min-relevancy 80 --max-threads 3\n\n# Headless browser automation (background)\npython3 main.py --browser --headless --min-relevancy 9 --max-threads 2\n```\n\n---\n\n## \ud83c\udd95 New Advanced Features:\n\n### **Smart Configuration Management**\n- **Precedence**: CLI arguments \u2192 config.json \u2192 defaults\n- **Verbose mode**: See exactly what configuration is being used\n- **Debug mode**: Full API request/response logging\n\n```bash\n# See all configuration details\npython3 main.py --verbose --dry-run\n\n# Debug API calls and responses\npython3 main.py --debug --dry-run\n```\n\n### **Flexible Thread Filtering**\n```bash\n# Include new threads (default: false)\npython3 main.py --show-new --verbose\n\n# Hide threads from already-DMed authors (default: true)\npython3 main.py --hide-already-dmed\n\n# Show threads from already-DMed authors\npython3 main.py --show-already-dmed\n\n# Sort by relevance or recency\npython3 main.py --sort-by by_relevancy\npython3 main.py --sort-by by_date\n```\n\n### **Multiple Processing Modes**\n```bash\n# DM mode (default)\npython3 main.py --mode dm --browser\n\n# Comment mode (simulation only)\npython3 main.py --mode comment --dry-run\n```\n\n---\n\n## Daily Use Examples:\n\n### **Conservative Automation** (Recommended)\n```bash\n# High-quality leads only, visible browser\npython3 main.py --browser --min-relevancy 90 --max-threads 3 --verbose\n```\n\n### **Testing New Filters**\n```bash\n# Test different relevancy thresholds\npython3 main.py --dry-run --min-relevancy 60 --show-new --verbose\n\n# Test specific subreddit\npython3 main.py --subreddit-id 123 --dry-run --debug\n```\n\n### **Bulk Processing** (Advanced Users)\n```bash\n# Background automation with higher volume\npython3 main.py --browser --headless --min-relevancy 80 --max-threads 10\n```\n\n---\n\n## \ud83d\ude80 Complete Configuration Options:\n\n### **Core Settings:**\n- `--token`: Your Popsy API authentication token\n- `--base-url`: API base URL (default: https://app.popsy.ai)\n- `--config`: Configuration file path (default: config.json)\n\n### **Thread Filtering:**\n- `--min-relevancy`: Minimum relevancy score 1-10 (default: 7)\n- `--max-threads`: Maximum threads to process (default: 100)\n- `--subreddit-id`: Filter by specific subreddit ID\n- `--page-size`: Threads per API page (default: 50)\n- `--sort-by`: Sort by 'by_relevancy' or 'by_date' (default: by_date)\n\n### **Thread Type Filters:**\n- `--show-new`: Include new threads (default: false)\n- `--dm-sent`: Include threads with DMs sent (default: false)\n- `--comment-sent`: Include threads with comments sent (default: false)\n- `--show-deleted`: Include deleted threads (default: false)\n- `--hide-already-dmed`: Hide previously contacted authors (default: true)\n- `--show-already-dmed`: Override hide setting\n\n### **Processing Mode:**\n- `--mode`: Choose 'dm' or 'comment' processing (default: dm)\n- `--dry-run`: Test without sending actual DMs/comments\n\n### **Browser Automation:**\n- `--browser` / `--live`: Use live browser automation (requires camoufox)\n- `--headless`: Run browser in background mode\n- `--browser-delay`: Custom delay between actions (seconds)\n\n### **Debugging & Logging:**\n- `--verbose` / `-v`: Show detailed configuration and processing info\n- `--debug`: Enable full API request/response logging\n\n---\n\n## File Structure:\n\n```\nreddit-dm-tool/\n\u251c\u2500\u2500 main.py                   # \ud83c\udd95 Unified CLI interface\n\u251c\u2500\u2500 api.py                    # Core API client library\n\u251c\u2500\u2500 dm_automation.py          # Browser automation library\n\u251c\u2500\u2500 config.json              # Your configuration\n\u251c\u2500\u2500 logs/\n\u2502   \u251c\u2500\u2500 api_client_YYYY-MM-DD.log\n\u2502   \u251c\u2500\u2500 sent_messages_YYYY-MM-DD.csv\n\u2502   \u2514\u2500\u2500 sent_comments_YYYY-MM-DD.csv\n\u2514\u2500\u2500 browser_data/            # Persistent browser session\n```\n\n---\n\n## \ud83c\udd95 Enhanced Features:\n\n### **Smart Configuration Display**\n```bash\npython3 main.py --verbose --dry-run\n```\nShows:\n- \u2705 **Command line arguments** you used\n- \u2705 **Configuration file values** loaded\n- \u2705 **Environment variables** detected\n- \u2705 **Effective values** after precedence resolution\n\n### **Robust Error Handling**\n- \u2705 **API response validation** (handles different response formats)\n- \u2705 **Browser dependency checking** (graceful fallback if camoufox not installed)\n- \u2705 **Configuration validation** (ensures compatible settings)\n\n### **Flexible Automation**\n- \u2705 **Simulation mode**: Test with API tracking but no actual sends\n- \u2705 **Browser mode**: Live DM sending with real browser\n- \u2705 **Headless mode**: Background automation for scheduled runs\n\n---\n\n## Configuration Examples:\n\n### **Conservative Setup** (config.json)\n```json\n{\n  \"token\": \"your-token-here\",\n  \"base_url\": \"https://app.popsy.ai\",\n  \"min_relevancy\": 90,\n  \"max_threads\": 3,\n  \"show_new\": false,\n  \"hide_already_dmed\": true,\n  \"sort_by\": \"by_relevancy\"\n}\n```\n\n### **Testing Setup** (config.json)\n```json\n{\n  \"token\": \"your-token-here\",\n  \"min_relevancy\": 60,\n  \"max_threads\": 10,\n  \"show_new\": true,\n  \"hide_already_dmed\": false,\n  \"sort_by\": \"by_date\"\n}\n```\n\n---\n\n## Troubleshooting:\n\n**\ud83d\udd27 Browser Issues:**\n```bash\npython3 -m camoufox remove\npython3 -m camoufox fetch\n```\n\n**\ud83d\udd27 Configuration Issues:**\n```bash\n# See what configuration is actually being used\npython3 main.py --verbose --dry-run\n\n# Debug API communication\npython3 main.py --debug --dry-run\n```\n\n**\ud83d\udd27 No threads found?**\n- Check your API token is valid: `--debug` shows request details\n- Lower the `--min-relevancy` score\n- Try `--show-new` to include new threads\n- Use `--show-already-dmed` to see previously contacted authors\n- Verify you have tracked subreddits in Popsy dashboard\n\n**\ud83d\udd27 API connection failed?**\n- Check internet connection\n- Verify `--base-url` is correct with `--verbose`\n- Ensure token hasn't expired with `--debug`\n\n---\n\n## Migration from Old Version:\n\nIf you were using the old separate scripts:\n\n```bash\n# Old way:\npython3 api.py --token TOKEN --dry-run\npython3 dm_automation.py --token TOKEN\n\n# New unified way:\npython3 main.py --dry-run --verbose                    # Simulation\npython3 main.py --browser --verbose                    # Browser automation\n```\n\n---\n\n## \u2705 What's New in This Version:\n\n- \ud83c\udd95 **Unified CLI**: Single `main.py` for all automation modes\n- \ud83c\udd95 **Smart Configuration**: CLI \u2192 config.json \u2192 defaults precedence\n- \ud83c\udd95 **Verbose & Debug Modes**: See exactly what's happening\n- \ud83c\udd95 **Browser Integration**: Seamless switch between simulation and live automation\n- \ud83c\udd95 **Enhanced Filtering**: More control over thread selection\n- \ud83c\udd95 **Better Error Handling**: Graceful failures and helpful error messages\n- \ud83c\udd95 **Configuration Display**: See effective settings before running\n- \ud83c\udd95 **API Compatibility**: Handles different API response formats\n\nThe new system provides:\n- \u2705 **Smart targeting** with AI relevancy scoring\n- \u2705 **Flexible automation** modes (simulation vs live browser)\n- \u2705 **Advanced configuration** management with precedence rules\n- \u2705 **Comprehensive logging** and debugging capabilities\n- \u2705 **Better user experience** with verbose feedback\n- \u2705 **Robust error handling** and validation\n\n\n# How to build the package\n\n```bash\nuv build\nuv run twine upload dist/*\n```\n",
    "bugtrack_url": null,
    "license": "Copyright 2025 Popsy Labs, Inc.",
    "summary": "Reddit DM automation CLI using Popsy AI for lead generation and outreach",
    "version": "0.0.5",
    "project_urls": {
        "Homepage": "https://popsy.ai"
    },
    "split_keywords": [
        "ai",
        " automation",
        " dm",
        " lead-generation",
        " outreach",
        " reddit"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "d60457ae878fd80c65e6419c47b82c4fdb07180aba3e9bdfebd09fd0d363c665",
                "md5": "251dd436eba0b0833eda40f8bdb0354c",
                "sha256": "5734ed27f4eebcadc2c4633ac5892d12bf4f90fd9e4a68da3194db7be2071a86"
            },
            "downloads": -1,
            "filename": "popsy_ai-0.0.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "251dd436eba0b0833eda40f8bdb0354c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.9",
            "size": 14301,
            "upload_time": "2025-07-10T10:50:04",
            "upload_time_iso_8601": "2025-07-10T10:50:04.755761Z",
            "url": "https://files.pythonhosted.org/packages/d6/04/57ae878fd80c65e6419c47b82c4fdb07180aba3e9bdfebd09fd0d363c665/popsy_ai-0.0.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-10 10:50:04",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "lcname": "popsy-ai"
}