Skip to main content

​
Prerequisites

To get the most out of this guide, you will need to:

​
1. Install

First, install Emailr for Laravel using the Composer package manager:
Composer
composer require emailr/emailr-laravel

​
2. Configuration

​
API key

Next, you should configure your Emailr API key in your application’s .env file:
.env
EMAILR_API_KEY=em_xxxxxxxxx

​
Mail driver

To use Emailr as your mail driver, first create a new mailer definition, in the mailers array within your application’s config/mail.php configuration file:
mail.php
'emailr' => [
    'transport' => 'emailr',
],
Next, update your application’s .env file to use the Emailr mail driver:
.env
MAIL_MAILER=emailr
MAIL_FROM_ADDRESS=onboarding@emailr.dev
MAIL_FROM_NAME=Acme

​
3. Send an email

Emailr for Laravel provides two convenient ways to send emails, using Laravel’s email service or the Emailr API facade.

​
Using the Mail Facade

OrderShipmentController.php
<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Mail\OrderShipped;
use App\Models\Order;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;

class OrderShipmentController extends Controller
{
    /**
     * Ship the given order.
     */
    public function store(Request $request): RedirectResponse
    {
        $order = Order::findOrFail($request->order_id);

        // Ship the order...

        Mail::to($request->user())->send(new OrderShipped($order));

        return redirect('/orders');
    }
}

​
Using the Emailr Facade

OrderShipmentController.php
<?php

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;
use App\Mail\OrderShipped;
use App\Models\Order;
use Illuminate\Http\RedirectResponse;
use Illuminate\Http\Request;
use Emailr\Laravel\Facades\Emailr;

class OrderShipmentController extends Controller
{
    /**
     * Ship the given order.
     */
    public function store(Request $request): RedirectResponse
    {
        $order = Order::findOrFail($request->order_id);

        // Ship the order...

        Emailr::emails()->send([
            'from' => 'Acme <onboarding@emailr.dev>',
            'to' => [$request->user()->email],
            'subject' => 'hello world',
            'html' => (new OrderShipped($order))->render(),
        ])

        return redirect('/orders');
    }
}

​
4. Receiving webhook requests

By default, Emailr for Laravel includes a webhook controller to respond to the /emailr/webhook URL path. The controller will dispatch a Laravel event that corresponds to a Emailr event. For example, an email.delivered event type will send an EmailDelivered Laravel event.

​
Register the webhook endpoint

Register your publicly accessible HTTPS URL in the Emailr dashboard.
For development, you can create a tunnel to your localhost server using a tool like ngrok or VS Code Port Forwarding. These tools serve your local dev environment at a public URL you can use to test your local webhook endpoint.Example: https://example123.ngrok.io/api/webhook
Screenshot placeholder

​
CSRF protection

Webhook requests from Emailr need to bypass Laravel’s CSRF protection. Be sure to list the URI as an exception in your application’s App\Http\Middleware\VerifyCsrfToken middleware or list the route outside of the web middleware group: 
protected $except = [
    'emailr/*',
];

​
Verifying webhook signatures

To enable webhook verification, ensure that the EMAILR_WEBHOOK_SECRET environment variable is set in your application’s .env file. The Signing secret can be retrieved from your Emailr dashboard.

​
5. Try it yourself

Laravel Example

See the full source code.