README

Let your Laravel app receive emails.

Installation

composer require notifiablehq/receive-email

Usage

1. Publish Config and Migrations

Publish the configuration and migration files:

php artisan vendor:publish --provider="Notifiable\\ReceiveEmail\\ReceiveEmailServiceProvider" --tag=receive-email

Then run the migrations:

php artisan migrate

2. Listen for Incoming Emails

Whenever an email is received, the package will dispatch the Notifiable\\ReceiveEmail\\Events\\EmailReceived event. On Laravel 11 and above, you should use a listener class:

Create the Listener

Generate a listener class:

php artisan make:listener HandleIncomingEmail

Then implement the handle method:

namespace App\Listeners;

use Notifiable\ReceiveEmail\Events\EmailReceived;

class HandleIncomingEmail
{
    public function handle(EmailReceived $event): void
    {
        $email = $event->email;
        
        \Log::info('Received email with subject: ' . $email->parsedMail()->subject());
    }
}

3. Accessing Email Data

The Email model gives you access to sender, recipients, subject, and body through the parsedMail method. Example:

/** @var \Notifiable\ReceiveEmail\Contracts\ParsedMailContract $mail */
$mail = $email->parsedMail();

$subject = $mail->subject();
$textBody = $mail->text();
$htmlBody = $mail->html();
$recipients = $mail->recipients();

Forge Deployment

1. Add this to your recipes, you can name it Install Mailparse. Make sure the user is root.

apt-get update
apt-get install -y php-cli php-mailparse

1. If you already have an existing server, run this recipe on that server. Otherwise, create a new server and make sure to select this recipe as a Post-Provision Recipe. You'll have to show Advance Settings to select this.

2. Once you have the server ready, open up Port 25, add your site, and deploy your Laravel app.

3. Activate an SSL certificate for your site in Forge (Sites > your site > SSL). Forge uses Let's Encrypt and places certs at:

   • Certificate: /etc/nginx/ssl/your-application-domain.com/server.crt
   • Private key: /etc/nginx/ssl/your-application-domain.com/server.key

4. SSH into your Forge server and go to your site directory. Then run the setup command as a super user:

sudo php artisan notifiable:setup-postfix domain-that-receives-email.com \
    --user=forge \
    --tls-cert=/etc/nginx/ssl/your-application-domain.com/server.crt \
    --tls-key=/etc/nginx/ssl/your-application-domain.com/server.key \
    --with-spf

Important: Always pass --user=forge (or your deploy user) when running with sudo. Without it, the pipe transport will run as root.

Available options:

1. Add the following DNS records to your domain:

   Type	Host	Value
   A	your-application-domain.com	your.forge.ip.address

   Type	Host	Value	Priority
   MX	domain-that-receives-email.com	your-application-domain.com	10

   Type	Host	Value
   TXT	domain-that-receives-email.com	v=spf1 mx -all

   The SPF TXT record tells other mail servers that only your MX host is authorized to send mail for this domain. Even though this is a receive-only server, publishing an SPF record prevents others from spoofing your domain.

Configuration

After publishing the config file, you can tune the following settings in config/receive_email.php:

To apply changes to message-size-limit or pipe-concurrency, re-run the setup command.

Research References

• How Postfix receives email
• Installing and configuring Postfix on Ubuntu

Credits

The solutions in this package are inspired by the following projects:

• Mailcare
• Laravel Mailbox