Advanced Topics

This page covers advanced features and patterns for power users who need to customize or optimize the mail system. Topics include connection pooling for performance optimization, registering custom transport drivers, and advanced configuration strategies.

For basic transport configuration and usage, see Transport Drivers. For queue integration patterns, see Queue Integration.

---

Connection Pooling Overview

The mail system supports connection pooling to optimize performance when sending high volumes of emails. Connection pooling maintains a pool of reusable transport connections, avoiding the overhead of repeatedly establishing and tearing down SMTP connections or HTTP clients.

Poolable Transports

Not all transports benefit from pooling. The system defines a list of poolable transports in src/MailManager.php71-73:

Transport	Poolable	Rationale
smtp	Yes	TCP connection reuse reduces handshake overhead
sendmail	Yes	Process reuse optimization
mailgun	Yes	HTTP client connection reuse
ses	Yes	AWS SDK client reuse
ses_v2	Yes	AWS SDK client reuse
postmark	Yes	HTTP client connection reuse
resend	Yes	HTTP client connection reuse
failover	Yes	Wraps poolable transports
roundrobin	Yes	Wraps poolable transports
log	No	No connection overhead
array	No	In-memory storage only

Sources: src/MailManager.php71-73

Pool Configuration

Connection pools are configured per-mailer in the mail configuration file. When a transport is poolable and a pool name is provided, the MailManager automatically wraps it in a TransportPoolProxy.

Sources: src/MailManager.php163-168 src/MailManager.php179-185

---

Transport Pool Architecture

This diagram shows how connection pooling is integrated into the mail system. The MailManager checks if a transport is poolable during creation src/MailManager.php124 and wraps it in a TransportPoolProxy src/MailManager.php163-168 if pool configuration is provided. The proxy implements TransportInterface src/TransportPoolProxy.php15 and delegates to pooled connection instances.

Sources: src/MailManager.php71-73 src/MailManager.php124 src/MailManager.php163-168 src/MailManager.php179-185 src/TransportPoolProxy.php1-29

---

TransportPoolProxy Implementation

The TransportPoolProxy class extends the generic PoolProxy from the object pool system and implements both TransportInterface and Stringable:

The implementation is minimal because it delegates to the parent PoolProxy via __call():

Method	Implementation	Purpose
send()	src/TransportPoolProxy.php20-23	Proxies send calls to pooled transport
__toString()	src/TransportPoolProxy.php25-28	Proxies string conversion for debugging
__call()	Inherited from PoolProxy	Generic method delegation to pooled object

Sources: src/TransportPoolProxy.php1-29

---

Custom Transport Registration

The mail system allows registration of custom transport drivers using the extend() method on MailManager. This enables integration with third-party email services or custom delivery mechanisms.

Registering a Custom Transport

Sources: src/MailManager.php516-525 src/MailManager.php162-171

Custom Transport Registration Process

The registration flow involves several key steps in MailManager:

1. Registration - Call extend() with driver name, factory closure, and optional poolable flag src/MailManager.php516
2. Poolable Flag - If $poolable = true, adds driver to poolables array src/MailManager.php518-520
3. Storage - Factory closure stored in customCreators array src/MailManager.php522
4. Resolution - During transport creation, checks customCreators first src/MailManager.php162
5. Pool Wrapping - If poolable and pool name provided, wraps in TransportPoolProxy src/MailManager.php163-169

Sources: src/MailManager.php516-525 src/MailManager.php162-171

---

Custom Transport Example Pattern

A custom transport must implement Symfony's TransportInterface. Here's the expected pattern:

Registration Example

Configuration in config/autoload/mail.php:

Sources: src/MailManager.php516-525

---

Advanced Configuration Patterns

Dynamic Driver Selection

The MailManager supports dynamic driver switching via the setDefaultDriver() method:

Sources: src/MailManager.php492-499

Mailer Purging

For long-running processes, purge cached mailer instances to force reconnection:

This is useful when:

• Configuration changes at runtime
• Connection credentials rotate
• Network conditions require fresh connections

Sources: src/MailManager.php504-509

Configuration URL Parsing

The system supports URL-based configuration for simplified setup:

The ConfigurationUrlParser extracts connection details from the URL src/MailManager.php469-472

Sources: src/MailManager.php468-474

---

Pool Configuration Parameters

Parameter	Type	Description	Default
min_connections	int	Minimum connections kept alive in pool	1
max_connections	int	Maximum concurrent connections	10
wait_timeout	float	Seconds to wait for available connection	3.0
max_idle_time	float	Seconds before idle connection closes	60.0

These parameters are passed to the pool configuration when creating the proxy src/MailManager.php167 src/MailManager.php183

Sources: src/MailManager.php163-168 src/MailManager.php179-185

---

Performance Considerations

When to Use Pooling

Scenario	Recommendation	Rationale
High-volume synchronous sending	Enable pooling	Amortizes connection overhead across many sends
Queue workers sending emails	Enable pooling	Long-running workers benefit from connection reuse
Occasional/sporadic sending	Disable pooling	Overhead of pool management not justified
Development/testing	Disable pooling	Simpler debugging and resource management
Composite transports (failover/roundrobin)	Enable pooling	Each underlying transport benefits from pooling

Pool Sizing Guidelines

• Min connections: Set to 1 for most cases to avoid unnecessary idle connections
• Max connections: Based on concurrent worker count or request throughput
  • Single worker: 2-5 connections
  • Multiple workers: 1-2 connections per worker
  • API server: 5-20 connections depending on load
• Wait timeout: 3-5 seconds for most cases
• Max idle time: 30-60 seconds balances connection reuse with resource cleanup

Sources: src/MailManager.php71-73

---

Extending Poolable Transports

The HasPoolProxy trait provides methods to manage the poolables list:

The addPoolable() method (inherited from HasPoolProxy trait) adds a driver to the poolables array, making it eligible for pool wrapping src/MailManager.php518-520

Sources: src/MailManager.php21 src/MailManager.php46 src/MailManager.php71-73 src/MailManager.php516-525

---

SMTP Transport Configuration

For advanced SMTP configurations, the system supports additional options:

Option	Configuration Key	Purpose
Source IP	source_ip	Bind to specific outbound IP address
Timeout	timeout	Connection timeout in seconds
Scheme	scheme	Force specific scheme (smtp/smtps)

These options are applied to the SocketStream when configuring SMTP transports src/MailManager.php221-236

Sources: src/MailManager.php193-236

---

HTTP Client Configuration

Transports that use HTTP (Mailgun, Postmark, Resend) support custom HTTP client configuration:

The getHttpClient() method extracts and applies these options src/MailManager.php431-442

Sources: src/MailManager.php431-442

---

Composite Transport Configuration

Failover and Round Robin transports require special configuration patterns:

Failover Transport

Tries transports in sequence until one succeeds:

Sources: src/MailManager.php355-375

Round Robin Transport

Distributes load across transports:

Both composite transports:

• Reference other mailer configurations by name src/MailManager.php359 src/MailManager.php384
• Resolve each referenced mailer's transport src/MailManager.php369-371 src/MailManager.php394-396
• Support nested configuration with pooled underlying transports

Sources: src/MailManager.php355-400