Send transactional email with Laravel

Send a transactional email from Laravel with a single POST to /v1/email, authenticated with a Bearer API key. There is no official Laravel package, so you call the REST endpoint with Laravel's built-in Http facade. This is a drop-in alternative to Laravel's mail driver for transactional sends: no mailer config, just an HTTP call. See Send email via the API for the full field reference.

Prerequisites

• An API key. Put it in .env and read it through config.
• A verified sending domain for the from address.

Configuration

Add the key to .env:

MAILHUSET_API_KEY=your-key-here

Expose it through a config file, for example config/services.php:

'mailhuset' => [
    'key' => env('MAILHUSET_API_KEY'),
],

Sending

Call the endpoint from a controller or a queued job with the Http facade:

<?php

namespace App\Http\Controllers;

use Illuminate\Support\Facades\Http;

class ReceiptController extends Controller
{
    public function send()
    {
        $response = Http::withToken(config('services.mailhuset.key'))
            ->post('https://api.mailhuset.com/v1/email', [
                'from'    => 'Acme <hello@yourdomain.com>',
                'to'      => ['customer@example.com'],
                'subject' => 'Your receipt',
                'html'    => '<p>Thanks for your order.</p>',
                'text'    => 'Thanks for your order.',
            ]);

        if ($response->successful()) {
            return $response->json('id');
        }

        // 401 bad/missing key, 403 from-domain not verified, 422 validation error.
        report(new \RuntimeException(
            "Mailhuset send failed ({$response->status()}): {$response->body()}"
        ));

        abort(502, 'Could not send email.');
    }
}

Http::withToken() sets the Authorization: Bearer header, and ->post() sends the body as JSON with the right Content-Type. Doing this inside a queued job keeps the send off the request path.

Fields

Build the body with the real fields: from (Name <address> on a verified domain), to (an array), subject, and the body as html and text (send both when you can). cc, bcc, replyTo (arrays) and idempotencyKey are optional. The full list is in Send email via the API.

Response

A 2xx returns the accepted message, including its id; $response->successful() covers that range. Errors: 401 bad or missing key, 403 the from domain is not verified, 422 a validation error (the response says which field).

Prefer Laravel's mail driver? Use SMTP

On a paid plan you can keep Laravel's own Mail facade and mailables and send through the SMTP relay instead of calling the API. Set these in .env with an SMTP credential from the dashboard:

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailhuset.com
MAIL_PORT=587
MAIL_ENCRYPTION=tls
MAIL_USERNAME=your-credential-username
MAIL_PASSWORD=your-credential-password
MAIL_FROM_ADDRESS=hello@yourdomain.com

Next steps

Reuse content with Templates, and track delivery with Webhooks. Prefer a typed client? Node and Python have official SDKs.

Need help? Email support@mailhuset.com.