Installation

Prefer letting your AI assistant do this? Copy the prompt from Install with an AI assistant.

1. Require and install

composer require cboxdk/laravel-postal
php artisan postal:install
php artisan migrate

The service provider is auto-discovered. postal:install publishes config/postal.php and prints this same checklist; migrate creates the postal_messages and postal_message_events tables.

The database is fully optional: disable both postal.webhooks.store and postal.inbound.store and the package registers no migrations at all — php artisan migrate creates nothing, and no code path touches the database. You keep the typed events; idempotency then falls to your listeners (dedupe on uuid()).

To copy the migrations into your app for editing:

php artisan postal:install --migrations

2. Configure servers

One entry per Postal mail server in config/postal.php — each mail server has its own API key (Postal admin → your mail server → Credentials):

'default' => env('POSTAL_SERVER', 'default'),

'servers' => [
    'default' => [
        'url' => env('POSTAL_URL'),
        'key' => env('POSTAL_KEY'),
    ],
],

POSTAL_URL=https://postal.example.com
POSTAL_KEY=your-server-api-key

See Multi-server for one-server-per-product setups, Connection types for smtp-api/smtp submission, and Dynamic servers for database-driven provisioning.

3. Verify

php artisan postal:ping     # connectivity + key validity per server
php artisan postal:doctor   # everything: config, keys, routes, tables, mailer

postal:doctor exits non-zero on failures, so it doubles as a deployment gate. From here:

• Webhook setup — delivery/bounce/open/click events.
• Inbound mail — receive email into the app.
• Quickstart — send your first message.