Skip to content

Installation

Requirements

  • PHP 8.2+
  • CodeIgniter 4.7+
  • Extensions: ext-openssl, ext-mbstring (and ext-curl for the HTTP API transports)

Install via Composer

composer require myth/postal

CodeIgniter auto-discovers the package through Composer — no manual registration is required.

Configuration

Transports are defined as named mailers in Config\Mailer. $default names the mailer used when you don't pick one. Out of the box it is null, which discards every message, so nothing is sent until you choose a transport:

<?php

public string $default = 'log';

public array $mailers = [
    'smtp' => [
        'transport'  => 'smtp',
        'host'       => 'localhost',
        'port'       => 587,
        'encryption' => 'tls',
    ],
    'log'  => ['transport' => 'log'],
    'null' => ['transport' => 'null'],
];

To use a different mailer in each environment, override $default from that environment's .env file:

mailer.default = smtp

To override the defaults in your application, publish the config file:

php spark publish

That writes app/Config/Mailer.php — a Config\Mailer class extending the package's Myth\Postal\Config\Mailer. Redeclare only the properties you want to change; everything else is inherited. Postal resolves the application's copy in preference to its own, so the settings you put there are the ones that take effect.

Publishing never overwrites an existing app/Config/Mailer.php, so it is safe to re-run after upgrading the package.

The same php spark publish run also copies the default email Layout and Mail Components — app/Views/mail/layouts/default.php and app/Views/mail/components/{button,panel}.php — so you can restyle them to match your brand. As with the config file, publishing never overwrites a copy you've already customized. See Markdown Mailables for what those files do.

Every property and transport setting is listed in the Config\Mailer reference.

Verify the install

Once $default names a real mailer, send a test message through it:

php spark email:test you@example.com

The command runs the full send pipeline and prints the result (provider message ID, or the error if it failed). With the package default, null, it reports success without sending anything, so set $default first.