Skip to main content

Laravel

Use the PHP SDK when you need the email API. Existing Laravel Mailables can use SMTP.

Before you start​

The SDK requires PHP 8.3 or later. You also need a verified sending domain and an API key with the sending scope.

Install and configure​

composer require epostix/sdk-php guzzlehttp/guzzle

Add the key to your environment:

.env
EPOSTIX_API_KEY=your_api_key

Add this entry to the array returned by config/services.php:

'epostix' => [
    'key' => env('EPOSTIX_API_KEY'),
],

Read it through config() in application code. Calling env() there can return an empty value after configuration is cached.

Send from application code​

For a first send, run this in php artisan tinker, after replacing the sender and recipient:

use Epostix\Client;
use Epostix\Generated\EmailCreate;

$client = new Client(config('services.epostix.key'));

$email = $client->emails->sendEmail(new EmailCreate(
    from: 'hello@mail.yourdomain.com',
    to: ['you@yourdomain.com'],
    subject: 'Your first email',
    html: '<p>Sent with Epostix.</p>',
    text: 'Sent with Epostix.',
), idempotencyKey: 'first-email-001');

$email->id;

The call returns the accepted email or throws an exception. API failures expose type, status and requestId on EpostixApiError. Do not catch and discard an exception in a queue job: the job would look successful even though the send failed.

Use Activity or webhooks to follow delivery.

Queue jobs​

Pass an idempotency key derived from a stored event, such as order-4821-confirmation. Keep it unchanged when the job retries, together with the request body and API key.

The SDK handles bounded retries for eligible transient failures. A job retry is a separate SDK call, so supply your own key to connect those attempts. See idempotency for the 24-hour window.

Keep existing Mailables on SMTP​

For an application using Laravel's SMTP mailer, configure the values its config/mail.php reads:

.env
MAIL_MAILER=smtp
MAIL_SCHEME=smtp
MAIL_HOST=smtp.epostix.com
MAIL_PORT=587
MAIL_USERNAME=your_full_smtp_username
MAIL_PASSWORD=your_smtp_password
MAIL_FROM_ADDRESS=hello@mail.yourdomain.com

Current Laravel applications use MAIL_SCHEME; older configurations may read MAIL_ENCRYPTION=tls instead. Check your application's configuration and use STARTTLS on port 587. Rebuild cached configuration after changing production values.

SMTP credentials come from API Keys & SMTP in the dashboard and are separate from API keys. Existing Mail::to(...)->send(...) calls then use Epostix.

Test safely​

Use a test API key or a sandbox recipient with the SDK. SMTP submission is live and has no test-key equivalent.