Download the PHP package ryanstubbs/flightmail without Composer

FlightMail

Send email from your Flight PHP app without the headaches.

FlightMail is a small plugin that wraps Symfony Mailer - the most battle-tested mail library in PHP - and makes it feel like part of Flight. One line to install, one fluent chain to send:

Why you'll like it:

• Any provider, one line each. SMTP, Postmark, Sendgrid, Mailgun, Amazon SES, Brevo and friends all work through simple DSN strings.
• Use several providers at once. Transactional mail through Postmark, newsletters through your own SMTP - pick per message.
• Templates if you want them. Render bodies with Twig or Latte. Don't want templates? Just pass strings and install nothing extra.
• Email-safe styling, optionally automatic. Inline CSS into your HTML so Gmail doesn't strip it - one Composer package away.
• Both parts, half the work. Let FlightMail generate the plain-text part from your HTML (Markdown quality), instead of writing it twice.
• Boring in the best way. Lazy connections, clear errors instead of silently swallowed mail, and everything is swappable if you need something custom.

Requirements

Installation

That's it for sending plain-text and HTML emails. Everything else is opt-in - add an engine only if you'll use it:

All of these can be installed side by side; FlightMail picks the right one based on what you configure.

Your first email

Add this to your bootstrap (the same place you define routes):

Using the Flight PHP skeleton instead? Register in app/config/services.php with the instance style:

Both styles expose the same mailer: Flight::mail() and $app->mail() are interchangeable.

Testing locally? If your project runs in DDEV, point the DSN at smtp://127.0.0.1:1025 and read every captured email in Mailpit at http://<project>.ddev.site:8025. Nothing leaves your machine.

Sending email

Plain strings (no template engine needed)

->text() and ->html() take raw strings and need nothing else installed:

Twig templates

Latte templates

Same idea, .latte extension:

HTML + plain text together

Best practice for deliverability - give mail clients both versions:

A few things worth knowing about templates:

• They render lazily, at send time - compose now, render later.
• The engine is chosen by extension: .twig → Twig, .latte → Latte, anything else → your configured default (renderer option).
• An explicit ->html() or ->text() body always wins over a template, so you can set a default template and override it per message.

Styling HTML and generating text parts

Two optional send-time enhancements, both off by default and both powered by libraries you only install if you want them:

Inline CSS into your HTML email

Gmail and most webmail clients strip <style> blocks - inline style="" attributes are the only styling they reliably honor. Writing those by hand is miserable; let Emogrifier do it at send time:

With that on, every HTML body gets its CSS inlined just before sending - whether it came from a template or ->html(). A message like <style>p { color: red; }</style><p>Hi</p> goes out as <p style="color: red;">Hi</p>.

To also inject shared styles into every email (brand colors, resets) without repeating them in each template, pass rules directly or point at a stylesheet file:

Full documents keep their structure; fragments stay fragments. Per-message control:

Generate the text part from your HTML

Best practice is to send an HTML and a plain-text version together, but writing both is tedious. FlightMail can derive the text part from the final HTML automatically - no extra dependency required for basic conversion, since the converter ships with Symfony Mime:

Modes:

• true or 'auto' - Markdown output if league/html-to-markdown is installed, otherwise simple tag-stripping.
• 'markdown' - force Markdown (requires composer require league/html-to-markdown, headings become ==, links [text](url), bold **bold**).
• 'plain' - always strip tags; works with zero extra packages.

Generation runs after rendering and CSS inlining, and only when the message has an HTML body but no text body - an explicit ->text() or ->textTemplate() always wins. Per-message control mirrors inlining:

If you enable a mode whose library isn't installed, you get a clear error telling you exactly which composer require to run - never silent degradation.

Choosing a provider

Providers plug in through DSN strings. Install the bridge package, paste the DSN into dsns, done.

The full list lives in the Symfony Mailer docs - anything documented there works here unchanged.

Multiple providers at once

Name each transport, then choose per message:

Configuration reference

Everything is optional except dsns.

Going further

Everything below is optional. The defaults cover most apps.

Add a custom DSN scheme

Implement Symfony's TransportFactoryInterface and register it - then your own scheme works exactly like a built-in one:

Add a custom template renderer

Anything that turns a template name plus params into a string qualifies:

Run something right before sending

Hooks receive the finished message - after rendering, after defaults, just before the wire:

Events and logging

Hand over a Symfony event dispatcher and/or PSR-3 logger and every transport will use them:

API cheat sheet

Since Message extends Symfony\Component\Mime\Email, every Symfony method you already know - attach(), embed(), priority(), replyTo() - works out of the box.

Troubleshooting

"No mail DSNs configured" You called Flight::mail() before registering the plugin, or the config array didn't include dsns. This error is deliberate - FlightMail refuses to guess where your mail should go rather than silently dropping it.

"Unknown mail template renderer ..." You used a template whose engine isn't installed. Fix with composer require twig/twig or composer require latte/latte, or register a custom renderer named after the extension.

"Unknown mail transport ..." A ->transport('name') (or default_transport) doesn't match any key in dsns. Check spelling - the error lists the configured names.

"CSS inlining requires pelago/emogrifier" You enabled inline_css (or called ->inlineCss()) without installing the library. Fix with composer require pelago/emogrifier.

"Markdown text parts require league/html-to-markdown" You forced text_from_html to 'markdown' (or ->textFromHtml('markdown')) without the library installed. Fix with composer require league/html-to-markdown, or use true/'auto'/'plain', which degrade gracefully.

Mail isn't arriving Point dsns at null://null to confirm the rest of your code works, then switch back to the real DSN. In DDEV, use smtp://127.0.0.1:1025 and inspect messages in Mailpit at port 8025.

Development

This repository is a DDEV project:

Contributing & license

Bug reports and pull requests welcome. MIT licensed - see LICENSE.