Sending from Laravel

A Laravel application can send through us in two ways. Pick the one that fits the code you already have.

• Over SMTP, if the application already sends with Mail::to() and Mailables. Nothing in your code changes: you point Laravel's own mailer at us in .env.
• Through the API, if you want what SMTP cannot give you: a message id back straight away, scheduling, batches, saved templates, and a lookup for every message.

Both send from the business's own verified domain, count toward the same monthly allowance, and show up on the account's Sent page. Plenty of applications use both: SMTP for the framework's own mail, such as password resets, and the API for receipts they want to track.

Before you start

The from address has to be on a sending domain the account has verified. If the business has not added one yet, they do it under Sending domains, and the dashboard lists the DNS records and checks them. See the DNS a sending domain needs.

Over SMTP

Open the domain under Sending domains and choose to connect an app. Copy the host, username and password from that page into your .env:

MAIL_MAILER=smtp
MAIL_SCHEME=smtp
MAIL_HOST=YOUR_SMTP_HOST
MAIL_PORT=587
MAIL_USERNAME=YOUR_SMTP_USERNAME
MAIL_PASSWORD=YOUR_SMTP_PASSWORD
MAIL_FROM_ADDRESS=hello@yourdomain.com
MAIL_FROM_NAME="${APP_NAME}"

Port 587 with MAIL_SCHEME=smtp connects in plain text and upgrades to an encrypted connection before anything is sent, which is what our service expects. Do not set MAIL_SCHEME=smtps: that expects encryption from the first byte and the connection will hang until it times out.

Older applications may still have MAIL_ENCRYPTION=tls in their .env and an encryption key in config/mail.php. Recent versions of Laravel ignore both, so leaving them does no harm, but MAIL_SCHEME is the setting that counts.

Then send the way you already do, with Mail::to() and your Mailables. Run php artisan config:clear after changing .env on a server that caches its config, or the old mailer keeps being used.

The credentials send as any address on the domain they were issued for and nothing else. MAIL_FROM_ADDRESS, and any from() in a Mailable, has to be on that domain.

Through the API

Get a key from Connected apps with the email:send ability. Keep it in .env and read it through a config file rather than calling env() in your code, so it still works once the config is cached:

REGGIO_API_KEY=rgo_your_key_here

return [

    'reggio' => [
        'key' => env('REGGIO_API_KEY'),
    ],

];

Sending is then one call with Laravel's HTTP client:

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.reggio.key'))
    ->acceptJson()
    ->post('https://reggiodigital.com/api/v1/emails', [
        'from' => 'hello@yourdomain.com',
        'to' => [
            'success@simulator.amazonses.com',
        ],
        'subject' => 'Your receipt',
        'html' => '<p>Thanks for your order.</p>',
        'text' => 'Thanks for your order.',
        'tags' => [
            'kind' => 'receipt',
            'order' => '1042',
        ],
    ]);

if ($response->failed()) {
    throw new RuntimeException($response->json('error.message'));
}

$body = $response->json();

A 202 with an id means we accepted it. Store the id if you want to look the message up later or match it against a webhook. Anything else carries an error whose type says what to do next.

Sending from a queued job keeps a slow network call out of the request. If a job can be retried, send an Idempotency-Key so a retry after a timeout never sends the message twice:

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.reggio.key'))
    ->acceptJson()
    ->withHeaders([
        'Idempotency-Key' => 'receipt-1042',
    ])
    ->post('https://reggiodigital.com/api/v1/emails', [
        'from' => 'hello@yourdomain.com',
        'to' => [
            'success@simulator.amazonses.com',
        ],
        'subject' => 'Your receipt',
        'html' => '<p>Thanks for your order.</p>',
        'text' => 'Thanks for your order.',
        'tags' => [
            'kind' => 'receipt',
            'order' => '1042',
        ],
    ]);

if ($response->failed()) {
    throw new RuntimeException($response->json('error.message'));
}

$body = $response->json();

Testing without emailing anyone

Send to the test addresses. They work over SMTP and the API alike, produce a real delivery, bounce or complaint, and never reach an inbox.