Download the PHP package myth/postal without Composer

Postal

A modern, driver-based email library for CodeIgniter 4.

Postal replaces CodeIgniter 4's monolithic Email class with a clean transport-driver architecture: compose a message once and send it through SMTP, Sendmail, PHP mail(), Amazon SES, a log, or a failover chain — without changing your application code. It keeps the familiar CI4 email API working for a painless migration, and it's fully testable without ever sending a real message.

Status: Public beta (0.x). The API is stable and ready for use; breaking changes before 1.0 will be rare and called out clearly in the changelog.

Documentation

lonnieezell.github.io/postal — full reference, guides, and configuration options for every transport.

Why Postal?

• Driver-based transports — swap how mail is delivered via config, not code.
• Drop-in friendly — existing service('email') calls keep working through a compatibility adapter.
• Amazon SES — deliver through SesV2 with SigV4 signing; no SMTP relay required.
• DKIM signing — sign outbound messages at the library level with a one-line config addition, no application code changes.
• Failover chain — wrap any number of mailers in a priority-ordered fallback so a provider outage doesn't drop mail.
• Suppression lists & unsubscribe — bind your own suppression list to silently filter recipients before send, and auto-inject List-Unsubscribe headers.
• Inline image embedding — local paths and data: URIs in HTML are automatically rewritten to cid: attachments.
• Zero required dependencies — PHP standard extensions only. No database, no queue, no view renderer needed to send mail.
• Built for testing — a fake transport and expressive assertions let you verify mail in PHPUnit without touching the network.
• Mailable classes — reusable, class-based emails with browser preview support in development.

Requirements

• PHP 8.2+
• CodeIgniter 4.7+
• Extensions: ext-openssl, ext-mbstring
• ext-curl + aws/aws-sdk-php for the Amazon SES transport (optional)

Installation

CodeIgniter auto-discovers the package — no manual wiring required.

Quick Start

Compose and send

send() returns a SendResult carrying success, the provider messageId, any error, and the raw provider response.

Send through a named transport

Mailable classes

For reusable, testable messages, extend Mailable:

Scaffold one with:

Backward-compatible API

Existing CodeIgniter email code keeps working unchanged via service('email'):

Transports

Register your own transport by adding it to the $transports map in Config\Mailer.

Configuration

Run php spark publish to write app/Config/Mailer.php into your application — a Config\Mailer extending the package's config, which Postal resolves in preference to its own default. Transports are defined there as named mailers, with a $default chosen per environment:

See the full documentation for every transport's configuration reference, DKIM setup, SES credentials, and more.

Events

Postal fires events through CodeIgniter's Events system at each stage of the send pipeline:

Returning false from an email.sending listener cancels the send. Event emission can be disabled with Config\Mailer::$fireEvents = false.

Testing

Swap in the fake transport and assert against what would have been sent — no network, no real mail:

Contributing

Contributions are welcome. The project ships with a full toolchain (PHPUnit, php-cs-fixer, PHPStan, Rector) runnable locally or in Docker:

Docker equivalents are available for every command by prefixing docker: (e.g. composer docker:test), and docker compose up starts a dev container with all required extensions. A pre-commit hook (installed on composer install) lints and auto-formats staged PHP files.

Please ensure composer ci passes and new behavior is covered by tests before submitting a pull request.

License

Released under the MIT License.