MailStack | Self-Hosted Email Marketing Platform

Step 2. Install Nginx

sudo apt install -y nginx
sudo systemctl enable nginx
sudo systemctl start nginx

Step 3. Install MySQL

sudo apt install -y mysql-server
sudo systemctl enable mysql
sudo systemctl start mysql
sudo mysql_secure_installation

Create the application database and user:

sudo mysql -u root -p

CREATE DATABASE mailstack CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'mailstack_user'@'localhost' IDENTIFIED BY 'StrongPassword123!';
GRANT ALL PRIVILEGES ON mailstack.* TO 'mailstack_user'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 4. Install PHP and required extensions

sudo apt install -y software-properties-common
sudo add-apt-repository ppa:ondrej/php -y
sudo apt update
sudo apt install -y php8.3 php8.3-fpm php8.3-cli php8.3-mysql php8.3-mbstring \
php8.3-xml php8.3-curl php8.3-bcmath php8.3-zip php8.3-gd php8.3-intl

sudo systemctl enable php8.3-fpm
sudo systemctl start php8.3-fpm

Step 5. Install Composer

cd /tmp
curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer
composer --version

Step 6. Install Node.js and npm

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
node -v
npm -v

Node.js is required to build the frontend assets used by the Livewire and Laravel interface.

Step 7. Upload the project and install dependencies

cd /var/www
sudo mkdir -p mailstack
sudo chown $USER:$USER mailstack
cd mailstack

# Upload and extract the project files here

composer install --optimize-autoloader --no-dev
npm install
npm run build

Step 8. Configure the environment file

APP_NAME="MailStack"
APP_ENV=production
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mailstack
DB_USERNAME=mailstack_user
DB_PASSWORD=StrongPassword123!

QUEUE_CONNECTION=database
SESSION_DRIVER=database
CACHE_STORE=file

Step 9. Run Laravel setup commands

php artisan key:generate
php artisan migrate --seed
php artisan storage:link
php artisan queue:table
php artisan failed:table
php artisan migrate
chmod -R 775 storage bootstrap/cache
php artisan config:cache
php artisan route:cache
php artisan view:cache

Step 10. Configure Nginx virtual host

Create an Nginx site configuration for your domain:

sudo nano /etc/nginx/sites-available/mailstack

server {
    listen 80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/mailstack/public;
    index index.php index.html;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
    }

    location ~ /\.ht {
        deny all;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/mailstack /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 11. Configure the queue worker with Supervisor

sudo apt install -y supervisor

Create the worker configuration:

sudo nano /etc/supervisor/conf.d/mailstack-worker.conf

[program:mailstack-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/mailstack/artisan queue:work --sleep=3 --tries=3 --timeout=120
autostart=true
autorestart=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/mailstack/storage/logs/worker.log

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start mailstack-worker:*

Step 12. Add the Laravel scheduler cron job

crontab -e

* * * * * php /var/www/mailstack/artisan schedule:run >> /dev/null 2>&1

Step 13. Install SSL with Certbot

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com -d www.yourdomain.com

Test renewal:

sudo certbot renew --dry-run

Step 2. Create and update the environment file

cp .env.example .env

Edit the .env file and update the application URL, database credentials, queue driver, and mail defaults.

APP_NAME="MailStack"
APP_ENV=production
APP_KEY=
APP_DEBUG=false
APP_URL=https://yourdomain.com

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mailstack
DB_USERNAME=your_db_user
DB_PASSWORD=your_db_password

QUEUE_CONNECTION=database
CACHE_STORE=file
SESSION_DRIVER=database

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

Step 3. Install PHP dependencies

composer install --optimize-autoloader --no-dev

Step 4. Generate the application key

php artisan key:generate

Step 5. Install frontend dependencies and build assets

npm install
npm run build

Step 6. Run migrations and seed the initial data

php artisan migrate --seed

This prepares the database tables and inserts the default system data required by the application.

Step 7. Link the storage directory

php artisan storage:link

Step 8. Configure file permissions

chmod -R 775 storage bootstrap/cache

Step 9. Create queue tables if needed

If you are using the database queue driver, make sure the queue tables exist.

php artisan queue:table
php artisan failed:table
php artisan migrate

Step 10. Start the queue worker

Campaign delivery and background jobs depend on a running queue worker.

php artisan queue:work --tries=3

Recommended Supervisor configuration for VPS:

[program:mailstack-worker]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/mailstack/artisan queue:work --sleep=3 --tries=3 --timeout=120
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/www/mailstack/storage/logs/worker.log

Step 11. Add the Laravel scheduler cron

* * * * * php /var/www/mailstack/artisan schedule:run >> /dev/null 2>&1

https://yourdomain.com/cron/campaigns/dispatch-scheduled?token=YOUR_CRON_TOKEN

Example: Login

POST /api/login

Request body:

{
  "email": "[email protected]",
  "password": "secret-password",
  "device_name": "postman"
}

Successful response:

{
  "message": "Login successful",
  "token": "1|sanctum_plain_text_token",
  "user": {
    "id": 1,
    "name": "Admin User",
    "email": "[email protected]"
  }
}

Example: List Contacts

GET /api/contacts?page=1&per_page=20&search=john

Example response:

{
  "data": [
    {
      "id": 12,
      "name": "John Carter",
      "email": "[email protected]",
      "status": "subscribed"
    }
  ],
  "links": {
    "next": null,
    "prev": null
  },
  "meta": {
    "current_page": 1,
    "per_page": 20,
    "total": 1
  }
}

Example: Create Campaign

POST /api/campaigns

Request body:

{
  "name": "May Product Launch",
  "subject": "Introducing our latest update",
  "template_id": 3,
  "mail_gateway_id": 2,
  "group_ids": [1, 4],
  "segment_ids": [2],
  "from_name": "MailStack Team",
  "from_email": "[email protected]",
  "content": "<h1>Hello</h1><p>Campaign body here.</p>"
}

Example response:

{
  "message": "Campaign created successfully",
  "data": {
    "id": 25,
    "name": "May Product Launch",
    "status": "draft"
  }
}

Example: Send Test Email

POST /api/campaigns/test-send

Request body:

{
  "test_email": "[email protected]",
  "subject": "Preview: May Product Launch",
  "from_name": "MailStack Team",
  "from_email": "[email protected]",
  "email_template_id": 3,
  "mail_gateway_id": 2
}

Example response:

{
  "message": "Test email sent successfully."
}