Mailcoach Ui Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Ensure spatie/laravel-mailcoach is installed first (core email marketing functionality).

   composer require spatie/laravel-mailcoach
   

   Then install the UI package:

   composer require spatie/mailcoach-ui
   

2. Publish Assets & Config Run the publisher for assets and configuration:

   php artisan vendor:publish --provider="Spatie\Mailcoach\MailcoachServiceProvider" --tag="mailcoach-assets"
   php artisan vendor:publish --provider="Spatie\Mailcoach\MailcoachServiceProvider" --tag="mailcoach-config"
   

   • Assets include Vue.js frontend (Sass/JS) and Tailwind CSS for styling.
   • Config defines routes, middleware, and UI settings (e.g., mailcoach.ui.enabled).

3. Run Migrations Mailcoach requires database tables for campaigns, subscribers, etc.:

   php artisan migrate
   

4. First Use Case: Launch the UI

   • Visit /mailcoach (or your configured route).
   • Authenticate via Laravel’s default auth (e.g., php artisan make:auth if not set up).
   • Default Credentials: Use the mailcoach user created during installation (check users table).

Implementation Patterns

Core Workflows

1. Campaign Management

   • Create/Edit Campaigns: Use the drag-and-drop email builder (WYSIWYG editor) to design templates.
     • Save as a draft or publish to send immediately/schedule.
     • Tip: Use the "Preview" button to test rendering across email clients.
   • Send Campaigns:
     • Trigger sends via the "Send Now" button or schedule for later.
     • Monitor open/click rates in real-time via the dashboard.

2. Subscriber Management

   • Import/Export Lists: Upload CSV files or sync with external APIs (e.g., via Laravel’s queue:work).
     • Pattern: Use Mailcoach::subscribers()->create() for programmatic additions.
   • Segmentation: Filter subscribers by tags (e.g., active, vip) or custom fields.
     • Example:

       $subscribers = Mailcoach::subscribers()
           ->where('tags', 'like', '%vip%')
           ->get();
       

3. Automation

   • Workflows: Design automated sequences (e.g., welcome emails) using the visual workflow builder.
     • Integration: Hook into Laravel events (e.g., user.registered) via:

       event(new Registered($user));
       // Trigger workflow via Mailcoach API:
       Mailcoach::workflows()->trigger('welcome_sequence', $user->email);
       

4. Analytics

   • Dashboard: Track delivery rates, bounce rates, and unsubscribes per campaign.
     • Export Data: Use the "Export" button to generate CSV reports.
   • Programmatic Access:

     $stats = Mailcoach::campaigns()->find(1)->stats();
     

Integration Tips

• Laravel Events: Tie Mailcoach to Laravel’s ecosystem by listening to events:

  // Example: Send a welcome email when a user registers
  Event::listen(Registered::class, function ($user) {
      Mailcoach::campaigns()->find(1)->sendTo($user->email);
  });
  

• API Access: Use the underlying API for custom logic:

  // Send a campaign via API
  $response = Http::post('/api/mailcoach/campaigns/1/send');
  

• Custom Fields: Extend subscriber data with custom fields (e.g., company_name):

  // Add a custom field to a subscriber
  $subscriber = Mailcoach::subscribers()->create([
      'email' => 'user@example.com',
      'custom_fields' => ['company_name' => 'Acme Corp'],
  ]);
  

• Theming: Override default UI assets by publishing and modifying:

  php artisan vendor:publish --tag=mailcoach-assets --force
  

  • Edit /resources/views/vendor/mailcoach/ for Blade templates.
  • Override /resources/js/mailcoach/ for Vue components.

Gotchas and Tips

Pitfalls

1. Asset Loading Issues

   • Problem: UI assets (CSS/JS) fail to load after publishing.
   • Fix: Ensure public_path() is correct in config/mailcoach.php and run:

     npm run dev  # or `npm run prod` for production
     php artisan optimize:clear
     

2. Authentication Bypass

   • Problem: /mailcoach routes are accessible without auth.
   • Fix: Register middleware in config/mailcoach.php:

     'middleware' => ['auth'],
     

3. Queue Workers Required

   • Problem: Emails don’t send or stats don’t update.
   • Fix: Run queue workers:

     php artisan queue:work
     

   • Tip: Use SUPERVISOR or FORK for production.

4. Database Conflicts

   • Problem: Migrations fail due to existing mailcoach_* tables.
   • Fix: Reset the database or manually drop tables before migrating.

5. Vue.js Dependencies

   • Problem: UI breaks due to missing Node modules.
   • Fix: Install dependencies:

     npm install
     

Debugging Tips

• Log Campaign Sends: Enable logging in config/mailcoach.php:

  'log' => [
      'enabled' => true,
      'channel' => 'single',
  ],
  

  Check logs at storage/logs/laravel.log.

• Test Emails Locally: Use Laravel’s Mail::fake() to verify emails:

  Mail::fake();
  Mailcoach::campaigns()->find(1)->sendTo('test@example.com');
  Mail::assertSent(MailcoachMail::class);
  

• Clear Caches: After config changes, run:

  php artisan config:clear
  php artisan view:clear
  

Extension Points

1. Custom UI Components

   • Extend the Vue.js frontend by adding components to /resources/js/mailcoach/components.
   • Example: Add a custom modal for subscriber management.

2. API Endpoints

   • Extend the API by publishing routes:

     php artisan vendor:publish --tag=mailcoach-routes
     

   • Add custom routes in routes/mailcoach.php.

3. Event Listeners

   • Listen to Mailcoach events (e.g., CampaignSent):

     Mailcoach::campaigns()->on('sent', function ($campaign) {
         // Custom logic (e.g., update analytics)
     });
     

4. Custom Storage

   • Override storage paths (e.g., for attachments) in config/mailcoach.php:

     'storage' => [
         'attachments' => storage_path('app/mailcoach/attachments'),
     ],
     

5. Localization

   • Translate UI strings by publishing language files:

     php artisan vendor:publish --tag=mailcoach-translations
     

   • Edit /resources/lang/vendor/mailcoach/ for custom translations.