Laravel Livewire Installation

You can install Email Builder with Laravel project using Livewire.

Requirements

• Email Builder API Token
• Laravel Livewire - Use Livewire Starter Kit
• Laravel Sanctum

Install Laravel Livewire

Ensure Livewire is installed before running the installation command. If you are using Livewire Starter Kit, you have already Livewire installed. Visit Livewire installation docs for more info,

composer require livewire/livewire

Install Laravel Sanctum

Email Builder UI communicate with backend via API. We need to install laravel/sanctum to protect our API routes. You are free to use other API auth libraries or methods. For this installation we will run following command to get Laravel Sanctum. Visit Laravel Sanctum Docs for more info.

php artisan install:api

Composer Authentication

You need an API key to install PHP package(s) from the emailbuilder.dev repository. Composer supports storing this token in the auth.json file. Run following command to install composer credentials in project root auth.json file. Add --global flag, if you want to store globally (optional).

composer config http-basic.composer.emailbuilder.dev <username> <api-token>

• Replace <username> with your Email.
• Replace <api-key> with your API key (token).

CAUTION

Add /auth.json to your .gitignore. Do not commit these credentials with source code.

API Token

Get your API token from Email Builder

Add Repository

To install packages from the emailbuilder.dev repository, add it to your project root composer.json file:

composer config \
    repositories.emailbuilder \
    composer https://composer.emailbuilder.dev

Above command will add following to the composer.json file

// composer.json
{
    ...
    "repositories": {
        "emailbuilder": {
            "type": "composer",
            "url": "https://composer.emailbuilder.dev"
        }
    }
}

.test TLD for local

For better result we suggest to use <your-domain>.test domain for local development instead of localhost.

# .env file
APP_URL=http://<example-domain>.test

Install Laravel Email Builder

Now we have added credentials to access repository, run composer require apsonex/email-builder-laravel to install the PHP package.

composer require apsonex/email-builder-laravel

Run Installation Command

Installing all the required files will take so much time. But not to worry, We will scaffold for you required file so that you get a good start. Simply run php artisan email-builder:laravel-install

php artisan email-builder:install

email-builder:install command will add bunch of files in you Laravel project.

Post Installation

After installation is done, we need to tell Laravel about the new files. Perform following post installation step to get Email Builder up and running.

Routes Setup

Installation has created routes/email-builder-api.php & routes/email-builder-web.php files in routes directory. We need to make aware Laravel about those files. In project bootstrap/app.php file, we need to install the newly created routes file as follows.

<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: [
            __DIR__ . '/../routes/web.php',
            __DIR__ . '/../routes/email-builder-web.php', 
        ],
        api: [
            __DIR__ . '/../routes/api.php',
            __DIR__ . '/../routes/email-builder-api.php', 
        ],
        commands: __DIR__ . '/../routes/console.php',
        health: '/up',
        apiPrefix: 'api'
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->statefulApi(); 
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

Environment Variables

Ensure to add following environment variables to your .env file.

• Retrieve the api-prefix value from the apiPrefix parameter defined in the withRouting method inside bootstrap/app.php.

• Retrieve the api-prefix-from-email-builder-api-route value from the prefix('apsonex-email-builder') defined in the Route prefix within routes/email-builder-api.php.

EMAIL_BUILDER_TOKEN=<token>

# e.g. https://example.com/api
EMAIL_BUILDER_API_URL=http://<your-domain>/<api-prefix>

# e.g. deepseek
EMAIL_BUILDER_AI_PROVIDER=<provider>

# e.g. sk-abc...
DEEPSEEK_API_KEY=<ai-provider-api-token>

# e.g. deepseek-chat
DEEPSEEK_MODEL=<ai-provider-model>

Migrate

Ensure run migrations

php artisan migrate

UI Access

Add UI access to sidebar menu items. Visit resources/views/components/layouts/app/sidebar.blade.php file and add menu items.

<!-- resources/views/components/layouts/app/sidebar.blade.php -->
<flux:navlist.item icon="at-symbol" :href="App\EmailBuilder\Enums\EmailBuilderRoute::Web_Email_Templates_Index->url()" :current="request()->routeIs(App\EmailBuilder\Enums\EmailBuilderRoute::Web_Email_Templates_Index->value)" wire:navigate>{{ __('Email Templates') }}</flux:navlist.item>
<flux:navlist.item icon="users" :href="App\EmailBuilder\Enums\EmailBuilderRoute::Web_Email_Receivable_Index->url()" :current="request()->routeIs(App\EmailBuilder\Enums\EmailBuilderRoute::Web_Email_Receivable_Index->value)" wire:navigate>{{ __('Email Receivables') }}</flux:navlist.item>

Above nav items can be added as per following code:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}" class="dark">
    <head>
        {...}
    </head>
    <body class="min-h-screen bg-white dark:bg-zinc-800">
        <flux:sidebar sticky stashable class="border-e border-zinc-200 bg-zinc-50 dark:border-zinc-700 dark:bg-zinc-900">
            {...}

            <flux:navlist variant="outline">
                {...}

                <flux:navlist.item icon="at-symbol" :href="App\EmailBuilder\Enums\EmailBuilderRoute::Web_Email_Templates_Index->url()" :current="request()->routeIs(App\EmailBuilder\Enums\EmailBuilderRoute::Web_Email_Templates_Index->value)" wire:navigate>{{ __('Email Templates') }}</flux:navlist.item> 

                <flux:navlist.item icon="users" :href="App\EmailBuilder\Enums\EmailBuilderRoute::Web_Email_Receivable_Index->url()" :current="request()->routeIs(App\EmailBuilder\Enums\EmailBuilderRoute::Web_Email_Receivable_Index->value)" wire:navigate>{{ __('Email Receivables') }}</flux:navlist.item> 

            </flux:navlist>

            {...}
        </flux:sidebar>

        {...}
    </body>
</html>

CSS Variables

Email Builder is built on top of Shadcn. Add following css-variables to your project style. Change variable to match your branding. Dark theme support is coming soon.

:root {
    --background: oklch(1 0 0);
    --foreground: oklch(0.145 0 0);
    --card: oklch(1 0 0);
    --card-foreground: oklch(0.145 0 0);
    --popover: oklch(1 0 0);
    --popover-foreground: oklch(0.145 0 0);
    --primary: oklch(0.205 0 0);
    --primary-foreground: oklch(0.985 0 0);
    --secondary: oklch(0.97 0 0);
    --secondary-foreground: oklch(0.205 0 0);
    --muted: oklch(0.97 0 0);
    --muted-foreground: oklch(0.556 0 0);
    --accent: oklch(0.97 0 0);
    --accent-foreground: oklch(0.205 0 0);
    --destructive: oklch(0.577 0.245 27.325);
    --destructive-foreground: oklch(0.577 0.245 27.325);
    --border: oklch(0.922 0 0);
    --input: oklch(0.922 0 0);
    --ring: oklch(0.708 0 0);
    --chart-1: oklch(0.646 0.222 41.116);
    --chart-2: oklch(0.6 0.118 184.704);
    --chart-3: oklch(0.398 0.07 227.392);
    --chart-4: oklch(0.828 0.189 84.429);
    --chart-5: oklch(0.769 0.188 70.08);
    --radius: 0.625rem;
    --sidebar: oklch(0.985 0 0);
    --sidebar-foreground: oklch(0.145 0 0);
    --sidebar-primary: oklch(0.205 0 0);
    --sidebar-primary-foreground: oklch(0.985 0 0);
    --sidebar-accent: oklch(0.97 0 0);
    --sidebar-accent-foreground: oklch(0.205 0 0);
    --sidebar-border: oklch(0.922 0 0);
    --sidebar-ring: oklch(0.708 0 0);
}

For more info visit Shadcn-Vue

Tailwind CSS

Tailwind CSS need content location to compile css for Email Builder.

Laravel Inertia React

/* app.css */
@source '../../vendor/apsonex/email-builder-laravel/resources/dist/**/*.js';

Laravel Inertia Vue

/* app.css */
@source '../../vendor/apsonex/email-builder-laravel/resources/dist/**/*.js';

Laravel Livewire

/* app.css */
@source '../../vendor/apsonex/email-builder-laravel/resources/dist/**/*.js';

Laravel Filament PHP

/* app.css */
@source '../../vendor/apsonex/email-builder-laravel/resources/dist/**/*.js';

Publish Updated Assets

To publish latest updated assets, run following command.

php artisan vendor:publish --tag=email-builder-laravel-assets --force

To automate the assets publication, you can add above command in composer hooks

// composer.json
{
    "scripts": {
        "post-autoload-dump": [
            ...
            "@php artisan vendor:publish --tag=email-builder-laravel-assets --force"
        ],
        "post-update-cmd": [
            ...
            "@php artisan vendor:publish --tag=email-builder-laravel-assets --force"
        ],
    },
}

It will publish two files in public directory.

• public/vendor/apsonex/email-builder-laravel/livewire/livewire-email-builder.js
• public/vendor/apsonex/email-builder-laravel/livewire/manifest.json

Installation Details

Installation will generate required files to run email builder. Lets see what files it will generate and options to customize those files.

Route Files

Installation will generate two route files. routes/email-builder-api.php and routes/email-builder-web.php.

• routes/email-builder-api.php is responsible to provide necessary api access to email builder. Make sure you have secured it with auth. In following example we are using auth:sanctum middleware to protect api routes.

// routes/email-builder-api.php
<?php

use Illuminate\Support\Facades\Route;
{...}

Route::middleware(['auth:sanctum', 'verified'])->as('email-builder.')->group(function () {
    // Config To initialize
    Route::get('/initialize-config', BaseController\InitializeController::class)->name('initialize-config');

    {...}
});

• routes/email-builder-web.php is responsible to provide Email Builder UI access to user. You can design and broadcast email template to multiple users or leads at once. But if you want to send quick email to single user or lead, just use quick-send example below. Customize according to your need.

// routes/email-builder-web.php
<?php

use Illuminate\Support\Facades\Route;
{...}

Route::middleware(['auth', 'verified'])->group(function () {

    // comments
    Route::get('/email-templates', LivewireComponents\EmailTemplatesComponent::class)->name(EmailBuilderRoute::Web_Email_Templates_Index->value);
    {...}
});

Files Updated Or Added

Email builder will generate or change following files to integrate into web app. You can further customize according to your needs.

🗂️ project-root/
├─ bootstrap/app.php
├─ 🗂️ app
│  └─ 🗂️ EmailBuilder
│  │  ├─ 🗂️ Enums
│  │  │  ├─ EmailBuilderContextKey.php
│  │  │  └─ EmailBuilderContextKey.php
│  │  ├─ 🗂️ PlaceholderCasts/
│  │  │  ├─ Date.php
│  │  │  └─ {...} // other casts
│  │  └─ 🗂️ Placeholders/
│  │     ├─ BusinessInfoPlaceholders.php
│  │     └─ {...} // other placeholders
│  └─ 🗂️ Livewire
│     └─ 🗂️ EmailBuilder
│        ├─ 🗂️ Concerns
│        │  └─ HasEmailBuilderConfig.php
│        ├─ EmailTemplateCreateComponent.php
│        ├─ EmailTemplateEditComponent.php
│        ├─ EmailTemplatesComponent.php
│        ├─ QuickSendReceiverListComponent.php
│        └─ QuickSendUiShowComponent.php
└─ 🗂️ resources
   └─ 🗂️ views
      └─ 🗂️ livewire
         └─ 🗂️ email-builder
            ├─ 🗂️ email-templates/
            │  └─ partials/index-heading.blade.php
            │  └─ index.blade.php
            └─ 🗂️ leads/
               └─ partials/index-heading.blade.php
               └─ index.blade.php