Laravel

Send email in Laravel without SMTP

Laravel's Mail facade sends over SMTP or a provider's driver, and Warmerly's transactional API is REST only, so the Mail facade cannot use it today. The Http facade can: a small service class makes the request, and you call it from a controller, a notification or a queued job.

Get a free API key API reference

Before you write any code

Four steps, the same in every framework. Warmerly is REST only today: no SMTP relay, webhooks, templates or attachments yet.

Step 1: Add and verify a sending domain
In Warmerly open Transactional email, add the domain you send from (for example mail.example.com), publish the DNS records it shows at your DNS provider, then verify. Use a domain or subdomain you do not use for cold outreach.
Step 2: Create a Sending API key
Under Transactional email, API keys, create a key with the Sending permission, optionally limited to that domain. It starts with wm_tx_ and is shown once, so copy it straight into your secrets store.
Step 3: Store the key as WARMERLY_TX_KEY
Add WARMERLY_TX_KEY to your .env file and read it through config/services.php, so config caching keeps working.
Step 4: Add the code below and send a test
A successful request answers 202 with the email's id and a status of sent (or queued, which Warmerly retries for up to 24 hours). The free plan is 5,000 emails a month with no card.

The code

Copy these into your project. The request is the same one the API reference documents; nothing is hidden behind a package.

app/Services/Warmerly.php

<?php
// app/Services/Warmerly.php
namespace App\Services;

use Illuminate\Support\Facades\Http;
use RuntimeException;

class Warmerly
{
    private const ENDPOINT = 'https://app.warmerly.com/api/v1/transactional/emails';

    /**
     * Send one email. $idempotencyKey identifies the MESSAGE (for example "reset-{$user->id}-{$tokenId}"),
     * so retrying the same message never sends it twice.
     *
     * @param  string|array<int, string>  $to
     * @return array{id: string, status: string, duplicate: bool}
     */
    public static function send(
        string $from,
        string|array $to,
        string $subject,
        ?string $html,
        ?string $text,
        string $idempotencyKey,
    ): array {
        $response = Http::withToken(config('services.warmerly.key'))
            ->withHeaders(['Idempotency-Key' => $idempotencyKey])
            ->timeout(15)
            ->post(self::ENDPOINT, array_filter([
                'from' => $from,
                'to' => $to,
                'subject' => $subject,
                'html' => $html,
                'text' => $text,
            ], fn ($value) => $value !== null));

        if ($response->status() !== 202) {
            throw new RuntimeException(sprintf('Warmerly %d %s', $response->status(), $response->json('error.code', 'unknown')));
        }

        return $response->json(); // ['id' => ..., 'status' => 'sent'|'queued', 'duplicate' => false]
    }
}

config/services.php

// config/services.php
'warmerly' => [
    'key' => env('WARMERLY_TX_KEY'),
],

Using it

A controller, notification or job

use App\Services\Warmerly;

Warmerly::send(
    from: 'Acme <noreply@mail.example.com>',
    to: $user->email,
    subject: 'Reset your password',
    html: '<p>Click <a href="'.e($url).'">here</a> to reset your password.</p>',
    text: "Reset your password: {$url}",
    idempotencyKey: "reset-{$user->id}-{$tokenId}",
);

What to know about Laravel

Queue it: Make the call inside a job that implements ShouldQueue so a slow request never delays your HTTP response, and set the idempotency key from the event so a job retry cannot send twice.
The Mail facade is not used: That also means Mailables, markdown mail and mail previews do not apply to this path. Render the HTML yourself, for example with a Blade view, and pass it as the html argument.
Escape what you put in HTML: The example wraps the URL in e(). Do the same for any value that came from a user.

When the API does not send

Every refusal has a code in the response body, at error.code. These are the ones to handle, and whether to retry.

Error codes the send endpoint can return, what they mean and whether to retry
Status	Code	Meaning	Retry?
400	bad_request	Invalid body, or the From address is not on a verified sending domain.	No: fix the request
403	forbidden	The key is limited to a different sending domain.	No
403	sending_paused	Sending is paused for the workspace (bounce or complaint rate, or under review).	No: contact support
422	content_rejected	The message was refused by abuse screening.	No, not unchanged
429	rate_limited	The hourly or daily sending limit was reached.	Later
429	quota_exceeded	The plan's monthly allowance, plus the free buffer, is used up.	No: upgrade or wait
502	send_failed	It could not be sent or queued. details.interrupted says whether it may have been delivered.	Same key if interrupted is false
503	service_unavailable	Transactional sending is not enabled for the workspace yet.	No

Full details, including the sending limits, are in the transactional email API reference.

Laravel questions

Can I use Laravel's Mail facade with Warmerly?

Not today. The Mail facade needs an SMTP server or a supported API driver, and Warmerly's transactional API is REST only. Call the API with the Http facade, as above.

Does this work with Laravel Octane, Vapor or queues?

Yes. It is a plain HTTP request with a timeout, with no state, so it works anywhere the Http facade does. Use a queued job for anything you do not want in the request cycle.

Is there a Laravel package or SDK for Warmerly?

No. Warmerly's transactional API is one HTTP request, so there is nothing to install. The code on this page is the whole integration.

Can I send attachments?

Not yet. The send request takes from, to, cc, bcc, reply_to, subject, html or text, headers and tags. Attachments, SMTP relay, delivery webhooks and templates are not available today.

What if sending is throttled or the mail server cannot be reached?

If nothing was handed over, the email is queued rather than dropped. The request still answers 202 with a status of queued, and Warmerly retries it after 1, 5, 15 and 60 minutes, then hourly, for up to 24 hours.

Send your first Laravel email today

Create a free account, verify a sending domain and send a test. 5,000 emails a month free, no card.

Start sending free Continue with Google API docs

Or book a free 15-minute setup call →

Warming up

Send email in Laravel without SMTP

Before you write any code

Four steps, the same in every framework. Warmerly is REST only today: no SMTP relay, webhooks, templates or attachments yet.

Step 1: Add and verify a sending domain

In Warmerly open Transactional email, add the domain you send from (for example mail.example.com), publish the DNS records it shows at your DNS provider, then verify. Use a domain or subdomain you do not use for cold outreach.

Step 2: Create a Sending API key

Under Transactional email, API keys, create a key with the Sending permission, optionally limited to that domain. It starts with wm_tx_ and is shown once, so copy it straight into your secrets store.

Step 3: Store the key as WARMERLY_TX_KEY

Add WARMERLY_TX_KEY to your .env file and read it through config/services.php, so config caching keeps working.

Step 4: Add the code below and send a test

A successful request answers 202 with the email's id and a status of sent (or queued, which Warmerly retries for up to 24 hours). The free plan is 5,000 emails a month with no card.

The code

Copy these into your project. The request is the same one the API reference documents; nothing is hidden behind a package.

app/Services/Warmerly.php

<?php
// app/Services/Warmerly.php
namespace App\Services;

use Illuminate\Support\Facades\Http;
use RuntimeException;

class Warmerly
{
    private const ENDPOINT = 'https://app.warmerly.com/api/v1/transactional/emails';

    /**
     * Send one email. $idempotencyKey identifies the MESSAGE (for example "reset-{$user->id}-{$tokenId}"),
     * so retrying the same message never sends it twice.
     *
     * @param  string|array<int, string>  $to
     * @return array{id: string, status: string, duplicate: bool}
     */
    public static function send(
        string $from,
        string|array $to,
        string $subject,
        ?string $html,
        ?string $text,
        string $idempotencyKey,
    ): array {
        $response = Http::withToken(config('services.warmerly.key'))
            ->withHeaders(['Idempotency-Key' => $idempotencyKey])
            ->timeout(15)
            ->post(self::ENDPOINT, array_filter([
                'from' => $from,
                'to' => $to,
                'subject' => $subject,
                'html' => $html,
                'text' => $text,
            ], fn ($value) => $value !== null));

        if ($response->status() !== 202) {
            throw new RuntimeException(sprintf('Warmerly %d %s', $response->status(), $response->json('error.code', 'unknown')));
        }

        return $response->json(); // ['id' => ..., 'status' => 'sent'|'queued', 'duplicate' => false]
    }
}

config/services.php

// config/services.php
'warmerly' => [
    'key' => env('WARMERLY_TX_KEY'),
],

Using it

A controller, notification or job

use App\Services\Warmerly;

Warmerly::send(
    from: 'Acme <noreply@mail.example.com>',
    to: $user->email,
    subject: 'Reset your password',
    html: '<p>Click <a href="'.e($url).'">here</a> to reset your password.</p>',
    text: "Reset your password: {$url}",
    idempotencyKey: "reset-{$user->id}-{$tokenId}",
);

What to know about Laravel

Queue it

Make the call inside a job that implements ShouldQueue so a slow request never delays your HTTP response, and set the idempotency key from the event so a job retry cannot send twice.

The Mail facade is not used

That also means Mailables, markdown mail and mail previews do not apply to this path. Render the HTML yourself, for example with a Blade view, and pass it as the html argument.

Escape what you put in HTML

The example wraps the URL in e(). Do the same for any value that came from a user.

When the API does not send

Every refusal has a code in the response body, at error.code. These are the ones to handle, and whether to retry.

Error codes the send endpoint can return, what they mean and whether to retry
Status	Code	Meaning	Retry?
400	bad_request	Invalid body, or the From address is not on a verified sending domain.	No: fix the request
403	forbidden	The key is limited to a different sending domain.	No
403	sending_paused	Sending is paused for the workspace (bounce or complaint rate, or under review).	No: contact support
422	content_rejected	The message was refused by abuse screening.	No, not unchanged
429	rate_limited	The hourly or daily sending limit was reached.	Later
429	quota_exceeded	The plan's monthly allowance, plus the free buffer, is used up.	No: upgrade or wait
502	send_failed	It could not be sent or queued. details.interrupted says whether it may have been delivered.	Same key if interrupted is false
503	service_unavailable	Transactional sending is not enabled for the workspace yet.	No

Full details, including the sending limits, are in the transactional email API reference.

Laravel questions

Can I use Laravel's Mail facade with Warmerly?

Not today. The Mail facade needs an SMTP server or a supported API driver, and Warmerly's transactional API is REST only. Call the API with the Http facade, as above.

Does this work with Laravel Octane, Vapor or queues?

Yes. It is a plain HTTP request with a timeout, with no state, so it works anywhere the Http facade does. Use a queued job for anything you do not want in the request cycle.

Is there a Laravel package or SDK for Warmerly?

No. Warmerly's transactional API is one HTTP request, so there is nothing to install. The code on this page is the whole integration.

Can I send attachments?

Not yet. The send request takes from, to, cc, bcc, reply_to, subject, html or text, headers and tags. Attachments, SMTP relay, delivery webhooks and templates are not available today.

What if sending is throttled or the mail server cannot be reached?