Sign In

Installation & Setup #

This guide will walk you through installing and configuring the Campaign plugin for October CMS.

📋 Requirements #

Before you begin, ensure your system meets these requirements:

System Requirements #

  • October CMS v3.x
  • PHP 8.0 or higher
  • Database MySQL 5.7+ or MariaDB 10.2+
  • Composer for dependency management
  • SSL certificate (required for production)
  • Cron job access for automation

Required Plugins #

  • Albrightlabs.SaasBase - For organization and user management

External Services (Optional) #

  • SMTP Server - For sending emails (can use multiple for failover)
  • Webhook Provider - SendGrid, Mailgun, Postmark, Amazon SES, or Brevo
  • Stripe Account - If using paid features through SaasBase

📦 Installation Steps #

1. Install the SaasBase Plugin First #

The Campaign plugin requires SaasBase for organization management:

cd plugins
git clone [repository-url] albrightlabs/saasbase
php artisan october:migrate

2. Install the Campaign Plugin #

cd plugins
git clone [repository-url] albrightlabs/campaign

3. Run Migrations #

Execute the database migrations to set up all required tables:

php artisan october:migrate

This will create:

  • Campaign management tables (campaign_messages, campaign_message_statuses)
  • Subscriber tables (campaign_subscribers, campaign_subscriber_lists)
  • SMTP configuration tables (smtp_servers, smtp_health_logs)
  • Webhook tables (campaign_webhook_endpoints, campaign_webhook_events)
  • API logging tables (api_request_logs)
  • Sender profiles table (sender_profiles)
  • Message scheduling table (campaign_message_schedules)

4. Configure Cron Job #

The Campaign plugin requires a cron job to process scheduled tasks:

* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1

This handles:

  • Sending scheduled campaigns
  • Processing message queues
  • SMTP health checks
  • Webhook deliveries

5. Set Up Permissions #

Ensure proper file permissions:

chmod -R 755 plugins/albrightlabs/campaign
chmod -R 775 plugins/albrightlabs/campaign/assets

6. Clear Caches #

php artisan cache:clear
php artisan config:clear
php artisan view:clear

⚙️ Initial Configuration #

1. Access the Backend #

  1. Log in to your October CMS backend
  2. You should see new menu items:
    • Dashboard - Campaign analytics
    • Messages - Campaign management
    • Lists - Subscriber lists
    • Subscribers - Contact management

2. Configure SMTP Settings #

Navigate to Settings → Email Settings:

  1. Click "Add SMTP Server"

  2. Enter your SMTP details:

    • Server Name: Friendly name (e.g., "Primary Mail Server")
    • Host: SMTP server address
    • Port: Usually 587 for TLS, 465 for SSL
    • Encryption: TLS or SSL
    • Username/Password: Your SMTP credentials
    • From Address: Default sender email
    • From Name: Default sender name

  3. Click "Test Connection" to verify settings

  4. Save the configuration

💡 Tip: You can add up to 3 SMTP servers for automatic failover protection.

3. Generate API Token (Optional) #

If you need API access:

  1. Go to Settings → API Settings
  2. Click "Generate New Token"
  3. Copy and securely store the token
  4. Set allowed IP addresses if needed

4. Configure Webhooks (Optional) #

For email event tracking:

  1. Navigate to Settings → Webhooks
  2. Click "Add Webhook"
  3. Configure your webhook endpoint
  4. Select events to track (sent, opened, clicked, etc.)

🔍 Verification #

Test Email Sending #

  1. Go to Messages → Create New Message
  2. Enter a test subject and content
  3. Click "Send Test Message"
  4. Enter your email address
  5. Verify you receive the test email

Check Dashboard #

Navigate to the Dashboard to verify:

  • Statistics are loading correctly
  • No error messages appear
  • Performance metrics display

Verify Cron Job #

Check that scheduled tasks are running:

php artisan schedule:list

You should see Campaign-related tasks listed.

🚨 Common Installation Issues #

Migration Errors #

If you encounter migration errors:

php artisan plugin:refresh Albrightlabs.Campaign

Permission Issues #

If you see permission errors:

sudo chown -R www-data:www-data storage
sudo chmod -R 775 storage

SMTP Connection Failed #

Common causes:

  • Firewall blocking SMTP ports
  • Incorrect credentials
  • SSL/TLS mismatch
  • IP not whitelisted on SMTP provider

Cron Not Running #

Verify cron is set up correctly:

crontab -l

Test manually:

php artisan campaign:run

📝 Environment Variables #

You can also configure settings via .env file:

# SMTP Settings
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your-username
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@example.com
MAIL_FROM_NAME="Your Company"

# Campaign Settings
CAMPAIGN_QUEUE_BATCH_SIZE=100
CAMPAIGN_RATE_LIMIT=1000
CAMPAIGN_RATE_LIMIT_PERIOD=3600

✅ Post-Installation Checklist #

  • [ ] SaasBase plugin installed and configured
  • [ ] Campaign plugin installed
  • [ ] Database migrations completed
  • [ ] Cron job configured
  • [ ] SMTP server(s) configured and tested
  • [ ] File permissions set correctly
  • [ ] Test email sent successfully
  • [ ] Dashboard loading properly
  • [ ] API token generated (if needed)
  • [ ] Webhooks configured (if needed)

🎯 Next Steps #

Now that installation is complete:

  1. Quick Start Guide - Send your first campaign
  2. Configuration - Fine-tune your settings
  3. Dashboard - Understanding your analytics

🆘 Need Help? #

If you encounter issues:

  1. Check the Troubleshooting Guide
  2. Review system logs in storage/logs
  3. Contact support at support@albrightlabs.com

Next: Quick Start Guide →