README

A high-performance, developer-friendly Laravel SDK for the Mailu API. Designed for Indunil Peramuna with focus on DTOs, type safety, and clean architecture.

✨ Features

• PHP: ^8.2
• Laravel: ^12.0 || ^13.0
• 🚀 Full API Coverage: Support for Users, Domains, Aliases, Alternatives, Relays, and Tokens.
• 🛡️ Type-Safe DTOs: Heavily utilizes spatie/laravel-data for structured, validated data handling.
• ⚡ Built-in Caching: Intelligent caching of GET requests to optimize performance.
• 🧱 Modular Architecture: Cleanly separated concerns using traits (HasUsers, HasDomains, etc.).
• 🧪 Pest Powered: Comprehensive test suite written in Pest PHP.
• 🧩 Clean Facade: Intuitive Mailu facade for standard operations.

📦 Installation

You can install the package via composer:

composer require iperamuna/mailu-laravel

⚙️ Configuration

Publish the config file:

php artisan vendor:publish --tag="mailu-config"

Add your credentials to .env:

MAILU_API_URL=https://mail.yourdomain.com/api/v1
MAILU_API_TOKEN=your_token_here
MAILU_CACHE_ENABLED=true

📖 Usage Examples

1. Simple Facade Usage

The most common way to interact with the SDK.

use Iperamuna\Mailu\Facades\Mailu;

// List all users
$users = Mailu::listUsers(); // Returns Collection<UserData>

// Create a new domain
Mailu::createDomain([
    'name' => 'example.com',
    'comment' => 'Managed by Laravel',
]);

// Generate DKIM keys
Mailu::generateDKIM('example.com');

2. Usage in a Controller

Inject the MailuService directly into your controller methods.

namespace App\Http\Controllers;

use Iperamuna\Mailu\MailuService;
use Illuminate\Http\Request;

class MailboxController extends Controller
{
    public function index(MailuService $mailu)
    {
        return view('mailboxes.index', [
            'users' => $mailu->listUsers(),
        ]);
    }

    public function store(Request $request, MailuService $mailu)
    {
        $mailu->createUser($request->only(['email', 'raw_password', 'displayed_name']));
        
        return back()->with('success', 'Mailbox created!');
    }
}

3. Usage in a Filament Resource

Ideal for building custom admin interfaces. Since Mailu returns an array/collection, you can use Filament's Table Builder with custom data.

namespace App\Filament\Resources;

use Filament\Resources\Resource;
use Filament\Tables\Table;
use Filament\Tables\Columns\TextColumn;
use Iperamuna\Mailu\Facades\Mailu;
use Iperamuna\Mailu\Data\UserData;

class MailboxResource extends Resource
{
    public static function table(Table $table): Table
    {
        return $table
            ->content(fn () => Mailu::listUsers()) // Fetch from API
            ->columns([
                TextColumn::make('email')
                    ->searchable()
                    ->sortable(),
                TextColumn::make('displayed_name')
                    ->label('Name'),
                TextColumn::make('quota_bytes_used')
                    ->label('Usage')
                    ->formatStateUsing(fn ($state) => number_format($state / 1024 / 1024, 2) . ' MB'),
            ])
            ->actions([
                \Filament\Tables\Actions\DeleteAction::make()
                    ->action(fn (UserData $record) => Mailu::deleteUser($record->email)),
            ]);
    }
}

🧪 Testing

composer test

🔒 Security

If you discover any security-related issues, please email iperamuna@gmail.com.

👤 Credits

• Indunil Peramuna

📄 License

The MIT License (MIT). Please see License File for more information.