README

The official Laravel integration for the Anypost email API: a mail transport, webhook events handler, and API client.

Requires Laravel 10 through 13 and PHP 8.1+. Built on anypost/anypost-php.

Install

composer require anypost/anypost-laravel

The service provider and Anypost facade are auto-discovered. Publish the config if you want to edit it:

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

Configuration

Set your API key in .env:

ANYPOST_API_KEY=ap_your_api_key

config/anypost.php also exposes base_url, the client options (timeout, max_retries), the webhook path/domain, and the webhook secret/tolerance. All read from environment variables.

Sending mail

Add an anypost mailer to config/mail.php:

'mailers' => [
    'anypost' => [
        'transport' => 'anypost',
    ],
],

Then point Laravel at it:

MAIL_MAILER=anypost

Every Mailable, Notification, and Mail::raw now sends through Anypost. Nothing else changes:

use Illuminate\Support\Facades\Mail;

Mail::to('someone@example.com')->send(new OrderShipped($order));

Tags, campaigns, and topics

The transport maps Laravel's envelope metadata onto Anypost's correlation dimensions. tags become Anypost tags; the reserved campaign, topic, and template_id metadata keys map to those fields:

use Illuminate\Mail\Mailables\Envelope;

public function envelope(): Envelope
{
    return new Envelope(
        subject: 'Your order has shipped',
        tags: ['transactional', 'shipping'],
        metadata: ['campaign' => 'order-lifecycle', 'topic' => 'shipping'],
    );
}

CC, BCC, reply-to, attachments, and custom headers carry over from the message. To set a send idempotency key, add an Anypost-Idempotency-Key header to the message.

Direct API access

Inject the client to reach any resource group — email, domains, apiKeys, templates, suppressions, webhooks, events:

use Anypost\Anypost;

public function __construct(private Anypost $anypost) {}

public function send()
{
    return $this->anypost->email->send([
        'from' => 'Acme <you@yourdomain.com>',
        'to' => ['someone@example.com'],
        'subject' => 'Hello',
        'html' => '<p>It worked.</p>',
    ]);
}

The Anypost facade proxies method calls such as Anypost::whoami(). Resource groups are properties, so reach them through the injected client.

Webhooks

The package registers POST /anypost/webhook (route name anypost.webhook). Point an Anypost webhook at that URL and set the signing secret:

ANYPOST_WEBHOOK_SECRET=whsec_your_secret

With a secret set, the signature is verified against the raw body before any event fires; an invalid signature returns 403. Leave the secret empty to disable verification (not recommended).

Each canonical event is dispatched as its own Laravel event under Anypost\Laravel\Events:

Listen for the ones you care about:

use Anypost\Laravel\Events\EmailBounced;

class LogBounces
{
    public function handle(EmailBounced $event): void
    {
        $emailId = $event->event['data']['email_id'];
        // $event->event = ['id' => ..., 'type' => ..., 'occurred_at' => ..., 'data' => [...]]
    }
}

A single delivery may carry multiple events; the controller dispatches one Laravel event per canonical event in the batch.

License

MIT