Mail and Notification Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• config/mail.php
• config/services.php
• config/app.php
• config/logging.php
• database/migrations/0001_01_01_000002_create_jobs_table.php

Introduction

The mail and notification system in this project is designed to provide a flexible, driver-based architecture for delivering messages across various channels. The primary focus of the configuration is to define how the application interacts with local and third-party mail service providers, as well as how it handles background processing for these deliveries.

The configuration scope includes the definition of default mailers, global sender identities, third-party API credentials, and logging channels for mail-related events. By leveraging environment variables, the system allows for seamless transitions between development, testing, and production environments without modifying the core codebase.

Sources: config/mail.php, config/app.php

Mail Architecture and Transports

The mail system utilizes a "transport" based architecture, allowing developers to switch between different delivery methods by changing a single configuration value.

Default Mailer and Global Settings

The system defines a default mailer used for all outgoing messages unless specified otherwise at runtime. Additionally, a global "From" address is established to ensure consistency in outgoing communications.

• Default Mailer: Controlled by the MAIL_MAILER environment variable, defaulting to log for safety in local environments.
• Global Sender: Uses MAIL_FROM_ADDRESS and MAIL_FROM_NAME. The name defaults to the application name defined in the app configuration.

Sources: config/mail.php:17-19, config/mail.php:109-113, config/app.php:16-17

Supported Transports

The application supports a wide range of transports, including SMTP, API-based services, and local utilities.

Transport	Description	Key Configuration Elements
smtp	Standard Mail Transfer Protocol	host, port, username, password, scheme
ses	Amazon Simple Email Service	key, secret, region
mailgun	Mailgun API	domain, secret, endpoint
postmark	Postmark API	token (key)
resend	Resend API	key
sendmail	Local sendmail binary	path (default: /usr/sbin/sendmail)
log	Writes mail to application logs	channel
array	Stores mail in an internal array	N/A

Sources: config/mail.php:33-100, config/services.php:19-35

Advanced Delivery Strategies

Beyond simple transports, the system supports complex delivery patterns:

• Failover: Attempts delivery via a primary mailer (e.g., smtp) and falls back to a secondary (e.g., log) if the first fails, after a 60-second retry window.
• Round Robin: Distributes mail load across multiple mailers (e.g., ses and postmark).

Sources: config/mail.php:87-100

Service Credentials and Third-Party Integration

Third-party service credentials are consolidated within the services configuration file to allow for centralized management of API keys and secrets.

Notification and Logging Channels

Notifications can be routed through various channels. For instance, Slack notifications are configured with specific bot tokens and default channels. Logging for mail events is also configurable, allowing mail content to be redirected to specific log channels when using the log transport.

• Slack: Requires SLACK_BOT_USER_OAUTH_TOKEN and a default channel.
• Log Redirection: The log mailer can specify a dedicated channel (e.g., stack, single, daily) via the MAIL_LOG_CHANNEL environment variable.

Sources: config/services.php:37-42, config/mail.php:79-82, config/logging.php:48-65

Queue and Background Processing

To prevent mail delivery from blocking user requests, the system utilizes a job queue. Mail jobs are dispatched to a database-backed or synchronous queue.

Job Schema for Mail Processing

The jobs table manages the state of mail deliveries and other background tasks.

Field	Type	Description
queue	string	The name of the queue (indexed for performance)
payload	longText	Serialized job data, including mail content and recipients
attempts	tinyInt	Number of times the job has been tried
available_at	unsignedInt	Unix timestamp when the job is ready for processing

Sources: database/migrations/0001_01_01_000002_create_jobs_table.php:13-22

Failed Mail Handling

If a mail delivery fails permanently, it is recorded in the failed_jobs table for manual intervention or debugging.

Conclusion

The Mail and Notification Configuration provides a robust framework for message delivery by separating transport logic from service credentials. By utilizing the mail.php and services.php configuration files, the system supports everything from local logging during development to high-availability failover and round-robin strategies in production, all while ensuring that delivery failures are tracked via a dedicated database schema.

Sources: config/mail.php, config/services.php, database/migrations/0001_01_01_000002_create_jobs_table.php