# Customization

For non-technical users: This page is for developers who want to modify MailTrixy's code, appearance, or functionality. Most customization (branding, colors, settings) can be done from the Admin Panel without any coding — see System Settings.

MailTrixy is designed to be highly customizable. This guide covers all the ways you can tailor the application to your specific needs.

## Custom Contact Fields

Each workspace can define custom fields to store additional data on contacts beyond the built-in fields (name, email, phone, company). Custom fields support multiple data types.

Field Type | Description | Example
--- | --- | ---
text | Single-line text input | Job title, department
textarea | Multi-line text area | Notes, address
select | Dropdown with predefined options | Lead status, priority
number | Numeric input | Deal value, employee count
date | Date picker | Birthday, contract date
checkbox | Boolean toggle | VIP flag, opt-in status

Custom fields can be managed from Settings → Contact Fields. They are automatically available in contact forms, import/export, campaign merge tags, and workflow conditions.

## Email Signatures

Each user can create multiple email signatures and assign a default signature per email account. Signatures support HTML formatting and dynamic merge tags.

    Available merge tags for signatures:

    {{user.name}}        - Current user's full name
    {{user.email}}       - Current user's email address
    {{user.title}}       - Current user's job title
    {{workspace.name}}   - Workspace name
    {{workspace.url}}    - Workspace URL
    {{date}}             - Current date

Signatures are managed from Settings → Email Signatures. The rich text editor supports images, links, and custom HTML for advanced formatting.

## Notification Preferences

Users can configure granular notification preferences for different event types. Notifications can be delivered through multiple channels.

- In-app notifications — Real-time browser notifications via Livewire polling.
- Email notifications — Digest or instant email alerts for important events.
- Slack notifications — Push notifications to a configured Slack channel.
- Telegram notifications — Push notifications to a Telegram chat or group.

Configurable notification events include: new conversation assigned, conversation reply received, campaign completed, workflow failed, AI reply ready for review, payment received, and subscription expiring.

## Webhook Configuration

MailTrixy can send webhook notifications to external services when specific events occur. Each workspace can configure multiple webhook endpoints.

    // Available webhook events:
    contact.created          contact.updated          contact.deleted
    conversation.created     conversation.replied      conversation.closed
    campaign.sent            campaign.completed
    email.received           email.sent
    workflow.completed       workflow.failed
    subscription.created     subscription.cancelled

Webhook payloads are signed with an HMAC-SHA256 signature using a per-webhook secret key. The signature is sent in the `X-MailTrixy-Signature` header. Failed deliveries are retried up to 5 times with exponential backoff.

    // Example webhook payload
    {
        "event": "contact.created",
        "timestamp": "2026-03-25T10:30:00Z",
        "workspace_id": 1,
        "data": {
            "id": 42,
            "name": "Jane Smith",
            "email": "jane@example.com",
            "company": "Acme Corp",
            "created_at": "2026-03-25T10:30:00Z"
        }
    }

## Blade View Customization

All frontend views are built with Blade templates and can be customized by publishing them to your application's `resources/views` directory.

    # Publish all views for customization
    php artisan vendor:publish --tag=mailtrixy-views

    # Key view directories:
    resources/views/
    ├── layouts/
    │   ├── app.blade.php          # Main application layout
    │   ├── auth.blade.php         # Authentication pages layout
    │   └── admin.blade.php        # Admin panel layout
    ├── components/
    │   ├── sidebar.blade.php      # Navigation sidebar
    │   ├── header.blade.php       # Top header bar
    │   └── modal.blade.php        # Reusable modal component
    ├── email-templates/
    │   └── 52 customizable templates
    └── livewire/
        └── 47 component views

The 52 email templates cover all transactional and marketing scenarios, including welcome emails, password resets, campaign templates, invoice notifications, and workflow action emails. Each template uses a consistent base layout with customizable header, footer, colors, and logo.

## Tailwind Theme Customization

MailTrixy uses Tailwind CSS 4 with a customizable theme configuration. You can modify the color scheme, typography, spacing, and other design tokens.

    /* resources/css/app.css */
    @import "tailwindcss";

    @theme {
        --color-primary: #4F46E5;      /* Indigo - main brand color */
        --color-primary-light: #818CF8;
        --color-primary-dark: #3730A3;
        --color-secondary: #06B6D4;    /* Cyan - accent color */
        --color-success: #10B981;
        --color-warning: #F59E0B;
        --color-danger: #EF4444;
        --color-surface: #F9FAFB;
        --color-sidebar: #1F2937;
        --font-sans: 'Inter', system-ui, sans-serif;
        --font-mono: 'JetBrains Mono', monospace;
    }

    /* Rebuild assets after theme changes */
    /* npm run build */

## Adding New AI Providers

MailTrixy supports 4 built-in AI providers (OpenAI, Gemini, Claude, DeepSeek) and is designed to accommodate additional providers through a driver-based architecture.

    // 1. Create a new provider driver
    // app/Services/AI/Drivers/CustomAiDriver.php

    namespace App\Services\AI\Drivers;

    use App\Services\AI\Contracts\AiDriverInterface;

    class CustomAiDriver implements AiDriverInterface
    {
        public function chat(string $prompt, array $context = []): string
        {
            // Implement API call to your AI provider
        }

        public function countTokens(string $text): int
        {
            // Return estimated token count
        }

        public function getModels(): array
        {
            // Return available model names
        }
    }

    // 2. Register the driver in AiServiceProvider
    // app/Providers/AiServiceProvider.php

    $this->app->make(AiManager::class)->extend('custom', function () {
        return new CustomAiDriver(config('services.custom_ai'));
    });

    // 3. Add configuration
    // config/services.php
    'custom_ai' => [
        'api_key' => env('CUSTOM_AI_API_KEY'),
        'base_url' => env('CUSTOM_AI_BASE_URL'),
        'model' => env('CUSTOM_AI_MODEL', 'default'),
    ],

## Adding New Payment Gateways

MailTrixy integrates with 40+ payment gateways through a unified billing interface. Adding a new gateway follows the same driver pattern used for AI providers.

    // 1. Create a new payment gateway driver
    // app/Services/Billing/Gateways/CustomGateway.php

    namespace App\Services\Billing\Gateways;

    use App\Services\Billing\Contracts\PaymentGatewayInterface;

    class CustomGateway implements PaymentGatewayInterface
    {
        public function createSubscription(Plan $plan, User $user): Subscription
        {
            // Create subscription via gateway API
        }

        public function cancelSubscription(Subscription $subscription): bool
        {
            // Cancel subscription via gateway API
        }

        public function handleWebhook(Request $request): void
        {
            // Process incoming webhook from the gateway
        }

        public function getCheckoutUrl(Plan $plan, User $user): string
        {
            // Generate payment checkout URL
        }
    }

    // 2. Register in the BillingServiceProvider
    // 3. Add gateway credentials to config/services.php
    // 4. Add the gateway option in the admin panel settings

The `PaymentGatewayInterface` contract ensures all gateways provide a consistent API for subscription management, one-time charges, refunds, and webhook handling.