kobaltdigital / ahasend-laravel
AhaSend mail transport, API client and webhook handling for Laravel
Requires
- php: ^8.2
- illuminate/contracts: ^12.0|^13.0
- illuminate/http: ^12.0|^13.0
- illuminate/mail: ^12.0|^13.0
- illuminate/routing: ^12.0|^13.0
- illuminate/support: ^12.0|^13.0
- symfony/mailer: ^7.0|^8.0
Requires (Dev)
- larastan/larastan: ^3.0
- laravel/pint: ^1.18
- orchestra/testbench: ^10.0|^11.0
- pestphp/pest: ^3.0|^4.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Send mail from Laravel through AhaSend. You get a mail transport, a client for the rest of the API and a webhook endpoint that turns AhaSend events into Laravel events.
Requires PHP 8.2+ and Laravel 12 or 13.
Installation
composer require kobaltdigital/ahasend-laravel
Add your API key and account ID to .env. Both are in the AhaSend dashboard.
MAIL_MAILER=ahasend AHASEND_API_KEY=aha-sk-... AHASEND_ACCOUNT_ID=...
Then add the mailer to config/mail.php:
'mailers' => [ 'ahasend' => [ 'transport' => 'ahasend', ], ],
That's it. Mailables and notifications now go out through AhaSend.
Sending mail
Nothing changes in how you write mail. To, cc, bcc, reply-to, attachments, inline images and tags all work.
A few AhaSend features are set per message with a header. They are stripped before the mail is sent.
use KobaltDigital\AhaSend\Transport\AhaSendTransport; use Illuminate\Mail\Mailables\Headers; public function headers(): Headers { return new Headers(text: [ AhaSendTransport::HEADER_IDEMPOTENCY_KEY => "invoice-{$this->invoice->id}", AhaSendTransport::HEADER_SCHEDULED_AT => now()->addHour()->toRfc3339String(), ]); }
| Header | Value |
|---|---|
X-AhaSend-Idempotency-Key |
Any string. Sending the same key twice sends one mail. |
X-AhaSend-Sandbox |
true to send to the sandbox. |
X-AhaSend-Sandbox-Result |
deliver, bounce, defer, fail or suppress. |
X-AhaSend-Track-Opens |
true or false. |
X-AhaSend-Track-Clicks |
true or false. |
X-AhaSend-Scheduled-At |
RFC 3339 time, at most 7 days ahead. |
X-AhaSend-Expires-At |
RFC 3339 time after which the mail is dropped. |
Sandbox and tracking can also be set for the whole mailer:
'ahasend' => [ 'transport' => 'ahasend', 'sandbox' => env('AHASEND_SANDBOX', false), 'track_opens' => false, 'track_clicks' => false, ],
After sending, the AhaSend message ID is on the message as X-AhaSend-Message-ID. Listen for Laravel's MessageSent event if you want to store it.
The API
For everything else there is a facade. Paths are relative to your account.
use KobaltDigital\AhaSend\Facades\AhaSend; AhaSend::messages()->send([ 'from' => ['email' => 'hello@example.com'], 'recipients' => [ ['email' => 'ada@example.org', 'substitutions' => ['name' => 'Ada']], ], 'subject' => 'Welcome, {{ name }}', 'html_content' => '<p>Hello {{ name }}</p>', ]); AhaSend::messages()->get($id); AhaSend::messages()->cancel($id); AhaSend::get('domains'); AhaSend::ping();
Requests that hit a rate limit, a server error or a dropped connection are retried twice. Every POST carries an idempotency key, so a retry never sends a mail twice. A request that still fails throws an ApiException (with status and body) or a ConnectionFailed.
See the AhaSend API reference for all endpoints and payloads.
Webhooks
Create a webhook in AhaSend that points to https://your-app.com/ahasend/webhook and put its secret in .env:
AHASEND_WEBHOOK_SECRET=aha-whsec-...
Using more than one webhook or an inbound route? Separate the secrets with a comma.
Every delivery is verified before anything happens. Then listen for the event you need:
use KobaltDigital\AhaSend\Events\MessageBounced; Event::listen(function (MessageBounced $event) { $email = $event->data('recipient'); $reason = $event->data('delivery_attempt.response'); // ... });
Each AhaSend event has a class in KobaltDigital\AhaSend\Events with the same name: message.delivered is MessageDelivered, contact.added_to_list is ContactAddedToList. Inbound mail arrives as MessageRouting. WebhookReceived fires for every delivery, including event types added after this release.
Two things to keep in mind:
- AhaSend retries deliveries, so you can get an event more than once.
$event->deliveryId()is the same for each retry. - Events don't arrive in order. Sort on
$event->occurredAt().
Configuration
Publish the config file if you want to change the timeout, the retries or the webhook route:
php artisan vendor:publish --tag=ahasend-config
Security
- The API key is only sent over HTTPS and never ends up in an exception message.
- Webhooks without a valid signature and a recent timestamp get a 403. There is no way to turn verification off.
- No webhook secret configured means the endpoint returns a 500, not a 200.
Found a problem? See SECURITY.md.
Testing
composer test
Credits
Built by Kobalt. Not affiliated with AhaSend.
License
MIT. See LICENSE.