Documentation

All URLs in this documentation assume your application base URL. Ensure APP_URL is set correctly.

Backend:

• PHP 8.2+
• Composer
• MySQL (or compatible) database
• Redis (recommended for queues)

Frontend:

• Node.js + npm

Optional (Bounce processing):

• PHP IMAP extension (required for processing IMAP/POP3 bounce mailboxes)

There are two ways to install MailPurse:

1. Installer wizard (recommended for most people, especially shared hosting)
2. Manual installation (advanced / for VPS + SSH)

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

cp .env.example .env
php artisan key:generate

php artisan migrate --force
php artisan storage:link
php artisan optimize:clear

docker run --name mailpurse-mysql \
  -e MYSQL_ROOT_PASSWORD=root \
  -e MYSQL_DATABASE=mailpurse \
  -p 3306:3306 \
  -d mysql:8.0

brew install mysql
brew services start mysql

CREATE DATABASE mailpurse;

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=mailpurse
DB_USERNAME=root
DB_PASSWORD=

php artisan optimize:clear
php artisan migrate

require __DIR__.'/../vendor/autoload.php';
$app = require_once __DIR__.'/../bootstrap/app.php';

require __DIR__.'/vendor/autoload.php';
$app = require_once __DIR__.'/bootstrap/app.php';

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

<IfModule mod_rewrite.c>
    <IfModule mod_negotiation.c>
        Options -MultiViews -Indexes
    </IfModule>

    RewriteEngine On

    # Handle Authorization Header
    RewriteCond %{HTTP:Authorization} .
    RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]

    # Redirect Trailing Slashes If Not A Folder...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^(.*)/$ /$1 [L,R=301]

    # Send Requests To Front Controller...
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule ^ index.php [L]
</IfModule>

php artisan key:generate
php artisan migrate --force
php artisan storage:link
php artisan config:cache
php artisan route:cache

ssh your-user@your-server-ip
cd /var/www/mailpurse
composer install --no-dev --optimize-autoloader
npm install
npm run build

MailPurse supports connecting Google accounts to enable Google Sheets and Google Drive features (for example: importing subscribers from spreadsheets, exporting results, and using Drive-backed assets).

Campaign sending and CSV imports run via queues. You must run a queue worker in production.

• php artisan queue:work (simple worker)
• php artisan horizon (if Horizon is configured in your environment)

The app schedules:

• Starting scheduled campaigns every minute (campaigns:start-scheduled)
• Processing bounces every 5 minutes (email:process-bounces --all)

Ensure your server runs Laravel scheduler:

The application supports multiple delivery server types (SMTP and provider APIs). Provider credentials are read from environment variables.

For non-coders, the easiest way to set up billing is from the Admin panel: Admin → Payment Methods. You can enable a provider, choose Live or Sandbox, paste the keys, and choose the default provider.

Monetization features help you sell access to the platform using plans and subscriptions, apply discounts with coupons, and track charges using invoices.

Servers are integrations used to send emails (Delivery Servers) and to receive/parse bounce mailbox messages (Bounce Servers).

If you use provider webhooks for bounces/opens/clicks, configure your provider to call these endpoints:

• POST /webhooks/mailgun (also /webhooks/mailgun/bounce, /webhooks/mailgun/open, /webhooks/mailgun/click)
• POST /webhooks/ses (also /webhooks/ses/bounce, /webhooks/ses/open, /webhooks/ses/click)
• POST /webhooks/sendgrid (also /webhooks/sendgrid/bounce, /webhooks/sendgrid/open, /webhooks/sendgrid/click)

Make sure APP_URL is set correctly so webhook URLs and tracking URLs are generated properly.

Marketing features are available in the Customer area and are centered around a simple flow: build an audience (email list) -> verify addresses (validation) -> send messages (campaigns) -> automate follow-ups (autoresponders).

Email lists are your audiences. Campaigns and autoresponders target a list (and optionally segments, if enabled). Each list contains subscribers with fields like email, name, status, and tags.

Campaigns send a message to subscribers in an email list using a delivery server. You can send immediately or schedule a start time.

Email validation helps improve deliverability by identifying invalid, risky, or disposable addresses before you send. Validation runs in the background and results can be used to clean lists.

Autoresponders are automated sequences triggered by subscriber events (for example: when someone joins a list). They are ideal for welcome sequences, onboarding, and drip campaigns.

• If campaigns do not send: verify a queue worker is running and the campaign has confirmed subscribers.
• If scheduled campaigns do not start: verify cron is running schedule:run.
• If bounce processing does not work: install PHP IMAP and ensure bounce servers are configured and active.
• If webhooks do not arrive: verify your site is publicly accessible and provider settings are correct.