Mailcoach Cli Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer global require spatie/mailcoach-cli
   

   Ensure $HOME/.composer/vendor/bin is in your PATH or use ./vendor/bin/mailcoach if installed locally.

2. First Authentication:

   mailcoach login
   

   • Enter your Mailcoach instance URL (e.g., https://your-instance.mailcoach.app).
   • Generate an API token in Mailcoach under Account > API Tokens and paste it during login.
   • Credentials are stored securely in ~/.config/spatie/mailcoach-cli/config.json.

3. First Use Case: List all email lists to verify connectivity:

   mailcoach list-email-lists
   

   Output will show a JSON array of lists (e.g., {"data":[{"id":1,"name":"Newsletter"}]}).

Implementation Patterns

Workflows

1. Campaign Management:

   • Create a draft campaign:

     mailcoach create-campaign --name="Spring Sale" --subject="20% Off!"
     

   • Schedule a campaign (ISO 8601 format):

     mailcoach schedule-campaign --campaign-id=1 --scheduled-at="2026-05-15T10:00:00Z"
     

   • Send test emails:

     mailcoach send-test-email --campaign-id=1 --email="test@example.com"
     

2. Automation with Laravel:

   • Use the CLI in artisan commands (e.g., php artisan mailcoach:sync-campaigns).
   • Example: Sync Mailcoach subscribers with a Laravel database:

     // app/Console/Commands/SyncSubscribers.php
     public function handle() {
         $subscribers = shell_exec('mailcoach list-subscribers --email-list-id=1');
         // Parse JSON and update local DB...
     }
     

3. CI/CD Integration:

   • Cache API responses in CI (e.g., GitHub Actions) to avoid rate limits:

     # .github/workflows/deploy.yml
     steps:
       - run: mailcoach clear-cache && mailcoach list-campaigns
     

4. Agent-Assisted Workflows:

   • Use with skills.sh for AI-driven tasks (e.g., Claude Code):

     /mailcoach list-campaigns --status=scheduled
     

   • Automate in Laravel Boost:

     php artisan boost:run "mailcoach create-campaign --name='Weekly Digest'"
     

Integration Tips

• Laravel Service Provider: Bind the CLI to a service container for programmatic access:

  // app/Providers/AppServiceProvider.php
  public function register() {
      $this->app->singleton('mailcoach', function () {
          return new \Spatie\MailcoachCli\MailcoachCli();
      });
  }
  

  Use in controllers:

  $campaigns = $this->app['mailcoach']->run('list-campaigns');
  

• Environment Variables: Override credentials via .env:

  MAILCOACH_URL=https://your-instance.mailcoach.app
  MAILCOACH_TOKEN=your_api_token_here
  

  Then run:

  mailcoach --env=.env list-email-lists
  

• API Spec Updates: Refresh the cached OpenAPI spec manually:

  mailcoach clear-cache
  

  Or automate via a cron job:

  0 3 * * * mailcoach clear-cache >> /dev/null 2>&1
  

Gotchas and Tips

Pitfalls

1. Token Permissions:

   • Ensure the API token has read/write access for the endpoints you use. Test with list-* commands first.
   • Debug with:

     mailcoach --verbose list-email-lists
     

     Look for 403 Forbidden errors in the output.

2. Rate Limiting:

   • Mailcoach enforces rate limits. Cache responses in Laravel:

     $cacheKey = "mailcoach_campaigns_{$campaignId}";
     return Cache::remember($cacheKey, now()->addMinutes(5), function () use ($campaignId) {
         return shell_exec("mailcoach show-campaign --campaign-id={$campaignId}");
     });
     

3. ID Mismatches:

   • Always use --id flags (e.g., --campaign-id=1) instead of names or slugs, as these are immutable.

4. Local Development:

   • Use a .env file for local testing to avoid hardcoding credentials:

     mailcoach --env=.env.local list-campaigns
     

Debugging

• Verbose Mode:

  mailcoach --verbose create-campaign --name="Test"
  

  Reveals raw API requests/responses (e.g., headers, payloads).

• Dry Runs: Simulate API calls without executing:

  mailcoach --dry-run schedule-campaign --campaign-id=1
  

• Logging: Enable debug logging in ~/.config/spatie/mailcoach-cli/config.json:

  {
    "debug": true,
    "log_file": "/tmp/mailcoach-cli.log"
  }
  

Extension Points

1. Custom Commands: Extend the CLI by creating a plugin. Example:

   # Create a new command file
   mkdir -p ~/.config/spatie/mailcoach-cli/commands
   touch ~/.config/spatie/mailcoach-cli/commands/export-subscribers.php
   

   Add PHP code to define new commands (see Spatie CLI docs).

2. Webhook Triggers: Use the CLI in Laravel events (e.g., sent email events) to update Mailcoach:

   // app/Events/EmailSent.php
   public function handle() {
       shell_exec("mailcoach update-subscriber --email-list-id=1 --email={$this->email}");
   }
   

3. GitHub Actions: Automate deployments with Mailcoach:

   - name: Deploy Campaign
     run: |
       mailcoach create-campaign --name="${{ github.event.inputs.name }}"
       mailcoach schedule-campaign --campaign-id=$(mailcoach list-campaigns | jq -r '.data[-1].id') --scheduled-at="${{ github.event.inputs.date }}"
   

Config Quirks

• Cache Directory: The CLI caches API specs in ~/.cache/spatie/mailcoach-cli. Clear it if commands fail unexpectedly:

  rm -rf ~/.cache/spatie/mailcoach-cli
  

• URL Formatting: Ensure the instance URL ends with / (e.g., https://example.com/). Trailing slashes are required for API routes.

• Token Rotation: Rotate tokens via:

  mailcoach logout && mailcoach login
  

  The CLI does not support token refresh; manual re-authentication is required.