README

Laravel Postmark

A PHP/Laravel client for the Postmark REST API. Covers transactional email (single, templated and batch), templates, bounces, message search, outbound statistics, server details and suppressions through a simple, typed API built on Laravel's Http client.

Features

Transactional email: send a single message, a templated message, or a batch of either
Templates: list, get, create, update, delete
Bounces: list with filters, get, raw dump, reactivate, delivery stats
Messages: search outbound and inbound, get message details
Stats: outbound overview, sends, bounces, opens, clicks, spam
Server: get the authenticated server's details
Suppressions: dump, create and delete per message stream
Throws PostmarkException (carrying Postmark's ErrorCode and error body) on any non-2xx response
Throws InvalidArgumentException before hitting the API when a required field is missing

Installation

You can install the package via composer:

composer require jeffersongoncalves/laravel-postmark

Publish the config file:

php artisan vendor:publish --tag=postmark-config

Set your Postmark server token in .env:

POSTMARK_TOKEN=your-server-token

Find it under Servers > (your server) > API Tokens in your Postmark account.

Configuration

// config/postmark.php
return [
    'api_url' => env('POSTMARK_API_URL', 'https://api.postmarkapp.com'),
    'token' => env('POSTMARK_TOKEN', ''),
    'message_stream' => env('POSTMARK_MESSAGE_STREAM', 'outbound'),
    'default_count' => env('POSTMARK_DEFAULT_COUNT', 50),
];

message_stream is applied to every send and suppression call that does not pass its own, and default_count is the page size used by the list endpoints.

Usage

The package is resolved via the Postmark facade or by injecting JeffersonGoncalves\Postmark\Postmark. Each API group is exposed as a method returning a dedicated resource class; sending and the server endpoint live directly on the manager.

Sending email

use JeffersonGoncalves\Postmark\Facades\Postmark;

Postmark::sendEmail(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome aboard',
    htmlBody: '<p>Hello!</p>',
);

// Several recipients (Postmark accepts up to 50 per message):
Postmark::sendEmail('sender@example.com', ['a@example.com', 'b@example.com'], 'Hi', textBody: 'Hi');

// Any other Postmark field goes in $options:
Postmark::sendEmail(
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Welcome aboard',
    htmlBody: '<p>Hello!</p>',
    options: [
        'Cc' => 'cc@example.com',
        'ReplyTo' => 'reply@example.com',
        'Tag' => 'welcome',
        'TrackOpens' => true,
        'TrackLinks' => 'HtmlAndText',
        'MessageStream' => 'broadcast',
    ],
);

Sending with a template

An integer is sent as TemplateId, a string as TemplateAlias:

Postmark::sendEmailWithTemplate('sender@example.com', 'recipient@example.com', 'welcome', [
    'name' => 'Ada',
    'product_url' => 'https://example.com',
]);

Postmark::sendEmailWithTemplate('sender@example.com', 'recipient@example.com', 1234567);

Sending a batch

Batches take raw Postmark message payloads; the configured message stream is applied to any message that does not set its own.

Postmark::sendBatch([
    ['From' => 'sender@example.com', 'To' => 'a@example.com', 'Subject' => 'Hi', 'TextBody' => 'Hi'],
    ['From' => 'sender@example.com', 'To' => 'b@example.com', 'Subject' => 'Hi', 'TextBody' => 'Hi'],
]);

Postmark::sendBatchWithTemplates([
    ['From' => 'sender@example.com', 'To' => 'a@example.com', 'TemplateAlias' => 'welcome', 'TemplateModel' => ['name' => 'Ada']],
]);

Templates

Postmark::templates()->list();
Postmark::templates()->list(count: 10, offset: 0, type: 'Standard');
Postmark::templates()->get('welcome');
Postmark::templates()->create('Welcome', 'Welcome aboard', [
    'Alias' => 'welcome',
    'HtmlBody' => '<p>Hello {{name}}</p>',
    'TextBody' => 'Hello {{name}}',
]);
Postmark::templates()->update('welcome', ['Subject' => 'Welcome!']);
Postmark::templates()->delete('welcome');

Bounces

Postmark::bounces()->list(['type' => 'HardBounce', 'inactive' => true]);
Postmark::bounces()->get(692560173);
Postmark::bounces()->dump(692560173);   // raw bounce source
Postmark::bounces()->activate(692560173); // reactivate the address
Postmark::bounces()->deliveryStats();

Messages

Postmark::messages()->outbound(['tag' => 'welcome', 'status' => 'sent']);
Postmark::messages()->inbound(['recipient' => 'inbox@example.com']);
Postmark::messages()->get('0a129aee-e1cd-480d-b08d-4f48548ff48d');
Postmark::messages()->inboundDetails('e2ecbbfc-fe12-463d-b933-9fe22915106d');

Stats

Postmark::stats()->overview();
Postmark::stats()->sends(tag: 'welcome', fromDate: '2026-01-01', toDate: '2026-01-31');
Postmark::stats()->bounces();
Postmark::stats()->opens();
Postmark::stats()->clicks();
Postmark::stats()->spam();

Server

Postmark::server();

Suppressions

Postmark::suppressions()->list();                    // configured stream
Postmark::suppressions()->list('broadcast');
Postmark::suppressions()->create('bounced@example.com');
Postmark::suppressions()->create(['a@example.com', 'b@example.com'], 'broadcast');
Postmark::suppressions()->delete('a@example.com');

Error handling

use JeffersonGoncalves\Postmark\Exceptions\PostmarkException;

try {
    Postmark::sendEmail('sender@example.com', 'recipient@example.com', 'Hi', textBody: 'Hi');
} catch (PostmarkException $e) {
    $e->getMessage();  // Postmark's "Message"
    $e->getCode();     // Postmark's "ErrorCode", or the HTTP status when absent
    $e->errorBody();   // the full decoded error body
}

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

jeffersongoncalves / laravel-postmark

Package info

Security

Fund package maintenance!

Statistics