Sign In

Configuration Guide #

This comprehensive guide covers all configuration options for the Message plugin.

📧 Email Settings #

Access email settings via Settings → Email Settings in the backend.

Sender Profiles #

Configure sender identities for your campaigns:

// config/campaign.php
return [
    'sender_profiles' => [
        'require_profile' => true,         // Require profile selection
        'allow_custom_reply_to' => true,   // Allow custom reply-to addresses
        'verify_domains' => true,          // Verify sender domains
        'default_profile_id' => null       // Default profile ID
    ]
];

Sender Profile Settings:

  1. Navigate to Settings → Sender Profiles
  2. Click "Create Sender Profile"
  3. Configure:
    • Profile Name: Internal reference (e.g., "Marketing Team")
    • From Name: Display name (e.g., "Acme Marketing")
    • From Email: Sender email address
    • Reply-To Email: Optional custom reply address
    • Set as Default: Make this the default profile

💡 Tip: Create different sender profiles for different campaign types (newsletters, promotions, transactional).

SMTP Configuration #

The Message plugin supports up to 3 SMTP servers with automatic failover.

Primary SMTP Server #

Your main email sending server:

Server Name: Primary Mail Server
Host: smtp.sendgrid.net
Port: 587
Encryption: TLS
Username: apikey
Password: your-sendgrid-api-key
From Address: noreply@yourdomain.com
From Name: Your Company Name

Backup SMTP Servers #

Configure additional servers for failover protection:

  • Priority 2: Secondary server (used if primary fails)
  • Priority 3: Tertiary server (last resort)

Common SMTP Configurations #

SendGrid #
Host: smtp.sendgrid.net
Port: 587
Encryption: TLS
Username: apikey
Password: [Your API Key]
Mailgun #
Host: smtp.mailgun.org
Port: 587
Encryption: TLS
Username: [Your Username]
Password: [Your Password]
Amazon SES #
Host: email-smtp.[region].amazonaws.com
Port: 587
Encryption: TLS
Username: [Your Access Key]
Password: [Your Secret Key]
Gmail/Google Workspace #
Host: smtp.gmail.com
Port: 587
Encryption: TLS
Username: your-email@gmail.com
Password: [App-Specific Password]
Outlook/Office 365 #
Host: smtp.office365.com
Port: 587
Encryption: STARTTLS
Username: your-email@outlook.com
Password: [Your Password]

SMTP Failover Settings #

Configure how the system handles SMTP failures:

// config/campaign.php
return [
    'smtp' => [
        'max_failures' => 3,           // Failures before switching
        'retry_after' => 30,            // Minutes before retry
        'health_check_interval' => 5,   // Minutes between checks
        'circuit_breaker_timeout' => 30 // Minutes for circuit reset
    ]
];

🔌 Webhook Configuration #

Set up webhooks to track email events in real-time.

Adding a Webhook #

  1. Navigate to Settings → Webhooks
  2. Click "Add Webhook"
  3. Configure settings:
Name: SendGrid Events
URL: https://your-domain.com/api/campaign/webhook
Secret: generate-secure-secret
Events: 
  - sent
  - opened
  - clicked
  - unsubscribed
  - bounced
  - complained
Provider: SendGrid

Provider-Specific Setup #

SendGrid #

  1. Log into SendGrid Dashboard
  2. Go to Settings → Mail Settings → Event Webhook
  3. Enter your webhook URL
  4. Select events to track
  5. Enable webhook

Mailgun #

  1. Access Mailgun Control Panel
  2. Navigate to Webhooks
  3. Add webhook URL for each event type
  4. Configure signing key

Amazon SES #

  1. Set up SNS topic
  2. Subscribe webhook endpoint
  3. Configure event publishing

Webhook Security #

Always use webhook secrets for verification:

// Webhook will verify signature
$signature = hash_hmac('sha256', $payload, $secret);

🔑 API Configuration #

Enable API access for external integrations.

Generating API Tokens #

  1. Go to Settings → API Settings
  2. Click "Generate New Token"
  3. Configure:
    • Token Name: "Mobile App Integration"
    • Allowed IPs: Leave blank for any IP, or specify IPs
    • Rate Limit: 1000 requests per hour
    • Permissions: Select allowed operations

API Settings #

// config/campaign.php
return [
    'api' => [
        'enabled' => true,
        'rate_limit' => 1000,
        'rate_limit_period' => 3600, // seconds
        'token_length' => 64,
        'log_requests' => true,
        'allowed_origins' => [
            'https://app.yourdomain.com',
            'https://mobile.yourdomain.com'
        ]
    ]
];

Using API Tokens #

Include token in request headers:

curl -H "Authorization: Bearer your-api-token" \
     -H "Content-Type: application/json" \
     https://your-domain.com/api/campaign/subscribers

⏰ Sending Configuration #

Control how and when emails are sent.

Message Scheduling #

Configure recurring message schedules:

// config/campaign.php
return [
    'scheduling' => [
        'enabled' => true,
        'default_timezone' => 'America/New_York',
        'default_send_time' => '09:00',
        'allow_yearly' => true,
        'max_runs_limit' => 1000,          // Maximum runs for recurring
        'cleanup_old_schedules' => true,   // Archive inactive schedules
        'cleanup_after_days' => 365        // Days before cleanup
    ]
];

Available Options:

  • enabled: Enable/disable scheduling system
  • default_timezone: Default timezone for schedules
  • default_send_time: Default time for scheduled sends (HH:MM)
  • allow_yearly: Allow yearly frequency option
  • max_runs_limit: Maximum sends for recurring campaigns
  • cleanup_old_schedules: Auto-archive completed schedules
  • cleanup_after_days: Days before archiving inactive schedules

Sending Windows #

Define when emails can be sent:

// config/campaign.php
return [
    'sending' => [
        'window_enabled' => true,
        'window_start' => '09:00',    // 9 AM
        'window_end' => '17:00',      // 5 PM
        'window_timezone' => 'America/New_York',
        'window_days' => ['mon', 'tue', 'wed', 'thu', 'fri'],
        'skip_weekends' => true
    ]
];

Rate Limiting #

Prevent overwhelming mail servers:

return [
    'sending' => [
        'rate_limit' => 500,           // emails per period
        'rate_limit_period' => 3600,   // seconds (1 hour)
        'batch_size' => 100,           // emails per batch
        'batch_delay' => 5             // seconds between batches
    ]
];

Queue Configuration #

Optimize queue processing:

return [
    'queue' => [
        'driver' => 'database',        // or 'redis', 'sqs'
        'connection' => 'default',
        'queue_name' => 'campaigns',
        'retry_after' => 90,           // seconds
        'max_attempts' => 3
    ]
];

📊 Tracking Configuration #

Configure email open and click tracking.

Open Tracking #

return [
    'tracking' => [
        'track_opens' => true,
        'track_clicks' => true,
        'track_unsubscribes' => true,
        'anonymize_ip' => false,       // GDPR compliance
        'tracking_domain' => 'track.yourdomain.com'
    ]
];

UTM Parameters #

Add UTM tags to links automatically:

return [
    'tracking' => [
        'utm_source' => 'newsletter',
        'utm_medium' => 'email',
        'utm_campaign' => '{campaign_code}',
        'append_utm' => true
    ]
];

🎨 Template Configuration #

Customize email templates and editor settings.

Editor Configuration #

return [
    'editor' => [
        'default_editor' => 'richeditor', // or 'markdown', 'plain'
        'allow_html' => true,
        'sanitize_html' => true,
        'allowed_tags' => [
            'p', 'br', 'strong', 'em', 'u', 
            'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
            'ul', 'ol', 'li', 'a', 'img', 
            'table', 'tr', 'td', 'th'
        ]
    ]
];

Default Template Settings #

return [
    'templates' => [
        'default_template' => 'default',
        'css_framework' => 'foundation', // or 'bootstrap'
        'inline_css' => true,
        'minify_html' => true,
        'image_hosting' => 'local'      // or 's3', 'cloudinary'
    ]
];

🔒 Security Configuration #

Spam Prevention #

return [
    'security' => [
        'enable_captcha' => true,
        'captcha_provider' => 'recaptcha', // or 'hcaptcha'
        'double_opt_in' => true,
        'confirm_expiry' => 72,            // hours
        'rate_limit_signups' => 10,        // per IP per hour
        'block_disposable_emails' => true
    ]
];

Email Validation #

Configure subscriber email validation:

return [
    'validation' => [
        'enabled' => true,
        'check_syntax' => true,
        'check_disposable' => true,         // Block disposable emails
        'check_mx_records' => false,        // Verify MX records (slower)
        'check_smtp' => false,              // SMTP verification (slowest)
        'block_role_emails' => false,       // Block admin@, noreply@, etc.
        'allow_subaddress' => true,         // Allow plus addressing (user+tag@)
        'log_validation' => true,           // Track validation statistics
        'disposable_domains_update' => 30   // Days between list updates
    ]
];

Validation Levels:

  • Syntax Only: Fast, checks format only
  • + Disposable Check: Blocks temporary email services
  • + MX Records: Verifies domain has mail servers
  • + SMTP Verification: Confirms mailbox exists (very slow)

Compliance Settings #

return [
    'compliance' => [
        'require_consent' => true,
        'show_privacy_policy' => true,
        'privacy_policy_url' => '/privacy',
        'gdpr_compliant' => true,
        'can_spam_compliant' => true,
        'include_physical_address' => true,
        'unsubscribe_method' => 'one_click' // or 'confirmation'
    ]
];

🌍 Localization #

Configure language and timezone settings:

return [
    'localization' => [
        'default_language' => 'en',
        'available_languages' => ['en', 'es', 'fr', 'de'],
        'default_timezone' => 'UTC',
        'subscriber_timezone' => true,     // Track subscriber timezones
        'date_format' => 'M j, Y',
        'time_format' => 'g:i A'
    ]
];

📁 Storage Configuration #

Attachment Settings #

return [
    'storage' => [
        'disk' => 'local',                 // or 's3', 'gcs'
        'attachment_path' => 'campaigns/attachments',
        'max_attachment_size' => 10485760, // 10MB in bytes
        'allowed_extensions' => [
            'pdf', 'doc', 'docx', 'xls', 
            'xlsx', 'png', 'jpg', 'jpeg'
        ]
    ]
];

Archive Settings #

return [
    'archive' => [
        'auto_archive' => true,
        'archive_after_days' => 365,
        'delete_archived_after_days' => 730,
        'archive_storage' => 's3'          // Long-term storage
    ]
];

🔧 Advanced Configuration #

Database Settings #

return [
    'database' => [
        'connection' => 'mysql',
        'prefix' => 'campaign_',
        'strict_mode' => true,
        'log_queries' => false             // Enable for debugging
    ]
];

Cache Configuration #

return [
    'cache' => [
        'driver' => 'redis',               // or 'memcached', 'file'
        'ttl' => 3600,                     // seconds
        'cache_templates' => true,
        'cache_analytics' => true,
        'cache_subscriber_counts' => true
    ]
];

Performance Tuning #

return [
    'performance' => [
        'chunk_size' => 1000,              // Process subscribers in chunks
        'memory_limit' => '256M',
        'max_execution_time' => 300,       // seconds
        'optimize_images' => true,
        'lazy_load_images' => true
    ]
];

📝 Environment Variables #

Configure via .env file for easy deployment:

# Mail Settings
CAMPAIGN_MAIL_DRIVER=smtp
CAMPAIGN_MAIL_HOST=smtp.sendgrid.net
CAMPAIGN_MAIL_PORT=587
CAMPAIGN_MAIL_USERNAME=apikey
CAMPAIGN_MAIL_PASSWORD=your-api-key
CAMPAIGN_MAIL_ENCRYPTION=tls

# API Settings
CAMPAIGN_API_ENABLED=true
CAMPAIGN_API_RATE_LIMIT=1000

# Queue Settings
CAMPAIGN_QUEUE_DRIVER=database
CAMPAIGN_QUEUE_BATCH_SIZE=100

# Tracking
CAMPAIGN_TRACK_OPENS=true
CAMPAIGN_TRACK_CLICKS=true

# Security
CAMPAIGN_DOUBLE_OPT_IN=true
CAMPAIGN_GDPR_COMPLIANT=true

🔄 Applying Configuration Changes #

After making configuration changes:

  1. Clear configuration cache:

    php artisan config:clear
php artisan cache:clear

  2. Restart queue workers:

    php artisan queue:restart

  3. Test configuration:

    php artisan campaign:test-config

🎯 Configuration Best Practices #

  1. Start Conservative: Begin with lower rate limits and increase gradually
  2. Monitor Performance: Watch queue processing and adjust batch sizes
  3. Use Environment Variables: Keep sensitive data out of code
  4. Enable Logging: During initial setup for troubleshooting
  5. Test Failover: Regularly test SMTP failover functionality
  6. Regular Backups: Back up configuration before major changes

🆘 Troubleshooting Configuration #

SMTP Issues #

  • Verify credentials with provider
  • Check firewall rules for SMTP ports
  • Test with telnet: telnet smtp.host.com 587

API Not Working #

  • Verify token is active
  • Check IP restrictions
  • Review API logs in backend

Webhooks Not Receiving #

  • Verify webhook URL is publicly accessible
  • Check webhook secret matches
  • Review webhook delivery logs

Next: Dashboard Guide →