SMTP Configuration for Laravel on Zerops

Important Security Note

By default, SMTP ports are blocked by Zerops firewall for security reasons. To use external SMTP services, please contact Zerops support to have the necessary ports opened for your project. Include in your request:

• Detailed explanation of your use case
• Specific ports and protocols needed
• Project ID and Organization ID from your Zerops Dashboard

Production Configuration

Laravel Mail Configuration

Laravel comes with a default mail configuration in config/mail.php. You typically don't need to modify this file as all settings can be controlled through environment variables.

The default configuration supports multiple mailer types and reads all sensitive information from your environment. In this example

config/mail.php

return [
    'default' => env('MAIL_MAILER', 'smtp'),

    'mailers' => [
        'smtp' => [
            'transport' => 'smtp',
            'url' => env('MAIL_URL'),
            'host' => env('MAIL_HOST', '127.0.0.1'),
            'port' => env('MAIL_PORT', 587),
            'encryption' => env('MAIL_ENCRYPTION', 'tls'),
            'username' => env('MAIL_USERNAME'),
            'password' => env('MAIL_PASSWORD'),
            'timeout' => null,
            'local_domain' => env('MAIL_EHLO_DOMAIN'),
        ],

        'ses' => [
            'transport' => 'ses',
        ],

        'postmark' => [
            'transport' => 'postmark',
        ],

        'failover' => [
            'transport' => 'failover',
            'mailers' => [
                'smtp',
                'log',
            ],
        ],
    ],

    'from' => [
        'address' => env('MAIL_FROM_ADDRESS', 'hello@example.com'),
        'name' => env('MAIL_FROM_NAME', 'Example'),
    ],
];

Available Mail Transports

Laravel supports multiple mail transport options:

• 'smtp' - Standard SMTP server
• 'sendmail' - Server's sendmail
• 'mailgun' - Mailgun API
• 'ses' - Amazon SES
• 'postmark' - Postmark
• 'log' - Log messages for testing
• 'array' - Store in array for testing
• 'failover' - Fallback to next mailer if one fails
• 'roundrobin' - Rotate between multiple mailers

Environment Configuration

Configure your Laravel service with the required mail variables. The following example shows SMTP configuration, but most settings are common across different mail transports:

zerops.yml

zerops:
  - setup: app
    run:
      envVariables:
        MAIL_MAILER: smtp
        MAIL_FROM_ADDRESS: noreply@yourdomain.com
        MAIL_FROM_NAME: YourApp
        MAIL_HOST: your-smtp-host
        MAIL_PORT: 587
        MAIL_USERNAME: your-username
        MAIL_PASSWORD: your-password
        MAIL_ENCRYPTION: tls

If using other mail transports, you might need additional environment variables. Refer to Laravel's Mail documentation for transport-specific configuration.

Implementing Email Functionality

Creating Mail Classes

Generate a new mail class using Artisan:

php artisan make:mail WelcomeEmail

app/Mail/WelcomeEmail.php

<?php

namespace App\Mail;

use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class WelcomeEmail extends Mailable
{
    use SerializesModels;

    public function __construct(
        public $user
    ) {}

    public function build()
    {
        return $this->view('emails.welcome')
                    ->subject('Welcome to ' . config('app.name'));
    }
}

Email Template

Create a blade template for your email content:

resources/views/emails/welcome.blade.php

<x-mail::message>
# Welcome {{ $user->name }}

Thanks for joining our application!

<x-mail::button :url="config('app.url')">
Visit Dashboard
</x-mail::button>

Thanks,<br>
{{ config('app.name') }}
</x-mail::message>

Sending Emails

You can send emails either immediately or using a queue:

use Illuminate\Support\Facades\Mail;
use App\Mail\WelcomeEmail;

// Send immediately
Mail::to($user->email)->send(new WelcomeEmail($user));

// Send using queue
Mail::to($user->email)->queue(new WelcomeEmail($user));

Queue Configuration

For production environments, it's recommended to use a queue system for sending emails to prevent request timeouts and improve application performance. Zerops provides Valkey, an open-source Redis-compatible service that's perfect for handling email queues.

First, add the Valkey service to your project:

services:
  - hostname: redis
    type: valkey@7.2
    mode: NON_HA  # use HA for high availability in production

Configure your Laravel service to use Redis for queues:

zerops.yml

zerops:
  - setup: app
    run:
      envVariables:
        # Queue Configuration
        QUEUE_CONNECTION: redis
        REDIS_HOST: redis
        REDIS_PORT: 6379
        REDIS_CLIENT: phpredis # PHP Redis client for better performance

        # Mail Configuration
        MAIL_MAILER: smtp
        MAIL_HOST: your-smtp-host.com
        MAIL_PORT: 587
        MAIL_USERNAME: your-username
        MAIL_PASSWORD: your-password
        MAIL_ENCRYPTION: tls
        MAIL_FROM_ADDRESS: noreply@yourdomain.com
        MAIL_FROM_NAME: YourApp

You can customize the queue behavior in your config/queue.php:

config/queue.php

phpCopy'default' => env('QUEUE_CONNECTION', 'redis'),

'connections' => [
    'redis' => [
        'driver' => 'redis',
        'connection' => 'default',
        'queue' => 'default',
        'retry_after' => 90,     // Retry failed jobs after 90 seconds
        'block_for' => null,     // Don't block when no jobs available
    ],
],

Development Environment

For local development and testing, Zerops provides a Mailpit service that allows you to catch and inspect all outgoing emails.

Setting up Mailpit

Add this to your project import configuration or import the service separately:

services:
  - hostname: mailpit
    type: go@1
    buildFromGit: https://github.com/zeropsio/recipe-mailpit
    enableSubdomainAccess: true

See Mailpit recipe repo for reference.

Configure your Laravel service to use Mailpit for development:

zerops:
  - setup: app
    run:
      envVariables:
        MAIL_MAILER: smtp
        MAIL_HOST: mailpit
        MAIL_PORT: 1025
        MAIL_FROM_ADDRESS: hello@example.com
        MAIL_FROM_NAME: ZeropsLaravel

Tip

Enable enableSubdomainAccess to access the Mailpit web interface where you can view all emails during development.

Best Practices

• Use queue for sending emails in production to prevent request timeouts
• Configure proper timeouts for SMTP connections
• Use environment variables for all mail settings
• Implement proper error handling for failed email deliveries
• Test email templates across different email clients
• Monitor email delivery rates and bounce rates
• Use Mailpit in development to catch and debug emails