README

MailBlocks is a component-based email builder for Laravel 10-12. Describe your transactional or marketing messages as PHP objects (headings, grids, rows, boxes, tables, etc.) and let the package render bulletproof markup automatically. Repository: https://github.com/lywebdev/laravel-mailblocks.

Documentation languages

• English
• Русский
• Українська
• Nederlands

Installation

composer require lywebdev/laravel-mailblocks

Quick start with MailTemplate

use MailBlocks\MailTemplate;
use MailBlocks\Components\{Button, Divider, Heading, Paragraph};

class OrderPaidMail extends MailTemplate
{
    public function __construct(
        private string $orderNumber,
        private string $orderUrl,
    ) {}

    public function build(): array
    {
        return [
            Heading::make('Order #' . $this->orderNumber)->center(),
            Paragraph::make('Your payment was received.'),
            Button::make('View order', $this->orderUrl),
            Divider::make()->margin('16px 0'),
            Paragraph::make('Thank you for staying with us!')->center(),
        ];
    }
}

Use it inside any Mailable:

public function content(): Content
{
    return (new OrderPaidMail($this->orderNumber, $this->orderUrl))->toContent();
}

Using MailComposer

use MailBlocks\MailComposer;
use MailBlocks\Components\{
    Box, Button, Divider, Grid\Column, Grid\Grid,
    Heading, Image, Paragraph, Row, Table
};

$html = MailComposer::make([
    Heading::make('Product Digest')->center(),
    Paragraph::make('Mix hero copy, CTA buttons, cards and tables in just a few calls.'),

    Row::make([
        Button::make('Start campaign', 'https://example.com/campaigns'),
        Button::make('Update profile', 'https://example.com/profile')->right(),
    ])->gap(20)->alignCenter(),

    Grid::make([
        Column::make(9)
            ->add(Heading::make('Campaign status')->h2()->left())
            ->add(Paragraph::make('Track opens, clicks and delivery in real time.'))
            ->add(Button::make('View report', 'https://example.com/report')->right()),
        Column::make(3)
            ->verticalCenter()
            ->add(Image::make(
                'https://via.placeholder.com/320x200.png?text=MailBlocks',
                'Dashboard preview',
                320
            )->rounded(24)->center()),
    ], gap: 20),

    Divider::make()->margin('32px 0'),

    Table::make(
        ['Metric', 'Value', 'Delta vs last week'],
        [
            ['CTR', '34%', '+3.2%'],
            ['Conversions', '1,204', '+18%'],
            ['Average order', '$105', '-2%'],
        ]
    )->marginTop('24px'),
])->renderHtml();

Components overview

• Text: Heading, Paragraph, Section, Divider.
• CTA & media: Button, Image.
• Layouts: Grid + Column (12-column system with gap and vertical alignment helpers), Row (inline blocks with justify*/align*/gap()), Box (fixed-width container with containerWidth() + verticalGap()).
• Data: Table ships with a modern dashboard look (rounded corners, zebra rows, shadow).
• Every component supports shared helpers: padding(), margin*(), width()/height(), containerWidth(), outline(), align(), etc.
• MailTemplate and MailComposer only accept explicit component objects, so you always see the full layout in PHP.

Dashboard-styled table

use MailBlocks\Components\Table;

Table::make(
    ['Metric', 'Value', 'Delta vs last week'],
    [
        ['CTR', '34%', '+3.2%'],
        ['Conversions', '1,204', '+18%'],
        ['Average order', '$105', '-2%'],
    ]
)->marginTop('24px')->outline('#e2e8f0');

Customizing the layout, header, and footer

Config-driven tweaks

1. Publish the config: php artisan vendor:publish --tag=mail-blocks-config.
2. Open config/mail-blocks.php and adjust:
   • brand.name, brand.tagline - company name and tagline (defaults to config('app.name')).
   • layout.header - logo URL, background, text color, badge label.
   • layout.footer - primary and secondary text, CTA label/link, support_email.
3. If you use custom Blade files, change layout.header.view / layout.footer.view.

Overriding Blade templates

1. Publish the views: php artisan vendor:publish --tag=mail-blocks-views.
2. Edit files in resources/views/vendor/mail-blocks:
   • layout.blade.php - page shell (background, container, box shadow, spacing).
   • partials/header.blade.php / partials/footer.blade.php - hero and footer blocks.
   • components/*.blade.php - individual component markup.
3. Update the markup to match your brand: change colors, add social icons, unsubscribe links, etc. Header/footer already render the current year and fall back to app.name, but you can alter this logic freely.
4. Need a different directory? Point layout.header.view / layout.footer.view at your own Blade files.

Creating custom components

namespace App\Mail\Components;

use MailBlocks\Components\Component;
use MailBlocks\Traits\RendersBlade;

class Alert extends Component
{
    use RendersBlade;

    public function __construct(private string $title, private string $message) {}

    public static function make(string $title, string $message): static
    {
        return new static($title, $message);
    }

    public function render(): string
    {
        return $this->renderBlade('mail.components.alert', [
            'title' => $this->title,
            'message' => $this->message,
        ]);
    }
}

resources/views/mail/components/alert.blade.php:

<table width="100%" cellpadding="0" cellspacing="0" style="background:#fff4e5;padding:20px;border-radius:14px;{{ $component->getStyleString() }}">
    <tr>
        <td style="color:#0f172a;font-size:15px;">
            <strong>{{ $title }}</strong>
            <p style="margin:12px 0 0;">{{ $message }}</p>
        </td>
    </tr>
</table>

Use it like any built-in component:

Alert::make('Heads up', 'We detected unusual activity.')->marginTop(24);

Recipes (ready-to-use templates)

The Examples folder contains several scenarios you can copy and adapt. Jump straight to the source on GitHub:

Tips

• For fixed-width columns inside Row, wrap content with Box::make()->containerWidth(200)->verticalGap(12).
• Use Column::verticalCenter() / verticalBottom() to align grid cells vertically.
• grid([...], $gap) uses padding, which renders reliably in Outlook.
• containerWidth() targets the wrapper table; width() targets the actual content inside the component.
• Need full control over visuals? Publish the Blade templates and edit resources/views/vendor/mail-blocks/layout.blade.php (plus header/footer) just like any regular email theme.