Getting Started

FluentCRM Core Developer Guide

FluentCRM is a self-hosted email marketing and CRM plugin for WordPress. It runs entirely on your WordPress site — no external API calls for contact storage or email management. This guide covers what you need to know to extend it.

Architecture Overview

FluentCRM is built on WPFluent, a Laravel-like framework for WordPress. It follows MVC patterns with Eloquent-style models, a route/controller/policy system for REST APIs, and a Vue 3 frontend.

Key technical details:

• PHP namespace: FluentCrm\App\ and FluentCrm\Includes\
• REST API base: /wp-json/fluent-crm/v2/
• DB table prefix: fc_ (e.g., fc_subscribers, fc_campaigns, fc_funnels)
• Hook prefixes: fluentcrm_ (legacy) and fluent_crm/ (current)
• Frontend: Vue 3 with Element Plus, Pinia for state management
• Email editor: Custom Gutenberg block editor for email composition

Directory Structure

fluent-crm/
├── app/
│   ├── Api/                 # Public PHP API classes (Contacts, Companies)
│   ├── Functions/           # Global helper functions (helpers.php)
│   ├── Hooks/               # Hook handler classes
│   │   └── Handlers/        # AdminMenu, ExternalPages, Scheduler, etc.
│   ├── Http/
│   │   ├── Controllers/     # REST API controllers
│   │   ├── Policies/        # Permission & access control policies
│   │   └── Routes/          # Route definitions (api.php)
│   ├── Models/              # Eloquent-style database models
│   ├── Modules/             # Feature modules (AbandonCart, etc.)
│   ├── Services/            # Business logic
│   │   ├── Funnel/          # Automation engine (triggers, actions, benchmarks)
│   │   └── Libs/            # Mailer, parser, file system
│   └── Views/               # PHP templates (external pages, admin)
├── boot/                    # Plugin bootstrap (app.php)
├── config/                  # Configuration files
├── database/                # Migrations and schema
├── resources/               # Frontend source (Vue, JS, CSS)
│   ├── admin/               # Admin Vue app (Options API)
│   └── v3app/               # V3 app modules (Pinia stores)
├── custom-editor/           # Gutenberg email editor
└── fluent-crm.php           # Plugin entry point

Core Concepts

Data Model

FluentCRM's data model centers around contacts (subscribers) with relationships to campaigns, tags, lists, and automations.

Table	Model	Purpose
fc_subscribers	Subscriber	Contacts — the central entity
fc_campaigns	Campaign	Email campaigns (one-time broadcasts)
fc_campaign_emails	CampaignEmail	Individual emails sent per campaign per contact
fc_tags	Tag	Flexible contact labels for segmentation
fc_lists	Lists	Contact groups for organizing subscribers
fc_funnels	Funnel	Automation workflows
fc_funnel_sequences	FunnelSequence	Steps within an automation
fc_meta	Meta	Shared key-value store (multiple types)
fc_subscriber_notes	SubscriberNote	Contact notes and activity logs
fc_companies	Company	Company/organization records

See the full Database Schema and Models Reference for details.

Automation System

Automations (funnels) use three building blocks:

• Triggers — Events that start a workflow (form submission, tag added, purchase, etc.)
• Actions — Steps executed in sequence (send email, add tag, wait, webhook, etc.)
• Benchmarks — Goal checkpoints a contact must reach (link clicked, purchase made, etc.)

Hook System

FluentCRM provides 200+ hooks for extending functionality:

• Action Hooks — Run custom code when events occur (contact created, email sent, campaign completed, etc.)
• Filter Hooks — Modify data before it's used (email headers, contact statuses, admin menus, etc.)

REST API

The REST API provides full programmatic access to all CRM data. All endpoints require authentication.

• Authentication — Cookie-based (wp_nonce) or Application Passwords
• Contacts API — CRUD operations on subscribers
• Campaigns API — Create and manage email campaigns
• Tags & Lists — Manage segmentation
• Webhooks — Inbound data via webhook endpoints

See the full REST API Reference.

Extension Points

Adding Custom Functionality

What you want to do	Where to look
Run code when a contact is created/updated	Contact Action Hooks
Modify email content before sending	Email Filters
Add a custom automation trigger	Custom Trigger Module
Add a custom automation action	Custom Action Module
Add a tab to the contact profile	Profile Section Module
Add custom smart codes for emails	Smart Code Module
Track custom events on contacts	Event Tracking Module
Add custom REST API endpoints	Extending the REST API
Customize the admin dashboard	Dashboard Filters
Modify frontend pages (unsubscribe, DOI)	Frontend Filters

Helper Utilities

FluentCRM includes helper classes and global functions:

• Global Functions — fluentcrm_get_option(), fluentCrmApi(), contact creation helpers
• Arr Helper — Array manipulation utilities
• Str Helper — String manipulation utilities
• Service Helper — CRM service utilities

Development Setup

Requirements:

• WordPress 5.6+
• PHP 7.4+
• MySQL 5.6+ (InnoDB)

Build tools (only needed if modifying frontend):

pnpm install && pnpm run dev   # Vite dev server
pnpm run build                 # Production build

Custom email editor (only if modifying the Gutenberg editor):

cd custom-editor && npm install && npm run build

Next Steps

• Database Schema — Understand the data structure
• Models Reference — Learn the Eloquent-style models and relationships
• Action Hooks — Hook into contact, campaign, and automation events
• Filter Hooks — Modify emails, settings, menus, and more
• REST API — Build integrations with the API
• Modules — Create custom triggers, actions, and profile sections