Send email with PHP

Send a transactional email from PHP with a single POST to /v1/email, authenticated with a Bearer API key. There is no official PHP SDK, so you call the REST endpoint directly; both examples below do that. See Send email via the API for the full field reference.

Prerequisites

• An API key, read from the MAILHUSET_API_KEY environment variable.
• A verified sending domain for the from address.

Guzzle

Guzzle is the common HTTP client. Install it with composer require guzzlehttp/guzzle, then:

<?php

use GuzzleHttp\Client;
use GuzzleHttp\Exception\ClientException;

$client = new Client();

try {
    $response = $client->post('https://api.mailhuset.com/v1/email', [
        'headers' => [
            'Authorization' => 'Bearer ' . getenv('MAILHUSET_API_KEY'),
            'Content-Type'  => 'application/json',
        ],
        'json' => [
            'from'    => 'Acme <hello@yourdomain.com>',
            'to'      => ['customer@example.com'],
            'subject' => 'Your receipt',
            'html'    => '<p>Thanks for your order.</p>',
            'text'    => 'Thanks for your order.',
        ],
    ]);

    $message = json_decode((string) $response->getBody(), true);
    echo "Accepted: {$message['id']}\n";
} catch (ClientException $e) {
    // 401 bad/missing key, 403 from-domain not verified, 422 validation error.
    $status = $e->getResponse()->getStatusCode();
    $body   = (string) $e->getResponse()->getBody();
    fwrite(STDERR, "Send failed ($status): $body\n");
}

Guzzle throws on a 4xx response, so the catch block is where you read the status and the error body.

Raw cURL

No dependencies, just the curl_* functions built into PHP:

<?php

$payload = json_encode([
    'from'    => 'Acme <hello@yourdomain.com>',
    'to'      => ['customer@example.com'],
    'subject' => 'Your receipt',
    'html'    => '<p>Thanks for your order.</p>',
    'text'    => 'Thanks for your order.',
]);

$ch = curl_init('https://api.mailhuset.com/v1/email');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('MAILHUSET_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS     => $payload,
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 200 && $status < 300) {
    $message = json_decode($body, true);
    echo "Accepted: {$message['id']}\n";
} else {
    // 401 bad/missing key, 403 from-domain not verified, 422 validation error.
    fwrite(STDERR, "Send failed ($status): $body\n");
}

Fields

Build the JSON 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. Errors: 401 bad or missing key, 403 the from domain is not verified, 422 a validation error (the response says which field).

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.