Skip to content

About

Open-source AI agent for B2B lead generation — describe your product, it finds the people who fit, explains why each one does, and emails them from your mailbox. Self-hosted CLI, one install.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

OpenCRM

Free, open-source CRM with lead automation, AI email generation, campaigns, and a full pipeline dashboard — self-host it in minutes.

Python Version Docker License

What It Does

  • Ingest leads automatically from Meta (Facebook) Lead Ads, webhooks, or manual entry
  • Manage your pipeline with a kanban board, table view, notes, follow-up reminders, and deal tracking
  • Send outreach emails via Outlook (Microsoft Graph) or Mailgun
  • Generate email copy with AI using any OpenAI-compatible API, Anthropic, or local models via Ollama
  • Run campaigns — filter your lead database, generate AI copy, and blast or drip emails
  • Track everything — reporting dashboard with conversion funnel, source attribution, pipeline value, and leads over time

Connectors are pluggable. Meta and Outlook/Mailgun are the built-in connectors, but the architecture is designed to be extended. Want to pull leads from Google Ads, HubSpot, or Typeform? Want to send via SendGrid or AWS SES? Add a connector — see Connectors below.

┌──────────────┐          ┌──────────────┐         ┌──────────────┐
│   Meta API   │          │   SQLite DB  │         │  Outlook /   │
│  Lead Fetch  │──────────│   Storage    │─────────│  Mailgun     │
│              │          │              │         │  Email Send  │
└──────────────┘          └──────────────┘         └──────────────┘
                                 │
              ┌──────────────────┼──────────────────┐
              │                  │                  │
        ┌─────┴─────┐    ┌──────┴──────┐    ┌──────┴──────┐
        │ Dashboard │    │  Campaigns  │    │   LLM AI    │
        │ (Flask)   │    │  & Sequences│    │  (optional) │
        └───────────┘    └─────────────┘    └─────────────┘

Quick Start

1. Clone & Configure

git clone <repository-url>
cd opencrm
cp .env.example .env

Edit .env with your credentials:

# Meta API
META_PAGE_ID=your_page_id
META_PAGE_ACCESS_TOKEN=your_token

# Microsoft Graph API (Outlook)
MS_TENANT_ID=your_tenant_id
MS_CLIENT_ID=your_client_id
MS_CLIENT_SECRET=your_client_secret
MS_SENDER_EMAIL=you@yourdomain.com

# Booking URL (included in outreach emails)
BOOKING_URL=https://calendly.com/you/30min

# Branding
SENDER_NAME=Jane Smith
COMPANY_NAME=Acme Corp
COMPANY_DESCRIPTION=We help small businesses grow with custom software

# AI Email Generation (optional — any OpenAI-compatible API)
LLM_API_KEY=sk-...
# LLM_MODEL=gpt-4o
# LLM_BASE_URL=http://localhost:11434/v1  # for Ollama

2. Run with Docker

docker-compose up -d

This starts two services:

  • Pipeline (port 9010) — polls Meta for new leads, sends automated emails
  • Dashboard (port 5050) — web UI for managing leads, campaigns, and reporting

3. Open the Dashboard

Visit http://localhost:5050 — default login: admin / admin

Change credentials via DASHBOARD_USERNAME and DASHBOARD_PASSWORD in .env.

4. Verify

curl http://localhost:9010/health

Features

Lead Pipeline

  • Automated Meta Lead Ads polling (configurable interval, default 15 min)
  • Webhook ingestion — POST /api/webhook/leads for any external source (Zapier, forms, n8n, etc.)
  • Manual lead entry via dashboard
  • Duplicate detection by lead ID
  • Intelligent field mapping (email, name, phone, company, job title)
  • Status tracking: intake → emailed → contacted → qualified → closed

CRM Features

  • Notes — add timestamped notes to any lead
  • Follow-up reminders — set reminder dates, see overdue/upcoming in dashboard
  • Deal tracking — deal value and expected close date per lead
  • Pipeline value — aggregate deal value across your funnel
  • Lead assignment — assign leads to team members
  • Tagging — industry, source, custom tags

Email & Campaigns

  • Microsoft Graph API (Outlook/Exchange) via OAuth2
  • Mailgun support for campaign sends
  • SMTP fallback (USE_SMTP=true)
  • Configurable HTML email templates with {name} variable substitution
  • AI email generation — works with OpenAI, Anthropic, Ollama, or any OpenAI-compatible endpoint
  • Campaigns — filter leads by status/source/search, generate AI copy, send to matching leads
  • Email sequences — multi-step drip campaigns with configurable delays

Dashboard

  • Table view — sortable, filterable, searchable, paginated

  • Kanban board — drag-free pipeline visualization with deal values and reminder badges

  • Reports — conversion funnel, leads by source, pipeline value by status, leads over time (30 days)

  • Campaign builder — create campaigns with live audience preview, AI copy generation, and one-click send

  • Sequence manager — create multi-step email sequences, enroll/unenroll leads

  • User management — multi-user with admin/user roles

Operations

  • Docker containerization with health checks and auto-restart
  • Graceful shutdown (SIGTERM/SIGINT)
  • Structured logging with rotation
  • Retry logic with exponential backoff
  • Thread-safe SQLite with connection pooling

Configuration

All configuration is via environment variables. See .env.example for the complete list with documentation.

Required

Variable Description
META_PAGE_ID Facebook Page ID
META_PAGE_ACCESS_TOKEN Page Access Token with leads_retrieval permission
MS_TENANT_ID Azure AD Tenant ID
MS_CLIENT_ID Azure App Client ID
MS_CLIENT_SECRET Azure App Client Secret
MS_SENDER_EMAIL Email address to send from
BOOKING_URL Scheduling link included in outreach emails

Branding

Variable Description Default
SENDER_NAME Name in email signature The Team
COMPANY_NAME Company name in emails (empty)
COMPANY_DESCRIPTION Used by AI email generation (empty)

AI (Optional)

Variable Description Default
LLM_API_KEY API key for AI features (disabled)
LLM_MODEL Model to use gpt-4o
LLM_BASE_URL Custom endpoint (Ollama, Together, etc.) (provider default)
LLM_PROVIDER openai or anthropic (auto-detected from key) openai

Email Providers (Optional)

Variable Description Default
MAILGUN_API_KEY Mailgun API key (for campaigns) (disabled)
MAILGUN_DOMAIN Mailgun sending domain (empty)
MAILGUN_SENDER_EMAIL Mailgun sender address campaigns@{domain}
WEBHOOK_API_KEY API key for webhook ingestion (disabled)

Other

Variable Description Default
POLL_INTERVAL_SECONDS Lead polling interval 900 (15 min)
DB_PATH SQLite database path /app/data/leads.db
LOG_LEVEL Logging verbosity INFO
DASHBOARD_USERNAME Dashboard login admin
DASHBOARD_PASSWORD Dashboard password admin

Webhook API

To ingest leads from external sources, set WEBHOOK_API_KEY in your .env and POST to:

curl -X POST http://localhost:5050/api/webhook/leads \
  -H "Authorization: Bearer YOUR_WEBHOOK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "company_name": "Acme Corp",
    "lead_source": "website"
  }'

Accepts single objects or arrays. Works with Zapier, Make, n8n, custom forms, or any HTTP client.


Connectors

OpenCRM ships with connectors for Meta Lead Ads (inbound) and Outlook/Mailgun (outbound), but it's built to be extended. You don't need Meta or Outlook to use this CRM — leads can come in via the webhook API, manual entry, or a custom connector you write.

Lead Source Connectors

To add a new lead source (e.g. Google Ads, HubSpot, Typeform), use meta_client.py as a template:

  1. Copy meta_client.py to a new file (e.g. google_ads_client.py)
  2. Implement a client class with a get_all_leads() method that returns a list of lead dicts with the standard fields (lead_id, email, full_name, first_name, last_name, phone_number, company_name, job_title, created_time, raw_field_data)
  3. Wire it into lead_processor.py or call it from your own script
  4. Or skip all that and just POST leads to the webhook endpoint — that works with any source, no code required

Email Provider Connectors

To add a new email provider (e.g. SendGrid, AWS SES, generic SMTP), use the _send_via_mailgun() function in dashboard.py as a template:

  1. Add your provider's config vars (API key, domain, etc.) to .env.example and load them at the top of dashboard.py
  2. Write a _send_via_yourprovider(to_email, subject, html_body) function
  3. Add your provider to the api_email_providers() endpoint
  4. Add an elif provider == 'yourprovider': branch in api_campaign_send()

LLM Connectors

AI email generation already works with any OpenAI-compatible API out of the box. Just set LLM_BASE_URL to your provider's endpoint. This covers OpenAI, Ollama (local), Together, Groq, Fireworks, and many others.

Contributing a Connector

We'd love community-contributed connectors. To submit one:

  1. Fork the repo
  2. Add your connector following the patterns above
  3. Update .env.example with any new config vars
  4. Submit a PR with a brief description of what it connects to

Prerequisites

Meta (Facebook) Setup

  1. Go to Facebook Developers
  2. Create or select your app
  3. Generate a Page Access Token with leads_retrieval permission
  4. Get your Page ID from Page Settings

Microsoft Azure Setup

  1. Go to Azure Portal
  2. Navigate to Azure AD → App registrations → New registration
  3. Copy the Application (client) ID and Directory (tenant) ID
  4. Create a Client Secret under Certificates & secrets
  5. Grant API permissions: Mail.Send, Mail.ReadWrite
  6. Grant admin consent

Project Structure

├── main.py              # Entry point — orchestrates the polling loop
├── config.py            # Configuration loading & validation
├── database.py          # SQLite operations (CRUD, schema, migrations)
├── meta_client.py       # Meta Graph API client (lead fetching)
├── email_client.py      # Microsoft Graph API + SMTP email sending
├── lead_processor.py    # Lead ingestion orchestration
├── email_sender.py      # Email sending orchestration
├── templates.py         # HTML/text email templates
├── dashboard.py         # Flask web dashboard (all features)
├── health_check.py      # HTTP health check server
├── logger.py            # Centralized logging
├── scripts/
│   ├── init_db.py       # Database initialization
│   ├── manual_send.py   # Manual email testing
│   └── test_credentials.py  # Credential validation
├── Dockerfile           # Multi-stage Docker build
├── docker-compose.yml   # Service orchestration
├── .env.example         # Configuration template
└── requirements.txt     # Python dependencies

Roadmap

  • PostgreSQL database support
  • Lead scoring and prioritization
  • A/B testing for email templates
  • Email open/click tracking (via Mailgun webhooks)
  • Reply detection and auto-status update
  • Slack/Discord notifications
  • Kubernetes Helm charts
  • Contact deduplication and merging

Security

Do NOT open public GitHub issues for security vulnerabilities. Please report them via the repository's security advisory feature or contact us directly.


License

MIT License — see LICENSE for details.


About

Open-source AI agent for B2B lead generation — describe your product, it finds the people who fit, explains why each one does, and emails them from your mailbox. Self-hosted CLI, one install.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages