README

Official PHP SDK for the Postscale email API.

Installation

composer require postscale/postscale-php

Requires PHP 8.1 or newer.

Send Email

<?php

use Postscale\Postscale;

$postscale = Postscale::client(getenv('POSTSCALE_API_KEY'));

$result = $postscale->emails->send([
    'from' => 'hello@example.com',
    'to' => ['user@example.com'],
    'subject' => 'Welcome to Postscale',
    'html_body' => '<strong>It works.</strong>',
]);

if ($result->error !== null) {
    throw new RuntimeException($result->error->code . ': ' . $result->error->message);
}

echo $result->data['message_id'];

The SDK keeps Postscale API-native field names. Use html_body, text_body, template_id, and unsubscribe_scope; the MVP SDK does not add html or text aliases.

Configuration

$postscale = Postscale::client(null, [
    'base_url' => 'https://api.postscale.io',
    'timeout' => 30,
    'max_retries' => 3,
    'headers' => [],
]);

If no API key is passed, the SDK reads POSTSCALE_API_KEY. If no base URL is passed, it reads POSTSCALE_BASE_URL and then falls back to https://api.postscale.io.

Retries are limited to idempotent GET, HEAD, and OPTIONS requests. The SDK does not retry POST /v1/send or POST /v1/send/batch automatically.

Results and Errors

Every API method returns a Postscale\Result object:

$result = $postscale->domains->list(['limit' => 10]);

if ($result->error !== null) {
    echo $result->error->statusCode;
    echo $result->error->code;
    echo $result->error->message;
    echo $result->error->requestId;
}

Configuration and local validation failures are raised as SDK exceptions before a request is sent.

Attachments

use Postscale\Attachment;

$attachment = Attachment::fromFile('invoice.pdf', 'application/pdf');

$result = $postscale->emails->send([
    'from' => 'billing@example.com',
    'to' => ['customer@example.com'],
    'subject' => 'Invoice',
    'text_body' => 'Attached.',
    'attachments' => [$attachment],
]);

Attachment helpers return API-native arrays with filename, content, and content_type. Client-side checks enforce the documented limits: 10 attachments, 25 MB per attachment, and 50 MB total decoded attachment payload.

Webhook Verification

use Postscale\Webhook;

$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_POSTSCALE_SIGNATURE'] ?? null;

$verified = Webhook::verifySignature(
    $rawBody,
    $signature,
    [getenv('POSTSCALE_WEBHOOK_SECRET'), getenv('POSTSCALE_PREVIOUS_WEBHOOK_SECRET')],
);

if (!$verified->valid()) {
    http_response_code(401);
    exit;
}

The verifier requires the Postscale signature format: t=<unix_seconds>,v1=<hex_hmac_sha256>, signed over <t>.<raw_body>. It supports multiple v1= signatures and multiple candidate secrets for rotation windows.

API Reference

Emails

$postscale->emails->send([...]);
$postscale->emails->sendBatch([['from' => '...', 'to' => ['...'], 'subject' => '...']]);
$postscale->emails->list([...]);
$postscale->emails->get($emailId);
$postscale->emails->listEvents($emailId);

Domains

$postscale->domains->create(['domain' => 'example.com']);
$postscale->domains->list([...]);
$postscale->domains->get($domainId);
$postscale->domains->update($domainId, [...]);
$postscale->domains->verify($domainId);
$postscale->domains->dns($domainId);
$postscale->domains->delete($domainId);

DKIM

$postscale->dkim->generate($domainId, ['selector' => 's1']);
$postscale->dkim->list($domainId);
$postscale->dkim->rotate($domainId, ['old_selector' => 's1', 'new_selector' => 's2']);
$postscale->dkim->deactivate($domainId, 's1');

Inbound

$postscale->inbound->list([...]);
$postscale->inbound->get($emailId);
$postscale->inbound->downloadAttachment($emailId, $attachmentId);

Suppressions

$postscale->suppressions->list([...]);
$postscale->suppressions->add(['email' => 'user@example.com', 'reason' => 'hard_bounce']);
$postscale->suppressions->check('user@example.com');
$postscale->suppressions->remove('user@example.com');
$postscale->suppressions->importPreview([...]);
$postscale->suppressions->importJob($jobId);
$postscale->suppressions->commitImport($jobId);

Templates

$postscale->templates->create([
    'name' => 'welcome',
    'subject' => 'Welcome',
    'html_body' => '<strong>Hello {{name}}</strong>',
]);
$postscale->templates->list([...]);
$postscale->templates->get($templateId);
$postscale->templates->update($templateId, [...]);
$postscale->templates->preview($templateId, ['variables' => ['name' => 'Ada']]);
$postscale->templates->delete($templateId);

Webhooks

$postscale->webhooks->create(['url' => 'https://example.com/webhooks', 'events' => ['email.delivered']]);
$postscale->webhooks->list([...]);
$postscale->webhooks->deliveries([...]);
$postscale->webhooks->endpointDeliveries($webhookId);
$postscale->webhooks->rotateSecret($webhookId);
$postscale->webhooks->delete($webhookId);

Warming, Stats, Usage, and Trust

$postscale->warming->getStatus($domainId);
$postscale->warming->history($domainId);
$postscale->warming->start($domainId);
$postscale->warming->pause($domainId);
$postscale->warming->resume($domainId);

$postscale->stats->aggregate($domainId);
$postscale->stats->daily($domainId);
$postscale->stats->hourly($domainId);
$postscale->stats->isp($domainId);

$postscale->usage->summary();
$postscale->trust->getReviewRequest();
$postscale->trust->createReviewRequest([...]);

Testing

composer test
composer analyse

License

MIT