Symfony Postmark Mailer

Symfony Postmark Mailer plugs Postmark into Symfony’s Mailer component by registering postmark+smtp and postmark+api DSN schemes, so applications send transactional email through Postmark by setting a MAILER_DSN environment variable rather than integrating Postmark’s API directly.

It also ships a Webhook request parser, a RemoteEvent payload converter, and a dedicated PostmarkDeliveryEvent for surfacing Postmark-specific bounce error codes and headers, letting Symfony apps handle Postmark’s delivery/bounce callbacks through the framework’s standard event system.

What You Get

• A PostmarkTransportFactory supporting postmark+smtp and postmark+api DSN schemes
• Two transport implementations (PostmarkApiTransport, PostmarkSmtpTransport) selected automatically from the DSN scheme
• A MessageStreamHeader helper for setting Postmark’s message-stream header on outgoing mail
• A PostmarkRequestParser that verifies and parses incoming Postmark webhook requests into Symfony RemoteEvent objects
• A PostmarkDeliveryEvent exposing Postmark-specific bounce error codes and message headers for fine-grained failure handling

Common Use Cases

• Sending transactional email from a Symfony app through Postmark by setting MAILER_DSN=postmark+api://KEY@default
• Routing mail through a specific Postmark message stream (e.g. broadcast vs. transactional) via MessageStreamHeader
• Receiving and reacting to Postmark bounce/delivery webhooks via Symfony’s Webhook and RemoteEvent components
• Inspecting Postmark’s numeric bounce error codes to distinguish hard bounces from spam complaints
• Building a multi-provider mailer setup where Postmark is one of several interchangeable Symfony Mailer transports

Under The Hood

Architecture - PostmarkTransportFactory::create() reads the DSN scheme to instantiate PostmarkApiTransport or PostmarkSmtpTransport, both applying MessageStreamHeader to route mail into Postmark’s stream model; a parallel Webhook/RemoteEvent/Event set (PostmarkRequestParser, PostmarkPayloadConverter, PostmarkDeliveryEvent) handles inbound callbacks independently of the send path, converting Postmark’s webhook JSON into Symfony’s shared RemoteEvent model plus a Postmark-specific delivery event carrying the raw error code. Tech Stack - PHP 8.4+, depending on symfony/mailer and psr/event-dispatcher at runtime, with symfony/http-client and symfony/webhook as dev/optional dependencies for the API transport and webhook parsing; distributed as a Composer package split from the symfony/symfony monorepo. Code Quality - A Tests/ directory with PHPUnit configuration covers the transport factory and Postmark-specific transports; as a first-party Symfony bridge it follows the framework’s strict typing, coding standards, and license headers throughout. API Design - Configuration is DSN-string driven (postmark+api://KEY@default), consistent with every other Symfony Mailer bridge, so switching from another provider to Postmark is a one-line environment variable change rather than a code change; the dedicated PostmarkDeliveryEvent gives access to provider-specific error codes without leaking Postmark’s SDK types into application code.