Documentation

Send email in PHP.

Works with: PHP 8.1 or newer. No required dependencies.

Install

Get a key under API keys in the dashboard and verify a sending domain first (how). Then add the library:

Terminal

1composer require mailtruss/mailtruss

Send an email

This sends one message and passes an idempotency key, so repeating the request can never deliver it twice. Pass an idempotency key and the same key never sends twice, so a retry after a timeout is safe.

send.php

1$mt = new Mailtruss\Mailtruss(getenv('MAILTRUSS_API_KEY'));
2$mt->emails->send(['from' => 'hello@yourdomain.com', 'to' => 'ana@example.com', 'subject' => 'Welcome', 'html' => '<p>Hi Ana</p>'], idempotencyKey: 'welcome-ana');

More on what you can put in a message (cc, bcc, attachments, tags, templates, scheduling) is under Sending.

Laravel

The service provider is auto-discovered. Add the key to config/services.php and a mailer to config/mail.php, then set MAIL_MAILER=mailtruss. Mailables, notifications and queued mail then go through the API: Bcc is kept, attachments and inline images work, and a retried queue job does not send twice (the Message-ID is the idempotency key).

config

1// config/services.php
2'mailtruss' => ['key' => env('MAILTRUSS_API_KEY')],
3
4// config/mail.php, inside 'mailers'
5'mailtruss' => ['transport' => 'mailtruss'],
6
7// .env
8MAIL_MAILER=mailtruss

Verify webhook signatures

Mailtruss signs every webhook with the Standard Webhooks scheme. Check the signature before you trust a request. Read the raw body from php://input.

webhook.php

1$event = Mailtruss\Webhook::verify(file_get_contents('php://input'), getallheaders(), getenv('MAILTRUSS_WEBHOOK_SECRET'));

Events, payloads and retries are on the Webhooks page.

Handle errors

Failures are Mailtruss\MailtrussException with errorName, statusCode and requestId. Every error name, with its cause and fix, is in the error catalogue.