Flow-Mailer Documentation

Flow-Mailer Documentation

Introduction

Flow-Mailer is a powerful, self-hosted email marketing platform built with Laravel and Filament. It provides a complete solution for managing email campaigns, contacts, and delivery infrastructure.

Key Features

  • Campaign management with scheduling and rate limiting
  • Contact organization with groups, segments, and categories
  • Multiple SMTP server support with automatic rotation
  • Import/Export functionality for contacts
  • Blacklist management for emails and domains
  • Dynamic content generation using Faker
  • Comprehensive email delivery tracking
  • Demo mode for safe testing

Installation

Requirements

  • PHP 8.2 or higher
  • MySQL 8.0+ or SQLite
  • Composer
  • Node.js & Yarn
  • Redis (optional, for caching)

Installation Steps

1. Clone the repository:

git clone https://github.com/your-repo/flow-mailer.git
cd flow-mailer

2. Install PHP dependencies:

composer install

3. Install JavaScript dependencies:

yarn install

4. Copy environment file:

cp .env.example .env

5. Generate application key:

php artisan key:generate

6. Configure your database in .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=flow_mailer
DB_USERNAME=your_username
DB_PASSWORD=your_password

7. Run migrations:

php artisan migrate

8. Create an admin user:

php artisan make:filament-user

9. Build assets:

npm run build

10. Start the development server:

composer dev

Configuration

Environment Variables

Key environment variables to configure:

APP_NAME="Flow-Mailer"
APP_URL=http://your-domain.com
DEMO_MODE=false  # Set to true for demo mode

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

# Queue Configuration
QUEUE_CONNECTION=database

# Cache Configuration
CACHE_STORE=redis

Queue Workers

For production, set up queue workers:

php artisan queue:work --queue=emails,campaigns,default --tries=3

Campaigns

Creating a Campaign

Campaigns are created through a multi-step wizard:

  1. Basic Information: Name, subject, sender details
  2. Content: Email body with dynamic placeholders
  3. Recipients: Select contact groups, segments, or databases
  4. Settings: Language, tracking options, UTM parameters
  5. Rate Limiting: Custom sending limits per time period
  6. Schedule: Immediate or scheduled sending

Campaign Fields

  • Email Subject: Supports Faker placeholders like {{company}}
  • Sender Email/Name: Override default server settings
  • Language: Sets email HTML language attribute
  • Track Opens/Clicks: Enable engagement tracking
  • UTM Parameters: For Google Analytics tracking

Sending a Campaign

Via artisan command:

php artisan email:send-campaign 1 --mailable=App\\Mail\\CampaignMail

Contacts

Contact Management

Contacts can be organized using:

  • Groups: Static collections of contacts
  • Segments: Dynamic filters based on conditions
  • Categories: Tag-based organization
  • Databases: Separate contact collections
  • Regions: Geographic organization

Importing Contacts

CSV import features:

  • Automatic database creation/assignment
  • Duplicate detection by email
  • Failed row tracking and download
  • Many-to-many database relationships

Contact Fields

  • Email (required, unique)
  • First Name / Last Name
  • Company Name / Status
  • Phone Number
  • Multiple Regions assignment
  • Sent status tracking

Delivery Servers

Server Types

  • SMTP: Standard SMTP servers
  • Amazon SES: AWS Simple Email Service
  • Mailgun: Mailgun API
  • SendGrid: SendGrid API
  • SparkPost: SparkPost API

Server Configuration

Key settings for each server:

  • Connection Details: Host, port, encryption
  • Authentication: Username/password or API keys
  • Quota Limits: Per second/minute/hour/day/month
  • From Settings: Default sender email/name
  • Usage: Campaign, transactional, or all

Testing Servers

Use the "Send Test Email" button when creating/editing servers to verify configuration before saving.

Email Sending System

Architecture

The email sending system includes:

  • EmailSendingService: Core sending logic
  • Server Rotation: Automatic selection based on quotas
  • Quota Management: Real-time usage tracking
  • Retry Logic: Automatic retries with backoff
  • Comprehensive Logging: All activities tracked

Email Commands

# Send campaign
php artisan email:send-campaign {campaign_id}

# View statistics
php artisan email:stats
php artisan email:stats --period=week
php artisan email:stats --server=1

# Monitor queue
php artisan queue:status
php artisan queue:status --watch

Email Status Tracking

  • pending: Queued for sending
  • sending: Currently being processed
  • sent: Successfully sent to SMTP
  • delivered: Confirmed delivery
  • failed: Sending failed
  • bounced: Email bounced
  • complained: Marked as spam

Rate Limiting

Server-Level Limits

Each delivery server supports:

  • Second Quota: Max emails per second
  • Minute Quota: Max emails per minute
  • Hourly Quota: Max emails per hour
  • Daily Quota: Max emails per day
  • Monthly Quota: Max emails per month
  • Pause After Send: Delay between emails

Campaign-Level Limits

Campaigns can override server limits with custom settings:

  • Enable "Use Custom Rate Limits" in campaign settings
  • Set specific limits for the campaign
  • Useful for warming up new IP addresses
  • Batch size control for job processing

Dynamic Content with Faker

Using Faker Placeholders

Add dynamic content to campaigns using double curly braces:

Dear {{firstName}} {{lastName}},

Welcome to {{company}}! Your account at {{domainName}} is ready.

Best regards,
{{name}}
{{jobTitle}}

Available Placeholders

Personal Information

  • {{firstName}}, {{lastName}}, {{name}}
  • {{email}}, {{safeEmail}}
  • {{phoneNumber}}, {{e164PhoneNumber}}

Company Information

  • {{company}}, {{companySuffix}}
  • {{jobTitle}}, {{bs}}

Text Generation

  • {{sentence}}, {{paragraph}}
  • {{text:200}} - Generate 200 characters
  • {{words:5}} - Generate 5 words

Dates and Numbers

  • {{date}}, {{time}}
  • {{randomNumber:1000}} - Max 1000
  • {{numberBetween:10:100}} - Between 10-100

Demo Mode

Enabling Demo Mode

Set in your .env file:

DEMO_MODE=true

Demo Mode Features

  • No data is saved to the database
  • Emails are simulated, not actually sent
  • Yellow warning banner in admin panel
  • All operations return success without changes
  • Perfect for testing and demonstrations

Technical Implementation

  • DemoModeMiddleware: Intercepts HTTP requests
  • DemoModeServiceProvider: Model-level protection
  • Service Updates: Email sending simulated

API Reference

Authentication

API authentication uses Laravel Sanctum tokens.

Endpoints

Campaigns

GET    /api/campaigns
POST   /api/campaigns
GET    /api/campaigns/{id}
PUT    /api/campaigns/{id}
DELETE /api/campaigns/{id}
POST   /api/campaigns/{id}/send

Contacts

GET    /api/contacts
POST   /api/contacts
GET    /api/contacts/{id}
PUT    /api/contacts/{id}
DELETE /api/contacts/{id}
POST   /api/contacts/import

Delivery Servers

GET    /api/deliver-servers
POST   /api/deliver-servers
GET    /api/deliver-servers/{id}
PUT    /api/deliver-servers/{id}
DELETE /api/deliver-servers/{id}
POST   /api/deliver-servers/{id}/test

Example Request

curl -X POST http://your-domain.com/api/campaigns \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Campaign",
    "subject": "Welcome to {{company}}",
    "content": "Hello {{firstName}}, welcome!",
    "sender_email": "[email protected]"
  }'

Complete Feature Reference

Based on the actual codebase implementation, Flow-Mailer includes the following features:

Email Sending System

Core Components

  • EmailSendingService: Main service handling all email delivery operations
  • Multi-server rotation: Automatic selection of available servers based on quotas
  • Quota enforcement: Real-time tracking across 5 time periods (second, minute, hour, day, month)
  • Campaign-level rate limits: Override server defaults with custom limits per campaign
  • Retry mechanism: Automatic retries with exponential backoff
  • Demo mode support: Simulate sending without actual delivery

Background Jobs

  • SendCampaignEmailJob: Individual email sending with retry logic
  • ProcessCampaignJob: Batch processing for entire campaigns
  • ImportContactsDatabaseJob: Asynchronous CSV import processing

Contact Management System

Contact Organization

  • Contacts: Core entity with email, name, company, business status
  • Contact Databases: Separate collections with import status tracking
  • Contact Groups: Static collections for manual organization
  • Contact Segments: Dynamic filtering with conditions
  • Contact Categories: Industry/type classification
  • Geographic Hierarchy: Countries and regions with parent-child relationships

Import System Features

  • CSV import with automatic column mapping
  • Automatic database creation/assignment
  • Duplicate detection and merging
  • Quality score calculation
  • Failed row tracking and download
  • Many-to-many database relationships

Contact Database Status Flow

  1. ready_to_import - File uploaded, awaiting processing
  2. importing - Currently being processed
  3. imported - Successfully imported
  4. available_for_purchase - Can be purchased
  5. purchased - Purchased and active

Campaign Management

Campaign Features

  • Multi-step wizard: Guided campaign creation
  • WYSIWYG editor: Visual email content editing
  • Recipient targeting: Select groups, segments, or databases
  • Custom rate limiting: Campaign-specific sending speeds
  • Language support: Set email HTML language attribute
  • UTM tracking: Google Analytics integration
  • Open/click tracking: Engagement analytics
  • Scheduling: Send immediately or at specified time

Campaign Rate Limits

  • emails_per_second - Max emails per second
  • emails_per_minute - Max emails per minute
  • emails_per_hour - Max emails per hour
  • emails_per_day - Max emails per day
  • pause_between_emails - Delay in seconds
  • batch_size - Jobs per batch (default: 100)

Delivery Server Management

Server Types

  • SMTP: Standard SMTP configuration
  • Amazon SES: AWS integration (planned)
  • Mailgun: Mailgun API (planned)
  • SendGrid: SendGrid API (planned)
  • SparkPost: SparkPost API (planned)

Server Features

  • Test email functionality before saving
  • Quota limits across 5 time periods
  • Automatic rotation based on availability
  • Force from email/name override
  • Reply-to configuration
  • Usage designation (campaign, transactional, all)

Email Filtering & Security

Blacklist Management

  • Email Blacklist: Block individual email addresses
  • Domain Blacklist: Block entire domains
  • Import/export blacklist entries
  • Automatic filtering during send

Proxy Support

  • Multiple proxy server configuration
  • Proxy rotation for sending
  • Authentication support

Analytics & Tracking

Email Log Tracking

  • Status tracking: pending, sending, sent, delivered, failed, bounced, complained
  • Timestamps: attempted_at, sent_at, delivered_at, opened_at, clicked_at, failed_at, bounced_at
  • Performance metrics: send_time_ms, response tracking
  • Error logging: Detailed error messages for failures

Statistics Commands

# Overall statistics
php artisan email:stats

# Weekly statistics
php artisan email:stats --period=week

# Server-specific stats
php artisan email:stats --server=1

# Refresh cache
php artisan email:stats --refresh

Advanced Segmentation

Segment Types

  • Static Segments: Manual contact assignment
  • Dynamic Segments: Automatic based on conditions

Dynamic Conditions

  • Field-based filtering (email, name, company, etc.)
  • Engagement-based (sent, opened, clicked)
  • Geographic (country, region)
  • Category/group membership
  • Custom field conditions

Live Inbox System

Inbox Features

  • Multiple inbox server configuration
  • Email processing rules
  • Automatic bounce handling
  • Complaint processing

Queue Management

Queue Features

  • Multiple queue priorities: emails, campaigns, default
  • Failed job handling with retries
  • Real-time monitoring
  • Queue status command for monitoring

Queue Commands

# Start queue worker
php artisan queue:work --queue=emails,campaigns,default --tries=3

# Monitor queue status
php artisan queue:status

# Watch queue in real-time
php artisan queue:status --watch

Developer Tools

Demo Mode

  • Enable via DEMO_MODE=true in .env
  • Intercepts all save/update/delete operations
  • Simulates email sending without delivery
  • Shows warning banner in admin panel

Logging

  • Dedicated email_sending log channel
  • Comprehensive operation logging
  • Performance tracking
  • Error tracking with context

Testing

  • Pest PHP testing framework
  • Feature and unit test structure
  • Factory support for all models

Database Schema

Core Tables

  • campaigns - Campaign configuration and settings
  • contacts - Contact information and engagement
  • deliver_servers - SMTP/API server configuration
  • email_logs - Complete email history
  • server_quota_usages - Real-time quota tracking

Organization Tables

  • contacts_databases - Database metadata
  • contact_segments - Segment definitions
  • contact_groups - Group definitions
  • contact_categories - Category list
  • contact_countries - Country list
  • contact_regions - Hierarchical regions

Relationship Tables

  • contact_contacts_database - Contact to database mapping
  • contact_contact_segment - Contact to segment mapping
  • contact_contact_group - Contact to group mapping
  • contact_region - Contact to region mapping

Infrastructure Tables

  • blacklist_emails - Email blacklist
  • blacklist_domains - Domain blacklist
  • proxies - Proxy configuration
  • proxy_servers - Proxy server details
  • live_inboxes - Inbox configuration
  • live_inbox_servers - Inbox servers
  • live_inbox_rules - Processing rules