Update Process - MailTrixy Documentation

This guide walks you through the process of updating MailTrixy to a newer version. Each release ships as a small per-version ZIP (e.g. update_1_5.zip) which you upload through the in-app updater — not the full project archive you originally used to install. MailTrixy replaces the application source files with the new ones from the ZIP. Always review the Change Log before updating to understand what has changed and whether there are any breaking changes.

What's inside the CodeCanyon download? When you extract the package from your CodeCanyon account, you will see four folders:

MailTrixy/ — the full project. Use this only for a fresh install on a brand-new server.

Update/ — contains the per-version update archives, e.g. update_1_5.zip. This is the file you upload in Admin → System Update. It is much smaller (typically a few MB) because it carries only the changed files plus the new migrations.

Database/ — SQL upgrade files for the Manual Update path. Only needed if you are not using the in-app updater.

Documentation/ — this offline copy of the docs.

Pick the file that matches the version you are upgrading to — e.g. update_1_5.zip to install v1.5. Uploading the full project ZIP from the MailTrixy/ folder into the in-app updater will fail validation — the updater specifically looks for the per-version update manifest.

⚠️ Read This First — If You Have Customized the Code

The update ZIP overwrites the application source code. Any edits you have made directly to PHP, Blade, JavaScript, CSS, or config files in your installation will be lost when you apply an update. There is no automatic merge.

Both the in-app updater (Admin → System Update) and the manual update method work the same way: they take the new files out of the ZIP and write them on top of the existing files in your installation. If you have customized any file inside the application code, that file will be reverted to the new version from the ZIP.

What gets overwritten

Every file inside these folders is replaced by the version from the update ZIP:

app/ — Controllers, Models, Services, Jobs, Livewire components, Listeners, Console commands
resources/views/ — All Blade templates (admin, frontend, inbox, settings, emails)
resources/css/, resources/js/ — Source CSS / JS, plus the compiled bundles in public/build/
routes/ — web.php, api.php, console.php
config/ — All config files (database, queue, mail, cache, etc.)
database/migrations/ — Migration files (new ones get added, existing ones stay the same)
public/build/ — Pre-compiled Vite assets
composer.json, composer.lock, package.json and any other root-level project files

What is preserved (never touched by the update)

.env — Your database credentials, API keys, app key, mail settings
storage/ — Uploaded files (attachments, contact imports, avatars, logos), logs, cached views, sessions
Your database — rows are kept intact; only schema is extended by migrations
Anything you saved through the admin UI (Theme Studio colors, Site Name, Footer content, Custom CSS / Header Code / Footer Code, Email Templates, AI prompts, Workflows, Pages, Plans) — these are stored in the database, not in files, so updates do not touch them

If you have edited any file under app/, resources/views/, routes/, config/, resources/css/, resources/js/, or public/build/:

Do NOT click Apply Update until you have either:

Saved every change as a clean diff/patch you can re-apply after the update, or

Moved your customisation into a supported extension point (see below).

Skipping this step will revert all your code modifications to the stock version shipped in the update ZIP. This is not a bug — it is how the update process works.

How to customize safely (so updates don't wipe your changes)

If you need to brand or adapt MailTrixy without your changes being lost on every update, use the built-in extension points instead of editing source files:

Branding (logo, colors, fonts, copy) — use Admin → Theme Studio, Admin → Settings → General → Site Name / Logo / Font, and Admin → Frontend Settings. These write to system_settings in the database and survive every update.
Custom CSS — Admin → Settings → Advanced → Custom CSS. The block is injected into every page's <head>. Use this for typography tweaks, layout overrides, hiding elements, etc.
Custom <head> and <body> code — Admin → Frontend Settings → Custom Code. Drop analytics tags, chat widgets, schema markup, or any third-party script here. Saved to system_settings.
Landing-page content — Admin → Frontend Settings for hero copy, features, testimonials, FAQ, CTA, footer, legal pages. All stored in the pages table; never need a code edit.
Email templates & signatures — Settings → Email Templates and Settings → Email Signature. Database-backed.
New channels / vertical features — build them as an Addon (Admin → Addons). Addons live in their own folder and are not touched by core updates.

If your customisation can't be expressed through any of the above, contact support before updating — we may be able to add a hook or setting in the next release so you don't have to maintain a fork.

Before Updating

Before starting the update process, create backups of all critical data. This ensures you can restore your installation if anything goes wrong.

IMPORTANT: Never skip the backup step. Updates may include database migrations that alter your data structure, and a backup is the only way to fully recover if issues arise.

You can create backups from your hosting control panel (most hosting providers have a one-click backup feature in cPanel / hPanel):

Back up your database - Use phpMyAdmin (available in cPanel/hPanel) to export your database.
Back up your .env file - Download the .env file from your hosting root directory to your computer. This contains your database credentials, API keys, email account settings, and AI provider configurations.
Back up your storage folder - Download or compress the storage/app directory which contains all uploaded files (attachments, contact imports, avatars, etc.).
Back up any customized files - If you have modified any Blade views, configuration files, or other application files, note them down and back them up separately
Note your current version - Check your current version so you can reference the changelog for all changes between your version and the latest

In-App Update

MailTrixy includes a built-in updater accessible from the admin panel. This is the recommended method for most users.

Step 1: Backup

Before proceeding, ensure you have created a full backup of your database, .env file, and storage/ directory as described in the Before Updating section above.

Step 2: Upload the per-version update ZIP

Download the latest release from your CodeCanyon account and extract it. Open the Update/ folder — inside you will find a versioned archive named like update_1_5.zip (the number matches the version you are installing). This is the small, update-only archive (a few MB), not the full project ZIP inside the MailTrixy/ folder that you originally used to install.

In the admin panel, navigate to Settings → System Update and upload that file using the provided uploader. The updater validates the ZIP's manifest and version number before accepting it — if you pick the wrong archive (e.g. the full project ZIP), the upload is rejected with a clear error.

Do not upload the full project ZIP here. The full archive contains vendor/, node_modules/, and other folders the updater intentionally does not touch — uploading it will fail validation. The in-app updater only accepts the per-version ZIP from the Update/ folder.

Step 3: Apply the Update

Click the "Apply Update" button. The system will extract the update files and replace the application code with the new version. Your .env file, your storage/ directory, and your database content are not touched.

Reminder: If you have edited any file under app/, resources/views/, routes/, config/, resources/css/, resources/js/, or public/build/, those edits will be overwritten by the version from the ZIP. Re-read the customization warning at the top of this page before clicking Apply.

Step 4: Run Migrations

After the files are updated, the system will prompt you to run database migrations. Click "Run Migrations" to apply any new database schema changes. This will only run migrations that have not been executed yet.

Step 5: Finalize

The updater will automatically clear application caches and restart queue workers. Verify that the admin dashboard loads correctly and key features (email sync, campaigns, AI replies) are working as expected.

Rollback (In-App Update)

If something goes wrong during the in-app update, restore your previous installation from the backups you created:

Restore your database backup using phpMyAdmin
Restore the previous application files from your backup
Verify the admin dashboard loads correctly and key features are working

Manual Update

If the in-app updater is not available or you prefer manual control, follow these steps.

Step 1: Download the Latest Version

Download the latest release from your CodeCanyon downloads page and extract the package. You will see four folders — MailTrixy/, Update/, Database/, Documentation/. For the manual update flow you can use either archive:

Update/update_1_5.zip (preferred) — the small per-version archive. Contains only the files that changed between releases, so the upload is small and there is less to overwrite. Pick the file that matches the version you are upgrading to.
The full project ZIP inside MailTrixy/ — works too, but it is much larger and copies a lot of unchanged files. Useful only when you also want to refresh vendor/ / public/build/ from scratch.

Step 2: Extract Files

Extract whichever ZIP you downloaded to a temporary directory on your computer. Browse the extracted contents to confirm you have the new app/, resources/, routes/, etc. folders ready to upload.

Step 3: Replace Application Files

Upload the new files from the update ZIP to your hosting using your hosting File Manager (cPanel/hPanel), overwriting the existing files. Do not overwrite or delete the following:

.env - Your environment configuration (database credentials, app key, API keys, etc.)
storage/ - Your uploaded files, email attachments, logs, and cached data

Every other file in your installation will be replaced by the version from the ZIP. If you previously edited any source file (Blade view, controller, service, route, config, CSS, JS), back up your modified versions before you upload, then re-apply your changes after the new files are in place. See the customization warning at the top of this page for the safer alternatives.

Note: All PHP dependencies and frontend assets are pre-built and included in the update package. You do not need to run Composer or NPM commands.

Step 4: Import the Database Upgrade File

The Database/ folder in the CodeCanyon package contains a per-version SQL upgrade file. Pick the one matching the version you are installing — for example, to upgrade an existing install to v1.5, use:

Database/upgrade-1.4-to-1.5.sql

Open phpMyAdmin (available in cPanel/hPanel), select your MailTrixy database, click the Import tab, choose the upgrade SQL file from the Database/ folder, and click Go. This applies the schema changes required for the new version.

Note: If you used the In-App Updater, this step is already handled by the wizard's Run Migrations step — you do not need to import the SQL file by hand.

IMPORTANT: Make sure you have backed up your database before importing this file. The upgrade SQL modifies your existing data structure.

Step 5: Clear Application Caches

From the admin panel, navigate to Settings → System and click Clear Cache to clear all application caches. This ensures the new code runs with fresh configuration.

Step 6: Verify the Update

Verify the following after completing the update:

Admin dashboard loads correctly
You can log in and navigate all sections
Email sync is functioning (check connected accounts)
Campaign sending works as expected
AI features are generating replies
Queue workers are processing jobs
Payment gateways are functional (test a checkout flow if possible)

Important Notes

Critical: Pay close attention to these guidelines to avoid data loss.

Customized source files will be overwritten — This is the single most common cause of post-update regressions reported to support. The update ZIP replaces the contents of app/, resources/, routes/, config/, and public/build/ with the new version. There is no merge step. Re-read the customization warning at the top of this page before applying any update.
Never delete your .env file during updates - This file contains your database credentials, API keys, email account configurations, AI provider settings, and application key. Losing it will break your installation
Never delete the storage directory - This directory contains all uploaded files (email attachments, contact imports, avatars), application logs, and cached files. Deleting it means losing all user-uploaded content
Always import the database upgrade file after updating - New versions may include database schema changes. Skipping the upgrade SQL will cause errors
Clear all caches after update - Stale cached configurations, routes, and views can cause unexpected behavior with new code
Check the changelog for breaking changes - Some updates may require additional manual steps such as new environment variables, configuration changes, or data migrations. Always review the Change Log before updating