Mailcoach

https://www.mailcoach.app/self-hosted/documentation/v10
Admin
Mailcoach is a self-hosted and hosted email marketing platform that integrates with Amazon SES,...
Tokens:25,052
Snippets:370
Trust Score:9.8
Update:2 months ago
Show doc for...
Tokens:
Raw
### Serve the application

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/as-a-standalone-app

Starts the local development server for the Mailcoach application.

```bash
php artisan serve
```

--------------------------------

### Install Doctrine DBAL

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Ensure doctrine/dbal is installed to allow rename migrations to function correctly.

```bash
composer require doctrine/dbal
```

--------------------------------

### Create a New Automation

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Create a new automation with a name, target email list, and a trigger. This example uses a 'SubscribedTrigger' and a 'SendAutomationMailAction', with an optional 'runEvery' interval. The automation starts immediately after creation.

```php
Automation::create()
    ->name('Welcome email')
    ->to($emailList)
    ->runEvery(CarbonInterval::minute())
    ->triggerOn(new SubscribedTrigger)
    ->chain([
        new SendAutomationMailAction($automationMail),
    ])
    ->start();
```

--------------------------------

### Install Laravel MCP

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/mcp-server

Install the required Laravel MCP package via Composer.

```bash
composer require laravel/mcp
```

--------------------------------

### Define custom action with configuration fields

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Example of a custom action class implementing component registration, factory creation, and data serialization for UI configuration.

```php
class WaitAction extends AutomationAction
{
    public CarbonInterval $interval;

    public function __construct(CarbonInterval $interval)
    {
        parent::__construct();

        $this->interval = $interval;
    }

    public static function getComponent(): ?string
    {
        return 'wait-action';
    }

    public static function make(array $data): self
    {
        return new self(CarbonInterval::createFromDateString("{$data['length']} {$data['unit']}"));
    }

    public function toArray(): array
    {
        [$length, $unit] = explode(' ', $this->interval->forHumans());

        return [
            'length' => $length,
            'unit' => Str::plural($unit),
        ];
    }
}
```

--------------------------------

### Implement WebviewAutomationMailReplacer for Custom Email Placeholders

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

This example demonstrates creating a custom placeholder for Mailcoach automation emails by implementing the `AutomationMailReplacer` interface. It replaces `::webviewUrl::` with the email's webview URL. Remember to register this replacer in your `mailcoach.php` configuration file.

```php
namespace Spatie\Mailcoach\Domain\Automation\Support\Replacers;

use Spatie\Mailcoach\Domain\Automation\Models\AutomationMail;

class WebviewAutomationMailReplacer implements AutomationMailReplacer
{
    public function helpText(): array
    {
        return [
            'webviewUrl' => __mc('This URL will display the HTML of the automation email'),
        ];
    }

    public function replace(string $text, AutomationMail $automationMail): string
    {
        $webviewUrl = $automationMail->webviewUrl();

        return str_ireplace('::webviewUrl::', $webviewUrl, $text);
    }
}

```

--------------------------------

### Install Mailcoach via Composer

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Require the Mailcoach package in your Laravel project using Composer.

```bash
composer require "spatie/laravel-mailcoach:^10.0"
```

--------------------------------

### Implement Event-Based Trigger in Mailcoach

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

This example shows how to create an event-based trigger that listens for a `SubscribedEvent` and runs the automation for the subscriber. Ensure the trigger class implements `TriggeredByEvents` and the `subscribe` method.

```php
use Spatie\Mailcoach\Domain\Audience\Events\SubscribedEvent;

class SubscribedTrigger extends AutomationTrigger implements TriggeredByEvents
{
    public static function getName(): string
    {
        return (string) __mc('When a user subscribes');
    }

    public function subscribe($events): void
    {
        $events->listen(
            SubscribedEvent::class,
            function ($event) {
                $this->runAutomation($event->subscriber);
            }
        );
    }
}
```

--------------------------------

### Implement Scheduled Trigger in Mailcoach

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

This example demonstrates a scheduled trigger that checks the current time against a set date and runs the automation for new subscribers. It requires implementing the `TriggeredBySchedule` interface and the `trigger` method.

```php
use Spatie\Mailcoach\Domain\Automation\Models\Automation;

public function trigger(Automation $automation): void
{
    if (! now()->startOfMinute()->equalTo($this->date->startOfMinute())) {
        return;
    }

    $this->runAutomation($automation->newSubscribersQuery());
}
```

--------------------------------

### Get Campaign Name from CampaignOpenedEvent

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Identify the name of the campaign that was opened by a subscriber. This is useful for analyzing engagement with specific campaigns.

```php
$name = $event->campaignOpen->campaign->name;
```

--------------------------------

### Implement HasTagCondition for Custom Subscriber Tag Check

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

This example shows how to create a custom condition for Mailcoach automations by implementing the `Condition` interface. It checks if a subscriber has a specific tag. Ensure the `tag` is provided in the data array.

```php
namespace Spatie\Mailcoach\Domain\Automation\Support\Conditions;

use Spatie\Mailcoach\Domain\Audience\Models\Subscriber;
use Spatie\Mailcoach\Domain\Automation\Models\Automation;

class HasTagCondition implements Condition
{
    public function __construct(
        private Automation $automation,
        private Subscriber $subscriber,
        private array $data,
    ) {
    }

    public static function getName(): string
    {
        return (string) __mc('Has tag');
    }

    public static function getDescription(array $data): string
    {
        return (string) __mc(':tag', ['tag' => $data['tag']]);
    }

    public static function rules(): array
    {
        return [
            'tag' => 'required',
        ];
    }

    public function check(): bool
    {
        return $this->subscriber->hasTag($this->data['tag']);
    }
}

```

--------------------------------

### Prepare Database with Migrations

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Run the database migrations to set up the tables required by Mailcoach.

```bash
php artisan migrate
```

--------------------------------

### Create a new Mailcoach project

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/as-a-standalone-app

Initializes a new Laravel application with Mailcoach preinstalled. Requires your spatie.be account email and Mailcoach license key for authentication.

```bash
composer create-project spatie/Mailcoach
```

--------------------------------

### Create an Email List

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/audience

Initialize a new email list by creating an instance of the EmailList model.

```php
$emailList = EmailList::create(['name' => 'my email list name']);
```

--------------------------------

### Publish Configuration Files

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Run the artisan command to publish updated configuration files.

```bash
php artisan vendor:publish --tag=mailcoach-config --force
```

--------------------------------

### Enable MCP Server

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/mcp-server

Enable the MCP server and write tools using environment variables.

```bash
MAILCOACH_MCP_ENABLED=true
```

```bash
MAILCOACH_MCP_WRITE_TOOLS_ENABLED=true
```

--------------------------------

### Storing Transport Message ID

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Example listener to store a transport message ID on a Send model after an email is sent.

```php
class StoreTransportMessageId
{
    public function handle(MessageSent $event)
    {
        if (! isset($event->data['send'])) {
            return;
        }

        /** @var \\Spatie\\Mailcoach\\Models\\Send $send */
        $send = $event->data['send'];

        $transportMessageId = $event->message->getHeaders()->get('header-name-used-by-your-email-provider')->bodyAsString();

        $send->storeTransportMessageId($transportMessageId);
    }
}
```

--------------------------------

### Get Campaign Name from CampaignMailSentEvent

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Retrieve the name of the campaign associated with a sent email. This allows you to identify which campaign the email belongs to.

```php
$campaignName = $event->send->campaign->name;
```

--------------------------------

### Create the initial user

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/as-a-standalone-app

Generates the first administrative user account for accessing the Mailcoach dashboard.

```bash
php artisan mailcoach:make-user
```

--------------------------------

### Get Email List Name from UnsubscribedEvent

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Determine the name of the email list from which a subscriber unsubscribed. This provides context for the unsubscribe action.

```php
$nameOfEmailList = $event->send->campaign->emailList->name;
```

--------------------------------

### Publish Mailcoach Migrations

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Publish and run the migrations to create the necessary database tables for Mailcoach.

```bash
php artisan vendor:publish --tag=mailcoach-migrations
php artisan migrate
```

--------------------------------

### Get Subscriber Email from SubscribedEvent

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Access the email address of a subscriber when the SubscribedEvent is fired. This event is triggered upon successful subscription confirmation.

```php
$email = $event->subscriber->email;
```

--------------------------------

### Get Email Address of Link Clicker

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Retrieve the email address of the subscriber who clicked a link in an email. This helps in understanding user behavior and engagement.

```php
$email = $event->campaignClick->subscriber->email;
```

--------------------------------

### Get Opened Email Address from CampaignOpenedEvent

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Retrieve the email address of the subscriber who opened an email. This event is triggered for campaigns with open tracking enabled.

```php
$email = $event->campaignOpen->subscriber->email;
```

--------------------------------

### Configure Composer Authentication

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Create an auth.json file with your spatie.be account email and license key for private package authentication.

```json
{
    "http-basic": {
        "satis.spatie.be": {
            "username": "<YOUR-SPATIE.BE-ACCOUNT-EMAIL-ADDRESS-HERE>",
            "password": "<YOUR-LICENSE-KEY-HERE>"
        }
    }
}
```

--------------------------------

### Determine Composer Home Directory

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Find the composer home directory on *nix systems to correctly place the auth.json file.

```bash
composer config --list --global | grep home
```

--------------------------------

### Get Email List Name from SubscribedEvent

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Retrieve the name of the email list associated with a subscriber when the SubscribedEvent occurs. This helps in identifying the context of the subscription.

```php
$nameOfEmailList = $event->subscriber->emailList->name;
```

--------------------------------

### Get Clicked Link URL from CampaignLinkClickedEvent

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Extract the original URL of a link that was clicked within an email. This event is fired for campaigns with click tracking enabled.

```php
$url = $event->campaignClick->link->original_link;
```

--------------------------------

### Create a campaign

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Create a new campaign by chaining methods or by passing an array of attributes to the create method.

```php
$campaign = Campaign::create()
    ->from('sender@example.com')
    ->to($emailList);

$campaign->name = 'My newsletter #1';
$campaign->save();

$campaign->contentItem->subject = 'Newsletter #1';
$campaign->contentItem->html = $html;
$campaign->contentItem->save();
```

```php
Campaign::create([
   'name' => 'My newsletter #1',
   'email_list_id' => $emailList->id,
]);
```

--------------------------------

### Get Sent Email Address from CampaignMailSentEvent

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Access the email address of the recipient when an individual email within a campaign has been sent. This event fires for each successfully sent email.

```php
$email = $event->send->subscription->subscriber->email;
```

--------------------------------

### Implement a PersonalizedReplacer

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Create a class implementing PersonalizedReplacer to execute logic for each individual email sent in a campaign.

```php
namespace Spatie	ests

use Spatie	ests
use Spatie	ests

class UnsubscribeUrlReplacer implements PersonalizedReplacer
{
    public function helpText(): array
    {
        return [
            'unsubscribeUrl' => 'The url where users can unsubscribe',
        ];
    }

    public function replace(string $html, Send $pendingSend): string
    {
        $unsubscribeUrl = $pendingSend->subscriber->unsubscribeUrl($pendingSend);

        return str_ireplace('::unsubscribeUrl::', $unsubscribeUrl, $html);
    }
}
```

--------------------------------

### Publish All Mailcoach Assets

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Publish all assets, including migrations and other necessary files, for Mailcoach.

```bash
php artisan mailcoach:publish
```

--------------------------------

### Publish Mailcoach Views

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Run this artisan command to export Mailcoach views for customization, including the webview template.

```bash
php artisan vendor:publish --provider="Spatie\Mailcoach\MailcoachServiceProvider" --tag="mailcoach-views"
```

--------------------------------

### Get Subscriber Email Who Opened Automation Email

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Retrieve the email address of the subscriber who first opened a specific automation email using the 'opens' relation. Ensure the 'email-campaigns:calculate-statistics' job has run to populate these attributes.

```php
$open = $automationMail->opens->first();
$email = $open->subscriber->email;
```

--------------------------------

### Publish Mailcoach Config File

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Optionally, publish the Mailcoach configuration file to customize its settings.

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

--------------------------------

### Configure Laravel Horizon for Mailcoach

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Add `mailcoach-general` and `mailcoach-heavy` configurations to your `config/horizon.php` for both production and local environments. Ensure your `QUEUE_CONNECTION` in `.env` is set to `redis`.

```php
'environments' => [
    'production' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default'],
            'balance' => 'simple',
            'processes' => 10,
            'tries' => 2,
            'timeout' => 60 * 60,
        ],
        'mailcoach-general' => [
            'connection' => 'mailcoach-redis',
            'queue' => ['mailcoach-schedule', 'mailcoach', 'mailcoach-feedback', 'send-mail', 'send-automation-mail'],
            'balance' => 'auto',
            'processes' => 10,
            'tries' => 2,
            'timeout' => 60 * 60,
        ],
        'mailcoach-heavy' => [
            'connection' => 'mailcoach-redis',
            'queue' => ['send-campaign'],
            'balance' => 'auto',
            'processes' => 3,
            'tries' => 1,
            'timeout' => 60 * 60,
        ],
    ],

    'local' => [
        'supervisor-1' => [
            'connection' => 'redis',
            'queue' => ['default'],
            'balance' => 'simple',
            'processes' => 10,
            'tries' => 2,
            'timeout' => 60 * 60,
        ],
        'mailcoach-general' => [
            'connection' => 'mailcoach-redis',
            'queue' => ['mailcoach-schedule', 'mailcoach', 'mailcoach-feedback', 'send-mail', 'send-automation-mail'],
            'balance' => 'auto',
            'processes' => 10,
            'tries' => 2,
            'timeout' => 60 * 60,
        ],
        'mailcoach-heavy' => [
            'connection' => 'mailcoach-redis',
            'queue' => ['send-campaign'],
            'balance' => 'auto',
            'processes' => 3,
            'tries' => 1,
            'timeout' => 60 * 60,
        ],
    ],
],

```

--------------------------------

### Get Subscriber Email Who Clicked Automation Email Link

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Retrieve the email address of the subscriber who first clicked a specific link within an automation email. This requires click tracking to be enabled and the 'email-campaigns:calculate-statistics' job to have processed the data.

```php
$automationMailLink = $automationMail->links->first();
$automationMailClick = $automationMailLink->links->first();
$email = $automationMailClick->subscriber->email;
```

--------------------------------

### Implement run method for custom actions

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

The run method executes once when a subscriber reaches the action. Use this to trigger specific logic like sending emails.

```php
public function run(Subscriber $subscriber): void
{
    $this->automationMail->send($subscriber);
}
```

--------------------------------

### Implement a custom campaign replacer

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Create a class implementing the Replacer interface to define custom placeholders for campaign content.

```php
namespace Spatie\Mailcoach\Support\Replacers;

use Spatie\Mailcoach\Domain\Campaign\Models\Campaign;
use Spatie\Mailcoach\Domain\Campaign\Support\Replacers\CampaignReplacer;

class WebviewReplacer implements CampaignReplacer
{
    public function helpText(): array
    {
        return [
            'webviewUrl' =>  'This url will display the html of the campaign',
        ];
    }

    public function replace(string $html, Campaign $campaign): string
    {
        $webviewUrl = $campaign->webviewUrl();

        return str_ireplace('::webviewUrl::', $webviewUrl, $html);
    }
}
```

--------------------------------

### Check Composer Authentication

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Verify that Composer can read your authentication credentials for the spatie.be repository.

```bash
composer config --list --global | grep satis.spatie.be
```

--------------------------------

### Implement a Custom Replacer Class

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/transactional-emails

Create a class implementing TransactionalMailReplacer to define help text and replacement logic for template placeholders.

```php
namespace App\Support\Replacers;

use Illuminate\Mail\Mailable;
use Spatie\Mailcoach\Domain\TransactionalMail\Models\TransactionalMail;
use Spatie\Mailcoach\Domain\TransactionalMail\Support\Replacers\TransactionalMailReplacer;

class SubjectReplacer implements TransactionalMailReplacer
{
    public function helpText(): array
    {
        return [
            'subject' => 'The subject used on the template',
        ];
    }

    public function replace(string $templateText, Mailable $mailable, TransactionalMail $template): string
    {
        return str_replace('::subject::', $mailable->subject, $templateText);
    }
}
```

--------------------------------

### Create Automation Email with Attributes

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Alternatively, create an automation email by passing an array of attributes directly to the `create` method. Ensure all required attributes like `from_email`, `subject`, and `content` are provided.

```php
AutomationMail::create([
   'from_email' => 'sender@example.com',
   'subject' => 'My newsletter #1',
   'content' => $html,
]);
```

--------------------------------

### Configure Unlayer Image Uploads

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/choosing-an-editor

Configure the disk name and maximum dimensions for image uploads in the Unlayer editor. Note that the package does not automatically delete old uploads.

```php
'unlayer' => [
    'disk_name' => env('MAILCOACH_UPLOAD_DISK', 'public'),
    'max_width' => 1500,
    'max_height' => 1500,
],
```

--------------------------------

### Publish Mailcoach Editor Configuration

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/choosing-an-editor

Publish the configuration file for the Editor.js package to customize settings like the upload disk name.

```bash
php artisan vendor:publish --provider="Spatie\MailcoachEditor\MailcoachEditorServiceProvider" --tag="mailcoach-editor-config"
```

--------------------------------

### Implement Editor Render Method

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

This method is required when creating a custom editor. It accepts a model with HTML content and should return the rendered HTML for the editor view. Ensure the returned HTML is valid.

```php
public function render(HasHtmlContent $model): string
{
    return view('mailcoach::app.campaigns.draft.textEditor', [
        'html' => $model->getHtml(),
    ])->render();
}

```

--------------------------------

### Run Database Migrations

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Apply the required schema changes to the transactional mail log and tags tables.

```php
return new class extends Migration
{
    public function up()
    {
        Schema::table('mailcoach_transactional_mail_log_items', function (Blueprint $table) {
            $table->string('mail_name')->nullable()->after('mailable_class');

            $table->index(['mail_name', 'created_at'], 'mail_name_index');
        });

        Schema::table('mailcoach_tags', function (Blueprint $table) {
            $table->text('description')->nullable()->after('name');
        });
    }
};
```

--------------------------------

### Configure sender details

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Set the sender name or reply-to address for a campaign.

```php
Campaign::create()->from('sender@example.com', 'Sender name')
```

```php
Campaign::create()->replyTo('john@example.com', 'John Doe')
```

--------------------------------

### Add Satis Repository to Composer

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Add the spatie satis repository to your composer.json file to access private packages.

```json
{
    "repositories": [
        {
            "type": "composer",
            "url": "https://satis.spatie.be"
        }
    ],

}
```

--------------------------------

### Update Horizon Configuration

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Add the mailcoach-schedule queue to your Horizon configuration to support the new schedule queue functionality.

```php
'mailcoach-general' => [
    'connection' => 'mailcoach-redis',
-     'queue' => ['general', 'mailcoach', 'mailcoach-feedback', 'send-mail', 'send-automation-mail'],
+     'queue' => ['general', 'mailcoach-schedule', 'mailcoach', 'mailcoach-feedback', 'send-mail', 'send-automation-mail'],
    'balance' => 'auto',
    'processes' => 10,
    'tries' => 2,
    'timeout' => 60 * 60,
],
```

--------------------------------

### Subscribe to a List

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/audience

Add a subscriber to an email list using either the list instance or the Subscriber model.

```php
$emailList->subscribe('john@example.com');
```

```php
Subscriber::createWithEmail('john@example.com')->subscribeTo($emailList);
```

--------------------------------

### Test a campaign

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Send a test email to one or more specific addresses before broadcasting to the full list.

```php
// to a single email address
$campaign->sendTestMail('john@example.com');

// to multiple email addresses at once
$campaign->sendTestMail(['john@example.com', 'paul@example.com'])
```

--------------------------------

### Publish Mailcoach Views

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Force publish the Mailcoach views to update them to the latest version.

```bash
php artisan vendor:publish --tag=mailcoach-views --force
```

--------------------------------

### Schedule Mailcoach Console Commands

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Schedule these commands in your `app/Console/Kernel.php` to ensure Mailcoach tasks run automatically. Be cautious when scheduling `mailcoach:cleanup-processed-feedback` as it may lead to duplicate feedback processing if historical data is removed.

```php
// in app/Console/Kernel.php
protected function schedule(Schedule $schedule)
{
    // ...
    $schedule->command('mailcoach:send-automation-mails')->everyMinute();
    $schedule->command('mailcoach:send-scheduled-campaigns')->everyMinute();
    $schedule->command('mailcoach:send-campaign-mails')->everyMinute();

    $schedule->command('mailcoach:run-automation-triggers')->everyMinute();
    $schedule->command('mailcoach:run-automation-actions')->everyMinute();

    $schedule->command('mailcoach:calculate-statistics')->everyMinute();
    $schedule->command('mailcoach:calculate-automation-mail-statistics')->everyMinute();
    $schedule->command('mailcoach:calculate-transactional-statistics')->everyMinute();
    $schedule->command('mailcoach:send-campaign-summary-mail')->hourly();
    $schedule->command('mailcoach:cleanup-processed-feedback')->hourly();
    $schedule->command('mailcoach:send-email-list-summary-mail')->mondays()->at('9:00');
    $schedule->command('mailcoach:delete-old-unconfirmed-subscribers')->daily();
  
    $schedule->command('mailcoach:prune')->dailyAt('3:00');
}

```

--------------------------------

### Clear view cache

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Command to clear the application view cache after upgrading.

```bash
php artisan view:clear
```

--------------------------------

### Create an Automation Email

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Use the `AutomationMail::create()` method to instantiate a new automation email. You can chain methods to set sender, subject, and content.

```php
AutomationMail::create()
    ->from('sender@example.com')
    ->subject('Welcome to Mailcoach')
    ->content($html);
```

--------------------------------

### Subscribe with Name Attributes

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/audience

Include first and last name details when subscribing a user.

```php
$subscriber = $emailList->subscribe('john@example.com', [
    'first_name' => 'John', 
    'last_name' => 'Doe'
]);
```

```php
Subscriber::createWithEmail('john@example.com')
   ->withAttributes([
       'first_name' => 'John', 
       'last_name' => 'Doe'
   ])
   ->subscribeTo($emailList);
```

--------------------------------

### Configure MCP Settings

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/mcp-server

Customize the MCP server behavior, including path, middleware, and token abilities, within the mailcoach.mcp config array.

```php
'mcp' => [
    'enabled' => env('MAILCOACH_MCP_ENABLED', false),
    'path' => 'mcp',
    'middleware' => [
        'auth:sanctum',
        'throttle:60,1',
    ],
    'write_tools_enabled' => env('MAILCOACH_MCP_WRITE_TOOLS_ENABLED', false),
    'read_token_ability' => 'mailcoach:mcp:read',
    'write_token_ability' => 'mailcoach:mcp:write',
],
```

--------------------------------

### Store Transactional Email using build()

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/transactional-emails

When using the `build` method in your Mailable, you can chain the `store()` method before specifying the view to log transactional emails.

```php
class YourMailable extends Mailable
{
    use StoresMail;

    public function build()
    {
        $this
            ->store()
            ->view('mails.your-mailable')
    }
}
```

--------------------------------

### Manage Campaign Webviews

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Retrieve webview URLs, publish views for customization, and hide specific HTML elements from the generated webview.

```php
$campaign->webViewUrl();
```

```bash
php artisan vendor:publish --provider="Spatie	ests" --tag="mailcoach-views"
```

```html
<html>
	<body>
		<!-- webview:hide -->
		<span>Is this email not displaying correctly? <a href="{{ webviewUrl }}">View online version</a></span>
		<!-- /webview:hide -->

		<div>
			... The rest of your email content
		</div>
		
		<!-- webview:hide -->
		<a href="{{ unsubscribeUrl }}">Unsubscribe</a>
		<!-- /webview:hide -->
	</body>
</html>
```

--------------------------------

### Update Mailcoach dependencies

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Run this command to update the Mailcoach package and its dependencies to the latest versions.

```bash
composer update spatie/laravel-mailcoach -W
```

--------------------------------

### Configure and embed subscription forms

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/audience

Enable form subscriptions on an email list and embed the HTML form on external sites.

```php
$emailList->update(['allow_form_subscriptions' => true]);
```

```html
<form method="POST" action="https://domain-where-mailcoach-runs/mailcoach/subscribe/<uuid-of-emaillist>">
    <div>
        <label for="email">Email</label>
        <input name="email">
    </div>
   <!-- optionally you can include the first_name and last_name field
    <div>
        <label for="first_name">First name</label>
        <input name="first_name">
    </div>
    <div>
        <label for="last_name">Last name</label>
        <input name="last_name">
    </div>
    -->
    <input type="hidden" name="redirect_after_subscribed" value="https://your-site/subscribed"  />
    <input type="hidden" name="redirect_after_already_subscribed" value="https://your-site/already-subscribed"  />
   <!-- only required if your list has double opt-in enabled
    <input type="hidden" name="redirect_after_subscription_pending" value="https://your-site/redirect-after-pending"  />
    -->
    <div>
       <button type="submit">Subscribe</button>    
    </div>
</form>
```

--------------------------------

### Implement a PersonalizedReplacer

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Create a class implementing PersonalizedReplacer to modify email content per subscriber. The replace method receives the Send object for subscriber access.

```php
namespace Spatie\Mailcoach\Domain\Automation\Support\Replacers;

use Spatie\Mailcoach\Domain\Shared\Models\Send;

class UnsubscribeUrlReplacer implements PersonalizedReplacer
{
    public function helpText(): array
    {
        return [
            'unsubscribeUrl' => __mc('The URL where users can unsubscribe'),
            'unsubscribeTag::your tag' => __mc('The URL where users can be removed from a specific tag'),
        ];
    }

    public function replace(string $text, Send $pendingSend): string
    {
        $unsubscribeUrl = $pendingSend->subscriber->unsubscribeUrl($pendingSend);

        $text = str_ireplace('::unsubscribeUrl::', $unsubscribeUrl, $text);

        preg_match_all('/::unsubscribeTag::(.*)::/', $text, $matches, PREG_SET_ORDER);

        foreach ($matches as $match) {
            [$key, $tag] = $match;

            $unsubscribeTagUrl = $pendingSend->subscriber->unsubscribeTagUrl($tag);

            $text = str_ireplace($key, $unsubscribeTagUrl, $text);
        }

        return $text;
    }
}
```

--------------------------------

### Clear Application Caches

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Clear the icon and view caches after upgrading to ensure changes are reflected.

```bash
php artisan icon:clear
php artisan view:clear
```

--------------------------------

### Configure Redis Rate Limiting

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/scaling-mailcoach

Enable atomic Redis-based rate limiting to prevent race conditions across multiple queue workers.

```env
MAILCOACH_RATE_LIMIT_REDIS=true
```

```php
'rate_limit_driver_is_redis' => env('MAILCOACH_RATE_LIMIT_REDIS', false),
```

--------------------------------

### Publish Mailcoach Views

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/audience

Use this command to publish Mailcoach's views, allowing customization of landing pages for unsubscribed users and other confirmation messages.

```bash
php artisan vendor:publish --provider="Spatie\Mailcoach\MailcoachServiceProvider" --tag="mailcoach-views"

```

--------------------------------

### Update custom Livewire routes

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Replace standard Route::get calls with Route::livewire for custom routes mounting Livewire components.

```php
- Route::get(‘/my-page’, MyLivewireComponent::class);
+ Route::livewire(‘/my-page’, MyLivewireComponent::class);
```

--------------------------------

### Update Configuration Editor Components

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Replace the deprecated TextAreaEditorComponent with the new Markdown and Codemirror editors in the configuration file.

```php
{-'content_editor' => \Spatie\Mailcoach\Livewire\Editor\TextAreaEditorComponent::class,-}
{+'content_editor' => \Spatie\Mailcoach\Domain\Editor\Markdown\Editor::class,+}

{-'template_editor' => \Spatie\Mailcoach\Livewire\Editor\TextAreaEditorComponent::class,-}
{+'template_editor' => \Spatie\Mailcoach\Domain\Editor\Codemirror\Editor::class,+}
```

--------------------------------

### Add Mailcoach Redis Queue Connection

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Define the `mailcoach-redis` connection in your `config/queue.php` file to enable Mailcoach to use Redis for its queueing needs.

```php
'connections' => [

    // ...

    'mailcoach-redis' => [
        'driver' => 'redis',
        'connection' => 'default',
        'queue' => env('REDIS_QUEUE', 'default'),
        'retry_after' => 11 * 60,
        'block_for' => null,
    ],


```

--------------------------------

### Update scheduled commands

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Configure the schedule in app/Console/Kernel.php with the updated Mailcoach command set.

```php
protected function schedule(Schedule $schedule)
{
    $schedule->command('mailcoach:send-automation-mails')->everyMinute();
    $schedule->command('mailcoach:send-scheduled-campaigns')->everyMinute();
    $schedule->command('mailcoach:send-campaign-mails')->everyMinute();

    $schedule->command('mailcoach:run-automation-triggers')->everyMinute();
    $schedule->command('mailcoach:run-automation-actions')->everyMinute();

    $schedule->command('mailcoach:calculate-statistics')->everyMinute();
    $schedule->command('mailcoach:calculate-automation-mail-statistics')->everyMinute();
    $schedule->command('mailcoach:send-campaign-summary-mail')->hourly();
    $schedule->command('mailcoach:cleanup-processed-feedback')->hourly();
    $schedule->command('mailcoach:send-email-list-summary-mail')->mondays()->at('9:00');
    $schedule->command('mailcoach:delete-old-unconfirmed-subscribers')->daily();
}
```

--------------------------------

### Update Auth Configuration

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Update the authentication model reference in your config/auth.php file.

```php
'users' => [
    'driver' => 'eloquent',
-     'model' => Spatie\MailcoachUi\Models\User::class,
+     'model' => \Spatie\Mailcoach\Domain\Settings\Models\User::class,
],
```

--------------------------------

### Run the Laravel scheduler

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/as-a-standalone-app

Ensures the Laravel scheduler is triggered every minute, which is required for Mailcoach background tasks.

```bash
php artisan schedule:run
```

--------------------------------

### Registering Feedback Listener

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Register the feedback listener in a service provider.

```php
Event::listen(Illuminate\\Mail\\Events\\MessageSent::class, StoreTransportMessageId::class);
```

--------------------------------

### Create Transactional Email Template

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/transactional-emails

Create a `TransactionalMailTemplate` model with a name, type (html, markdown, or blade), subject, and body. This allows non-technical users to define email content.

```php
Spatie\Mailcoach\Domain\TransactionalMail\Models\TransactionalMail::create([
    'name' => 'name-of-your-template',
    'type' => 'html', // this can be html, markdown or blade
    'subject' => 'The subject of your email',
    'body' => '<html>Content of your email</html>'
]);
```

--------------------------------

### Create and Use Segmenting Classes

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Implement custom segmenting logic by extending the Segment class, supporting both static and configurable segment objects.

```php
class OnlyEmailAddressesStartingWithA extends Segment
{
    public function shouldSend(Subscriber $subscriber): bool
    {
        return Str::startsWith($subscriber->email, 'a');
    }
}
```

```php
Campaign::create()
   ->content($yourHtml)
   ->segment(OnlyEmailAddressesStartingWithA::class)
   ->sendTo($emailList);
```

```php
class OnlyEmailAddressesStartingWith extends Segment
{
    public string $character;

    public function __construct(string $character) {
        $this->character = $character;
    }

    public function shouldSend(Subscriber $subscriber): bool
    {
        return Str::startsWith($subscriber->email, $this->character);
    }
}
```

```php
Campaign::create()
   ->content($yourHtml)
   ->segment(new OnlyEmailAddressesStartingWith('b'))
   ->sendTo($emailList);
```

--------------------------------

### Define and Use a Custom Mailable

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Extend CampaignMail to create custom mailables and assign them to campaigns.

```php
use Spatie	ests;

class MyCustomMailable extends CampaignMail
{
    public function build()
    {
        return $this->view('emails.your-custom-view');
    }
}
```

```php
Campaign::create()
    ->useMailable(MyCustomMailable::class)
    ->sendTo($emailList);
```

--------------------------------

### Implement shouldContinue method for flow control

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Controls whether a subscriber proceeds to the next action. Returns true by default.

```php
public function shouldContinue(Subscriber $subscriber): bool
{
    if ($subscriber->pivot->created_at <= now()->sub($this->interval)) {
        return true;
    }

    return false;
}
```

--------------------------------

### Subscribe without confirmation

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/audience

Bypass the double opt-in process to immediately confirm a subscriber.

```php
$emailList->subscribeskippingConfirmation('john@example.com');
```

```php
Subscriber::createWithEmail('john@example.com')
   ->skipConfirmation()
   ->subscribeTo($emailList);
```

--------------------------------

### Create a Configurable Segment

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Pass parameters to a segment class constructor to allow dynamic filtering. The object is serialized when saved to the automation.

```php
class OnlyEmailAddressesStartingWith extends Segment
{
    public string $character;

    public function __construct(string $character) {
        $this->character = $character;
    }

    public function shouldSend(Subscriber $subscriber): bool
    {
        return Str::startsWith($subscriber->email, $this->character);
    }
}
```

```php
Automation::create()
    ->segment(new OnlyEmailAddressesStartingWith('b'));
```

--------------------------------

### Register Mailcoach Route Macro

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Register the Mailcoach route macro in your `RouteServiceProvider`'s `boot` method to handle Mailcoach routes.

```php
Route::mailcoach('mailcoach');
```

--------------------------------

### Set Reply To for Automation Email

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Configure a reply-to address and name for your automation emails using the `replyTo` method.

```php
AutomationMail::create()->replyTo('john@example.com', 'John Doe')
```

--------------------------------

### Configure Data Pruning

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/scaling-mailcoach

Set the retention period in days for various Mailcoach data tables to manage database size.

```php
/**
 * Pruning settings determine after how many days the models should be pruned.
 * This will keep aggregated (calculated) statistics available, individual
 * subscriber rows will be deleted. Using null will disable pruning.
 * @since 8.13.0
 */
'prune_after_days' => [
    'sends' => null,
    'opens' => null,
    'clicks' => null,
    'unsubscribes' => null,
    'send_feedback_items' => null,
    'transactional_mail_log_items' => null,
],
```

--------------------------------

### Update RouteServiceProvider

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Replace the mailcoachUi route macro with the default Mailcoach route macro.

```php
public function boot()
{
    ...

-     Route::mailcoachUi('/');
+     Route::mailcoach('/');

    ...
}
```

--------------------------------

### Define a segment using a query

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/campaigns

Use the subscribersQuery method to filter subscribers for large lists. The package automatically ensures only subscribed users receive campaign emails.

```php
class OnlyEmailAddressesStartingWithA extends Segment
{
    public function subscribersQuery(Builder $subscribersQuery): void
    {
        $subscribersQuery->where('email','like', 'a%');
    }
}
```

--------------------------------

### Configure Editor.js

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/choosing-an-editor

Set the mailcoach.campaign.editor and mailcoach.automationMail.editor config values to use Editor.js. This is a block-based WYSIWYG editor that also supports image uploads.

```php
config(['mailcoach.campaign.editor' => 
    Spatie\\\MailcoachEditor\\Editor::class
]);
config(['mailcoach.automationMail.editor' => 
    Spatie\\\MailcoachEditor\\Editor::class
]);
```

--------------------------------

### Handling Feedback and Bounces

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/advanced-usage-for-php-devs

Retrieve a Send model by transport ID and mark it as bounced.

```php
$send = Send::findByTransportMessageId($messageId);
```

```php
$send->markAsBounced(SendBounceSeverity::PERMANENT);
```

--------------------------------

### Add Post-Update Command to Composer

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/in-an-existing-laravel-app

Ensure Mailcoach assets are republished on every Composer update by adding a post-update command.

```json
"scripts": {
    "post-update-cmd": [
        "@php artisan mailcoach:publish"
    ]
}
```

--------------------------------

### Run the queue worker

Source: https://www.mailcoach.app/self-hosted/documentation/v10/getting-started/installation/as-a-standalone-app

Executes the Mailcoach-specific queue worker. This replaces the standard Laravel queue:work command.

```bash
mailcoach:work
```

--------------------------------

### Set From Name for Automation Email

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

When creating an automation email, you can specify a 'from' name by passing it as the second argument to the `from` method.

```php
AutomationMail::create()->from('sender@example.com', 'Sender name')
```

--------------------------------

### Create Email List Requiring Confirmation

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/audience

Enable double opt-in for a new email list by setting the 'requires_confirmation' attribute to true during creation. This ensures subscribers actively confirm their subscription.

```php
EmailList::create([
    'name' => 'My list'
    'requires_confirmation' => true,
]);

```

--------------------------------

### MCP Server URL

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/mcp-server

The default endpoint for the MCP server.

```text
https://your-domain.test/mcp
```

--------------------------------

### Update User Model Configuration

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Update the User model reference in your configuration file to point to your application's User model.

```php
'models' => [
    ...
-     'user' => \Spatie\Mailcoach\Domain\Settings\Models\User::class,
+     'user' => \App\Models\User::class,
    ...
]
```

--------------------------------

### WaitActionComponent Livewire Component

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/automations

Extends `AutomationActionComponent` to define fields, data retrieval, validation rules, and rendering for a 'wait' action in Mailcoach automations. Requires `Spatie\Mailcoach\Domain\Automation\Support\Livewire\AutomationActionComponent`.

```php
use Spatie\Mailcoach\Livewire\Automations\AutomationActionComponent;

class WaitActionComponent extends AutomationActionComponent
{
    public string $length = '1';

    public string $unit = 'days';

    public array $units = [
        'minutes' => 'Minute',
        'hours' => 'Hour',
        'days' => 'Day',
        'weeks' => 'Week',
        'weekdays' => 'Weekdays',
        'months' => 'Month',
    ];

    public function getData(): array
    {
        return [
            'length' => (int) $this->length,
            'unit' => $this->unit,
        ];
    }

    public function rules(): array
    {
        return [
            'length' => ['required', 'integer', 'min:1'],
            'unit' => ['required', Rule::in([
                'minutes',
                'hours',
                'days',
                'weeks',
                'weekdays',
                'months',
            ])],
        ];
    }

    public function render()
    {
        return view('mailcoach::app.automations.components.actions.waitAction');
    }
}

```

--------------------------------

### Store Transactional Email in Mailable

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/transactional-emails

Use the `StoresMail` trait and call the `store()` method within the `content` function to log transactional emails. Ensure your Mailable class extends `Mailable` and uses the trait.

```php
use Illuminate\Mail\Mailables\Content;
use Illuminate\Mail\Mailables\Envelope;
use Spatie\Mailcoach\Domain\TransactionalMail\Mails\Concerns\StoresMail;

class YourMailable extends Mailable
{
    use StoresMail;

    public function envelope(): Envelope
    {
        return new Envelope(
            subject: 'Your order has been shipped!'
        );
    }
    
    public function content(): Content
    {
        $this->store();
    
        return new Content(
            markdown: 'mails.orderShipped'
        );
    }
}
```

--------------------------------

### Update Livewire Namespace

Source: https://www.mailcoach.app/self-hosted/documentation/v10/other/upgrading

Update references to Mailcoach Livewire components to the new namespace.

```text
Spatie\Mailcoach\Http\Livewire
```

```text
Spatie\Mailcoach\Livewire
```

--------------------------------

### Update Email List Defaults

Source: https://www.mailcoach.app/self-hosted/documentation/v10/features/audience

Configure default sender and reply-to information for an email list.

```php
$emailList->update([
    'default_from_email' => 'john@example.com',
    'default_from_name' => 'John Doe',
]);
```

```php
$emailList->update([
    'default_reply_to_email' => 'jane@example.com',
    'default_reply_to_name' => 'Jane Doe',
]);
```
Tokens:
Raw