Airmail / Developer guides
Laravel Email API Integration
Use the built-in HTTP client; no custom mail driver or Airmail package is required for REST sending.
Free Developer beta. Verified domain and manual sending approval required.
Configure your server
In config/services.php add the airmail entry below. Read env only from configuration so Laravel's configuration cache works. Store a logical email job before sending and reuse its idempotency key on retry. This uses the documented Http client API available in Laravel 8 and later; maintain a supported framework version for production.
// config/services.php
'airmail' => ['key' => env('AIRMAIL_API_KEY')],Send from a job or application service
Replace example addresses and persist the returned message ID. Only run live sends after approval. Laravel's HTTP client does not throw for all HTTP errors unless instructed, so explicitly handle the response. Do not wrap this in an unbounded retry loop.
use Illuminate\Support\Facades\Http;
$response = Http::withToken(config('services.airmail.key'))
->acceptJson()->timeout(15)
->withHeaders(['Idempotency-Key' => 'account-481-welcome'])
->post('https://api.airmailai.tech/v1/messages', [
'from' => ['email' => 'notifications@example.com'],
'to' => [['email' => 'recipient@example.net']],
'subject' => 'Welcome', 'text' => 'Your account is ready.',
]);
$response->throw();
$messageId = $response->json('id');Handle retries without duplicates
Persist one Idempotency-Key per logical REST send. Reuse the same key and identical payload when a request times out; do not create a new key for a retry. A 202 response means durable acceptance, not final delivery. Save the msg_* ID and inspect Messages or signed webhooks for the result. After acceptance, do not resubmit deferred mail: Airmail and its delivery service own those retries. Do not automatically fail over an ambiguous send to another provider, because the first provider may already have accepted it.
Before your first production message
Start with the free Developer beta. Verify your account, create a workspace and add a domain you control: example.com and mail.example.com are both supported. Publish the records shown in Domains. Merge an existing SPF policy rather than adding another; preserve a valid existing DMARC policy. Create an API key after verification, use the dashboard for one owner-controlled validation, and request production approval. SMTP credentials become available after activation. No repository or SSH access is needed.