Download the PHP package mattstein/usesend-laravel without Composer

useSend mail transport for Laravel

Send Laravel mail through useSend, the open-source transactional email service, with a first-party mail transport.

• Works with useSend Cloud, or a self-hosted instance behind your own domain.
• Maps recipients, attachments, custom headers, tags, and metadata onto useSend's send API.
• Sends through a useSend template, schedules delivery, and threads replies.
• Fails loudly: every rejection becomes an exception that says what useSend said.
• Retries connection failures, server errors, and rate limits without ever double-sending.
• Supports idempotency keys, so a retried queued job cannot double-send either.
• Keeps the email ID useSend returns, for API lookups and webhooks.
• Sends recipients so useSend’s suppression list can match them.

Requirements

• PHP 8.2+
• Laravel 12 or 13

Laravel 10 and 11 are past end of life, and every release of them is affected by an unpatched security advisory, so Composer will not install them.

Installation

Publish the config and point it at your instance:

The command publishes config/usesend.php and lists the next steps. Pass --force to overwrite a config file you already published.

Then set the mailer:

Usage

Mail now goes through useSend; nothing else changes.

A named mailer alongside another provider

The usesend mailer is always available, so you can keep a second transport without touching the global one:

Per-mailer settings

Anything in config/usesend.php can be overridden for a single mailer, which is handy for multi-tenant apps or a staging instance:

Settings are read per send, not cached at boot, so an app that resolves an API key per tenant at runtime works too.

Templates

Send a useSend template instead of the mailable’s rendered HTML. useSend replaces the subject and HTML with the template’s:

The mailable still needs a body. useSend rejects a request with neither text nor HTML, even when it uses a template, and Laravel will not send a message without one either. Its HTML is sent and replaced by the template; its text is only sent when there is no HTML, because useSend does not replace text. Its subject is sent too, and replaced by the template's: if the template ID does not exist, useSend sends the mailable's own subject and HTML instead.

Variables are sent as strings, because that is all useSend accepts: numbers are cast, booleans become "true" or "false", null becomes "", and arrays become JSON.

Scheduled sends

Have useSend hold an email and deliver it later:

The send itself happens straight away: useSend accepts the email, returns its ID, and delivers it at the scheduled time. A time in the past is delivered immediately. Cancelling or rescheduling a scheduled email is done through useSend's API with that ID.

Replies

Thread an email as a reply to one useSend sent earlier, by its email ID:

Or without a template, with the header:

To reply to mail useSend did not send, set the standard In-Reply-To and References headers, which are forwarded as they are.

Idempotent sends

Give a mailable an idempotency key and useSend sends it at most once per key, for 24 hours. Derive the key from what makes the email unique, so a retried queued job sends the same key:

Or set the header yourself, which works from headers() or a notification:

The key goes to useSend as its Idempotency-Key request header, never as an email header. Keys can be up to 256 characters. useSend answers a repeat of the same key and email with the original email, and a repeat with a different email with HTTP 409.

The useSend email ID

After a send, the ID useSend returns becomes the message ID, and is added to the message as an X-UseSend-Email-Id header:

Recipients

The to recipients come from the message envelope, which is who the mail is actually delivered to, minus anyone who is only on cc or bcc. A message needs at least one to recipient, because useSend requires one.

Recipients and reply-to addresses are sent without display names. useSend checks its suppression list against the exact string it receives, so "Jane" <[email protected]> would get past a suppressed [email protected]. The sender keeps its display name.

Custom headers, tags, and metadata

Any header a mailable sets is forwarded to useSend, except the ones that describe the envelope or the MIME structure, which useSend owns:

List-Unsubscribe, X-Campaign, and similar headers are all forwarded, which copy-pasted transports usually drop. Values are sent as written, so non-ASCII text arrives intact.

Laravel's tag() and metadata() become X-Tag and X-Metadata-* headers. useSend takes one value per header, so repeated headers are joined: two tags are sent as X-Tag: welcome, onboarding.

Attachments

Attachments are sent base64-encoded, up to the ten useSend accepts. A part with no filename is named after its media type (attachment.csv), because useSend rejects an empty filename.

Inline images (cid: references) have no equivalent in useSend's send API, so they are left out by default. Set USESEND_INLINE_ATTACHMENTS=attach to send them as ordinary attachments instead.

Configuration

Self-hosted instances

base_url accepts the shapes people actually paste:

Anything else, including an empty value, throws InvalidBaseUrlException rather than guessing an instance.

Retries

Retries are off by default. Turn them on to ride out a dropped connection, a server error, or useSend's rate limit:

That is up to three attempts in all, USESEND_RETRY_SLEEP milliseconds apart. A rate limit waits as long as useSend's Retry-After asks, up to a minute. Any other 4xx is never retried, because a rejected email will be rejected again.

Retrying is always safe. The attempts of one send share a generated Idempotency-Key, so if a response is lost and the request is retried, useSend answers with the original email instead of sending a second one. The key is random, so two intentional sends of the same mailable stay two sends.

A generated key only covers these HTTP retries. When a queued job is retried, it is a new send with a new key. To cover that too, set a key on the message, as described in Idempotent sends.

Errors

Everything thrown extends UseSendException, which implements Symfony's TransportExceptionInterface so Laravel reports a failed delivery rather than an unhandled error.

Everything except ApiRequestFailedException is thrown before any request is made.

ApiRequestFailedException carries the HTTP status, useSend's errorCode (such as RATE_LIMITED or NOT_UNIQUE), and the responseBody. Its message includes whatever useSend said, field by field for a failed validation. The API key is never part of a message, so these exceptions are safe to log:

Redirects are never followed, because following one would turn the request into a GET that can answer 200 without sending anything. A redirect, or a successful response that is not JSON, means the base URL points at something other than useSend's API, and fails with a message that says so.

Testing

The transport uses Laravel's HTTP client, so Http::fake() works as usual:

To assert on a failure, fake the error useSend would return:

The HTTP client is resolved from the container for each send, so Http::fake() applies however early the mailer was created. To test the transport on its own, pass it an HTTP factory:

Migrating from a hand-rolled transport

See UPGRADING.md for the step-by-step swap, including the mail.mailers.unsend → mail.mailers.usesend rename.

How the message maps to the API

Each concern sets a header, so the same options work from withSymfonyMessage() in a notification or anywhere else a mailable trait cannot go:

These headers are read by the transport and never sent as email headers.

The transport sends one email per message. useSend's other endpoints, such as batch sends, cancelling or rescheduling, and contacts, are outside what a mail transport does; use the email ID it records with useSend's API for those.

License

The MIT License (MIT). Please see LICENSE.md for more information.