Skip to content

Mail on OneSignal

View raw .md

How to send selected mail classes through OneSignal email, with an SMTP failover, while Laravel still renders every mail with your views and theme.

On this page

Quick Reference#

text
MAIL_MAILER=routed
MAGIC_STARTER_MAIL_ONESIGNAL_ENABLED=true
MAGIC_STARTER_MAIL_ONESIGNAL_CLASSES=TeamInvitationNotification
Item Value
Mailers onesignal, onesignal-failover and routed, defined in config/mail.php.
Switch MAGIC_STARTER_MAIL_ONESIGNAL_ENABLED, off by default.
Classes MAGIC_STARTER_MAIL_ONESIGNAL_CLASSES, comma separated basenames or *.
Credentials ONESIGNAL_APP_ID and ONESIGNAL_REST_API_KEY, the same as push.
Check php artisan magic-starter:mail:doctor, which sends nothing.
Prune php artisan magic-starter:mail:prune-sends, daily.

Introduction#

The package can send your application's mail through OneSignal email. Laravel still renders every mail with your views and theme; the onesignal transport only hands the finished subject and HTML to OneSignal.

Nothing moves until you ask for it. The transport is selected by a mailer, and the router sends a mail class through OneSignal only when its switch is on and the class is listed. A class you did not list keeps going through your usual mailer, so you can move one mail at a time and move it back the same way.

Before the first send, OneSignal needs its email channel set up: a sender on a domain you own, the SPF, DKIM and DMARC records, and a verified account. Until then OneSignal accepts test sends to your own addresses only.


The Mailers#

The package registers two transports. Add the mailers that use them to config/mail.php:

php
'mailers' => [
    // ...

    // OneSignal email on its own. Use it inside a failover, never as the default.
    'onesignal' => [
        'transport' => 'onesignal',
    ],

    // OneSignal first, then your SMTP mailer for anything OneSignal does not send.
    'onesignal-failover' => [
        'transport' => 'failover',
        'mailers' => ['onesignal', 'smtp'],
        'retry_after' => 60,
    ],

    // The router: each mail class goes to its routed mailer or to `default`.
    'routed' => [
        'transport' => 'magic-starter-router',
        'default' => 'smtp',
    ],
],

Point MAIL_MAILER at routed when you want routing. With the switch off, routed hands every mail to its default mailer, so the switch is the only thing that changes delivery.

The onesignal transport reads the same credentials as push: magic-starter.onesignal.app_id and the REST API key (ONESIGNAL_APP_ID, ONESIGNAL_REST_API_KEY).


Routing a Mail Class#

The router reads magic-starter.mail.onesignal:

Env key Default Meaning
MAGIC_STARTER_MAIL_ONESIGNAL_ENABLED false The switch. Off, nothing is routed.
MAGIC_STARTER_MAIL_ONESIGNAL_CLASSES empty Comma separated class basenames (ResetPassword, TeamInvitationNotification); * routes every class.
MAGIC_STARTER_MAIL_ONESIGNAL_MAILER onesignal-failover The mailer a listed class leaves through.
MAGIC_STARTER_MAIL_ONESIGNAL_RETENTION_DAYS 30 How long a send record is kept.
text
MAIL_MAILER=routed
MAGIC_STARTER_MAIL_ONESIGNAL_ENABLED=true
MAGIC_STARTER_MAIL_ONESIGNAL_CLASSES=TeamInvitationNotification

The class is the notification or the mailable that sent the mail, matched by basename. A listener stamps it on mail sent through a router mailer only, and the router removes that header before the mail leaves, so a mail on any other mailer keeps exactly the headers it had.


The Failover#

Every OneSignal failure throws a TransportException, which is the one exception type Laravel's failover mailer acts on. So the next member (your SMTP mailer) delivers the mail when OneSignal:

  • is not provisioned (no app id or REST key);
  • gets a mail it has no field for (cc, bcc, attachments, or no HTML body);
  • refuses the request or cannot be reached;
  • answers without a message id, which is how OneSignal says it sent nothing.

A request to OneSignal gives up after 10 seconds (5 seconds to connect), so a hanging OneSignal fails over instead of holding the send. The limit is on the package's shared OneSignal client, so push and SMS calls through it are bounded the same way.

A failed member is skipped for retry_after seconds in that worker process, so a burst after one OneSignal error goes to SMTP for that window.

No recipient, subject or body appears in an exception or a log line. The failover logs each failure at ERROR, so the messages carry error keys and counts only.


Send Records and the Doctor#

Each mail OneSignal accepts writes a row to magic_starter_mail_sends: the OneSignal message id, the mail class, a sha256 of the first recipient and the recipient counts. It never stores an address, a subject or a body. A failed insert is reported and does not fail the mail, because the mail has already left.

magic-starter:mail:prune-sends runs daily and deletes rows past the retention. OneSignal keeps message data for 30 days, so a longer retention only keeps ids it can no longer answer for.

magic-starter:mail:doctor checks the setup and sends nothing:

bash
php artisan magic-starter:mail:doctor
php artisan magic-starter:mail:doctor --deliveries=20

It prints whether the credentials are set, whether OneSignal reports the email channel enabled, the router config and the default mailer. With --deliveries it reads OneSignal's counters (successful, failed, errored, received) for the last sends, by class and message id. It exits 1 when mail is routed (the router is on and the default mailer uses the router transport) and either the email channel is off or the routed mailer is not defined, since every routed mail would then land on the failover or on the default mailer.


Limits#

  • Every send uses include_unsubscribed, because your own database is the opt-out of record. OneSignal therefore adds no List-Unsubscribe header, and it cannot carry the one your mailable sets: keep the unsubscribe link in the body.
  • OneSignal creates an email subscription for every address it sends to. Name OneSignal in your privacy notice before you route mail to people outside your own users.
  • Marketing mail is out of scope: the transport sends to explicit addresses only and never targets a segment.
  • Notifications: the OneSignal push channel that shares these credentials, and mail branding.
  • Configuration: the mail.brand.* keys and the schedule block.
esc

Search index did not load.

No match for "".

Try a class like rounded-lg or a widget like WButton.