README

A comprehensive email marketing package for Laravel with campaigns, templates, tracking, and rate limiting. SaaS-ready with multi-tenancy support.

Features

• Email Templates - Create and manage reusable email templates with variable support
• Campaigns - Organize email sends into campaigns with statistics
• Open Tracking - Track when recipients open emails via tracking pixel
• Click Tracking - Track link clicks with automatic URL wrapping
• Rate Limiting - Built-in rate limiting (configurable, default 10 emails/hour)
• Queue Support - Send emails via Laravel queues with random delays
• Bounce Detection - Automatic detection of bounced/invalid emails
• SMTP Configuration - Configure SMTP settings from admin panel (stored in database)
• Multi-tenancy - SaaS-ready with per-tenant SMTP settings
• Admin Dashboard - Full admin interface for managing everything
• Standalone Layout - Works out of the box with built-in Bootstrap 5 admin panel

Requirements

• PHP 8.1+
• Laravel 8.x, 9.x, 10.x, or 11.x
• Redis (recommended for queues)

Installation

composer require dinara/email-marketing

Run migrations:

php artisan migrate

Optionally publish configuration:

php artisan vendor:publish --tag=email-marketing-config

Optionally publish views for customization:

php artisan vendor:publish --tag=email-marketing-views

Configuration

Minimal Setup

Add to your .env file:

# Required: Your lead/recipient model
EMAIL_MARKETING_LEAD_MODEL=App\Models\Lead

That's it! The package works out of the box with:

• Built-in Bootstrap 5 admin panel
• SMTP settings stored in database (configurable from admin panel)
• Default rate limiting (10 emails/hour)

Full Configuration

# Required: Your lead/recipient model
EMAIL_MARKETING_LEAD_MODEL=App\Models\Lead

# Optional: Database connection for leads (null = default)
EMAIL_MARKETING_LEAD_CONNECTION=null

# Optional: Model for logo images (must have: type, src columns)
EMAIL_MARKETING_IMAGES_MODEL=App\Models\Images

# Optional: Use your own layout (null = use package's built-in layout)
EMAIL_MARKETING_LAYOUT=admin.layout

# Optional: Admin panel route prefix
EMAIL_MARKETING_ROUTE_PREFIX=admin/email-marketing

# Optional: Rate limiting
EMAIL_MARKETING_RATE_LIMIT=10
EMAIL_MARKETING_BASE_DELAY=360
EMAIL_MARKETING_RANDOM_DELAY=120

Multi-tenancy (SaaS)

For SaaS applications with multiple tenants, configure a tenant resolver in config/email-marketing.php:

'tenant_resolver' => fn() => auth()->user()?->tenant_id,

Each tenant will have their own SMTP settings stored in the email_smtp_settings table.

Example with Spatie Laravel Multitenancy:

'tenant_resolver' => fn() => app('currentTenant')?->id,

Usage

Access Admin Panel

Navigate to /admin/email-marketing (or your configured prefix).

Available Routes

Template Variables

Templates support the following variables:

Running Queue Worker

For sending emails via queue:

php artisan queue:work

Or use Laravel Horizon for Redis queues:

php artisan horizon

Programmatic Usage

use Dinara\EmailMarketing\Models\EmailTemplate;
use Dinara\EmailMarketing\Models\EmailCampaign;
use Dinara\EmailMarketing\Services\EmailCampaignService;
use Dinara\EmailMarketing\Services\SmtpConfigService;

// Create a template
$template = EmailTemplate::create([
    'name' => 'Welcome Email',
    'subject' => 'Welcome {{contact_name}}!',
    'body_html' => '<h1>Hello {{contact_name}}</h1><p>Welcome to our service!</p>',
    'is_active' => true,
]);

// Create and start a campaign
$service = app(EmailCampaignService::class);
$campaign = $service->createCampaign(
    name: 'Welcome Campaign',
    templateId: $template->id,
    recipientIds: [1, 2, 3] // Lead IDs
);

$service->startCampaign($campaign);

// For SaaS: Set tenant before operations
$smtpService = app(SmtpConfigService::class);
$smtpService->setTenant($tenantId);
$settings = $smtpService->getSettings();

Database Tables

The package creates the following tables:

• email_templates - Email templates with HTML content
• email_campaigns - Campaign metadata and status
• email_sends - Individual email sends with tracking
• email_clicks - Click tracking data
• email_smtp_settings - SMTP settings (supports multi-tenancy)

Tracking

Open Tracking

Emails automatically include a 1x1 transparent tracking pixel. Opens are recorded with:

• Timestamp
• IP address
• User agent
• Open count

Click Tracking

All links in emails are automatically wrapped with tracking URLs. Clicks record:

• Original URL
• Timestamp
• IP address
• User agent

Bounce Detection

The package automatically detects bounced emails based on SMTP error codes (550, 551, 552, 553, 554) and common error messages. Bounced recipients are marked with email_invalid = true.

Customization

Custom Lead Model

Your lead model should have at least:

• id
• email
• company_name or name
• manager_name (optional, for contact person)

Custom Views

Publish and modify views:

php artisan vendor:publish --tag=email-marketing-views

Views will be copied to resources/views/vendor/email-marketing/.

Custom Layout

Set your admin layout in .env:

EMAIL_MARKETING_LAYOUT=admin.layout

Your layout should have a content section:

@yield('content')

Events

The package dispatches events you can listen to:

• EmailSent - When an email is successfully sent
• EmailOpened - When a tracking pixel is loaded
• EmailClicked - When a tracked link is clicked
• EmailBounced - When an email bounces

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please submit a Pull Request.

Support

For issues and feature requests, please use the GitHub issue tracker.