Search by

smstunnel / smstunnel-laravel

narcisbodea

SMSTunnel notification channel for Laravel: send notifications as texts from your own Android phone, from your own number.

v1.2.0 2026-11-15 14:41 UTC

This package is auto-updated.

Last update: 2026-11-15 14:41:42 UTC


README

smstunnel/smstunnel-laravel sends Laravel notifications as texts with SMSTunnel: from your own Android phone, from your own number. It works with Laravel 10, 11, 12 and 13.

$user->notify(new OrderShipped($order));

Your app hands the text to your SMSTunnel account and your phone sends it from its own SIM, so recipients see a number they know and can reply to. The phone is linked to your account when you sign in to the SMSTunnel app (or scan the QR code from your dashboard), and you can cut an app off at any time by deleting its API key in your dashboard.

Your phone needs the SMSTunnel app from Google Play:

Get it on Google Play

Contents

Installation

composer require smstunnel/smstunnel-laravel

The service provider is registered automatically (package discovery). It also installs smstunnel/smstunnel-php, the PHP client it builds on. PHP 8.1 or newer.

Setting up SMSTunnel

  1. Install the SMSTunnel app from Google Play on your Android phone and sign in. Sign in at smstunnel.io on your computer with the same account: the phone appears under Phones (you can also link it with the QR code from Phones → Add phone).
  2. In your SMSTunnel dashboard, open Apps → Add an app and create its key. The key can send texts and look up whether they went out (sms:send and sms:read).
  3. Add it to config/services.php:
'smstunnel' => [
    'key' => env('SMSTUNNEL_API_KEY'),
    'device_id' => env('SMSTUNNEL_DEVICE_ID'),                       // optional: send through this phone
    'default_country_code' => env('SMSTUNNEL_DEFAULT_COUNTRY_CODE'), // optional, e.g. +40, for numbers without + or 00
],
SMSTUNNEL_API_KEY=sk_live_...

Leave device_id empty to let SMSTunnel pick one of your phones. A url key points the channel at a self-hosted SMSTunnel; the default is https://smstunnel.io.

Usage

Return smstunnel (or SmsTunnelChannel::class) from via() and add a toSmsTunnel() method:

use Illuminate\Notifications\Notification;
use NotificationChannels\SmsTunnel\SmsTunnelMessage;

class OrderShipped extends Notification
{
    public function __construct(private Order $order) {}

    public function via(object $notifiable): array
    {
        return ['smstunnel'];
    }

    public function toSmsTunnel(object $notifiable): SmsTunnelMessage
    {
        return SmsTunnelMessage::create("Your order #{$this->order->id} has shipped.");
    }
}

toSmsTunnel() can also return a plain string.

Tell the channel which number to text with a routeNotificationForSmstunnel() method on the notifiable (for example your User model). Use the international format, such as +14155550123:

use Illuminate\Notifications\Notifiable;

class User extends Authenticatable
{
    use Notifiable;

    public function routeNotificationForSmstunnel(Notification $notification): ?string
    {
        return $this->phone_number;
    }
}

When it returns null or an empty string, nothing is sent, so users without a number are skipped.

To text someone who is not a user, send an on-demand notification:

use Illuminate\Support\Facades\Notification;

Notification::route('smstunnel', '+14155550123')->notify(new OrderShipped($order));

Notifications that implement ShouldQueue are sent from your queue like any other channel, which keeps your requests fast.

Available message methods

Method Description
SmsTunnelMessage::create(string $content) A new text.
content(string $content) The words of the text, up to 1600 characters (10 joined SMS).
deviceId(?string $deviceId) Send through this phone instead of services.smstunnel.device_id.
defaultCountryCode(?string $code) E.g. +40, for numbers given without + or 00. Wins over services.smstunnel.default_country_code.
verificationCode(bool $value = true) Send it as a sign-in or verification code (see below).
sendAt(DateTimeInterface|string|null $sendAt) Send it at this time instead of now (see Scheduled texts).
idempotencyKey(?string $key) Make the text's Idempotency-Key from your own key instead of the notification's id (see Retrying safely).
withoutIdempotencyKey() Send the text without an Idempotency-Key, as in 1.0.

Verification codes

public function toSmsTunnel(object $notifiable): SmsTunnelMessage
{
    return SmsTunnelMessage::create("Your sign-in code is {$this->code}")->verificationCode();
}

SMSTunnel checks that the text contains the code, 4 to 10 digits (such as 482913, 123-456 or 12-345678), and refuses it otherwise. Codes count against a separate quota, and the text can be up to 320 characters.

Scheduled texts

Give the message a send time, 1 minute to 30 days ahead, and SMSTunnel hands the text to your phone then:

public function toSmsTunnel(object $notifiable): SmsTunnelMessage
{
    return SmsTunnelMessage::create("Reminder: your appointment is tomorrow at {$this->appointment->starts_at->format('H:i')}.")
        ->sendAt($this->appointment->starts_at->copy()->subDay());
}
  • sendAt() takes a DateTimeInterface (Carbon too), sent with its own offset, or an ISO 8601 string with an offset, such as 2026-11-16T09:00:00+02:00.
  • NotificationSent's response is then a SmsTunnel\Response\ScheduledText (id, sendAt, status) instead of a SendResult. Keep the id to cancel the text with app(SmsTunnel\Client::class)->cancelScheduled($id); listScheduled() and getScheduled($id) read them (see the client's README).
  • At that time SMSTunnel sends the text as if your app sent it then, with the same key: it picks the phone then (unless you set one), and the text counts toward that day's allowance. If the phone is offline, the text waits for it up to 3 days.
  • The send time is part of the text's Idempotency-Key: make it from the notification's data, like the words, so a retry from your queue schedules the text once.
  • Verification codes can't be scheduled: a message with both fails with CouldNotSendNotification before anything is sent.
  • When as many texts wait as your plan allows (10 on Free up to 1000 on Enterprise), the notification fails with a PermissionException whose getErrorCode() is SCHEDULE_LIMIT_REACHED.

Several numbers

If routeNotificationForSmstunnel() returns a list of numbers, the channel sends one text to each of them (repeats are skipped). The NotificationSent event then carries a list of results. Each number gets its own Idempotency-Key, so when your queue retries the notification after one number failed, the numbers that already got the text are not texted again.

A number may hold digits, spaces, +, (, ), . and -. One with anything else (a line break or a tab, for example) fails the notification with CouldNotSendNotification before anything is sent.

Failures

When a text does not go through, the channel dispatches Laravel's Illuminate\Notifications\Events\NotificationFailed event and throws the exception again, like the other notification channels. The event's data holds message, exception and to (the number). With several numbers, the others are still tried before the exception is thrown.

use Illuminate\Notifications\Events\NotificationFailed;
use Illuminate\Support\Facades\Event;

Event::listen(function (NotificationFailed $event) {
    if ($event->channel === 'smstunnel') {
        logger()->warning('Text not sent', ['to' => $event->data['to'] ?? null, 'error' => $event->data['message'] ?? null]);
    }
});

The exceptions come from smstunnel/smstunnel-php, all under SmsTunnel\Exception\SmsTunnelException:

Exception When
AuthenticationException (401) The API key is wrong, was deleted, or its account is suspended.
PermissionException (403) The key lacks a permission, or the plan does not include the feature.
RateLimitException (429) Too many requests; getRetryAfter() says how many seconds to wait. A queued notification is retried by your queue.
ApiException Any other error answer, e.g. 400 for a number SMSTunnel cannot read or a verification text without a code, or 409 while the first try with the same Idempotency-Key is still running (see below).
TransportException SMSTunnel could not be reached.

A missing API key throws NotificationChannels\SmsTunnel\Exceptions\InvalidConfiguration; a notification without toSmsTunnel() throws CouldNotSendNotification.

Retrying safely

Every text goes out with an Idempotency-Key, a SHA-256 of the notification's id and everything SMSTunnel compares for a repeat: the number, the words, the phone, the country code and the kind of text. Laravel gives each notification its own id and keeps it when your queue retries the job, so for 24 hours a retry of the same text can't text the same number twice: SMSTunnel answers it with the first result (the same messageId), and the result's replayed is true. This works with no changes to your notifications.

A new notify() call is a new notification with a new id. To text once per order even when your app sends the notification twice, give the text your own key:

public function toSmsTunnel(object $notifiable): SmsTunnelMessage
{
    return SmsTunnelMessage::create("Your order #{$this->order->id} has shipped.")
        ->idempotencyKey("order-{$this->order->id}-shipped");
}

The channel then makes each number's key from yours, the number and the text.

  • A retry with other words is a new text, and goes out: a sign-in code made afresh in toSmsTunnel() sends the new code. To keep a retry from texting again, build the text from the notification's own data, not from the time it is sent.
  • NotificationSent's response (a SendResult) has replayed: true when SMSTunnel answered a retry with the first answer, so no new text went out.
  • A 409 (IDEMPOTENCY_KEY_IN_PROGRESS) means the first try is still running: the queue's next try gets its answer.
  • A server error (5xx) is kept with the key, because the text may have gone out before it: retries within 24 hours get the same error back. Check your dashboard before you send that text again.
  • withoutIdempotencyKey() sends the text without a key, as in 1.0: a retry can text the number again.
  • SMSTunnel remembers a key for 24 hours.

The client on its own

The package registers SmsTunnel\Client in the container, configured from services.smstunnel:

use SmsTunnel\Client;

$status = app(Client::class)->getMessageStatus($messageId); // needs sms:read
$phones = app(Client::class)->getDevices();

To send through your own HTTP client (proxy, logging), bind an SmsTunnel\Transport\TransportInterface in a service provider, for example a Psr18Transport. See the client's README.

Notes and limits

  • Rate limit: sending allows 30 requests a minute.
  • Length: up to 1600 characters; verification codes up to 320.
  • Offline phone: the text waits on your account and goes out when the phone is back online (SendResult::$queued is true).

Build it with an AI assistant

Paste this into Claude, ChatGPT, Cursor or Copilot and replace the part in brackets. Don't paste your API key into the chat: the prompt doesn't need it.

Help me send Laravel notifications as text messages with SMSTunnel.

About SMSTunnel (https://smstunnel.io): my own apps and tools hand text messages (SMS) to my
SMSTunnel account, and my own Android phone sends them from my own number, on my own SIM and plan.
The phone runs the SMSTunnel app from Google Play
(https://play.google.com/store/apps/details?id=io.smstunnel.app), signed in to my account.

What I want: [describe what should send a text, to whom, and when]

How it works:
- Install the notification channel: composer require smstunnel/smstunnel-laravel (Laravel 10 to 13,
  PHP 8.1+). The service provider registers itself and installs the PHP client
  smstunnel/smstunnel-php.
- config/services.php: 'smstunnel' => ['key' => env('SMSTUNNEL_API_KEY'), 'device_id' =>
  env('SMSTUNNEL_DEVICE_ID'), 'default_country_code' => env('SMSTUNNEL_DEFAULT_COUNTRY_CODE')]; the
  key goes in .env as SMSTUNNEL_API_KEY.
- In a notification, via() returns ['smstunnel'] and toSmsTunnel(object $notifiable) returns
  NotificationChannels\SmsTunnel\SmsTunnelMessage::create('...') or a plain string; message methods
  content(), deviceId(), defaultCountryCode(), verificationCode(), sendAt(), idempotencyKey(),
  withoutIdempotencyKey().
- The notifiable's routeNotificationForSmstunnel(Notification $notification): ?string returns the
  number in international format; null or '' skips it, a list gets one text per number. Not a user:
  Notification::route('smstunnel', '+14155550123')->notify(...).
- Sign-in codes: SmsTunnelMessage::create("Your sign-in code is {$code}")->verificationCode(); the
  text must contain the code as 4 to 10 digits (or 123-456), up to 320 characters.
- Scheduled texts: ->sendAt($dateTime) (1 minute to 30 days ahead, a DateTimeInterface or an ISO
  8601 string with an offset; built from the notification's data) and SMSTunnel sends it then;
  NotificationSent's response is then a SmsTunnel\Response\ScheduledText (->id for
  app(SmsTunnel\Client::class)->cancelScheduled($id)). Not for sign-in codes.
- Failures dispatch Illuminate\Notifications\Events\NotificationFailed (data: message, exception,
  to) and rethrow, all under SmsTunnel\Exception\SmsTunnelException: AuthenticationException 401,
  PermissionException 403, RateLimitException 429 (getRetryAfter()), ApiException (400, 5xx),
  TransportException (network). Use ShouldQueue so a queue retries. Every text goes out with an
  Idempotency-Key made from the notification's id, the number and the text, so for 24 hours a retry
  of the same text can't text a number twice (the result's ->replayed is true);
  ->idempotencyKey("order-{$order->id}-shipped") makes it from my own data instead. A retry with
  other words is a new text and goes out.
- defaultCountryCode (e.g. +44) completes numbers written without + or 00 and always takes
  precedence over the phone's own country setting. Texts up to 1600 characters; 30 send requests a
  minute. If the phone is offline, the text waits and goes out when it is back.
- The API key comes from my SMSTunnel dashboard (https://dashboard.smstunnel.io): Apps → Add an app
  → Create the key. It is shown only once and can send texts and check whether they went out.

Rules for your answer:
- Keep the API key in an environment variable or the platform's secret store (for example
  SMSTUNNEL_API_KEY). Never put it in source code, in a repository, or in code that runs in a
  browser or a mobile app: call SMSTunnel from a server. I will not paste my key in this chat; use a
  placeholder.
- Validate phone numbers before sending (international format, like +14155550123) and skip or report
  the invalid ones.
- Handle errors: log or show what went wrong. Let the queue retry a few times with a backoff, and
  build each text from the notification's data so a retry sends the same words.
- Only send texts people expect from me: alerts to myself, reminders, sign-in codes, updates they
  asked for. No unsolicited texts.

Responsible use

Send only texts that people expect from you: alerts to yourself, appointment reminders, sign-in codes, order updates. Unsolicited messages from a personal SIM break most carriers' terms of service. Please make sure your usage complies with your carrier's terms and with local regulations (in the EU, that includes GDPR and ePrivacy rules on electronic communications).

Changelog

Please see CHANGELOG for what has changed recently.

Testing

composer test
composer analyse       # PHPStan, level max
composer format:check  # Pint

The end-to-end tests run only against a test server, never production:

SMSTUNNEL_E2E=1 SMSTUNNEL_BASE_URL=http://127.0.0.1:3101 SMSTUNNEL_API_KEY=... composer test:e2e

Security

If you discover a security issue, please email contact@narboweb.ro instead of opening an issue.

Credits

This package is not affiliated with, endorsed by, or sponsored by Laravel or its owners. Laravel is a trademark of its respective owner.

License

The MIT License (MIT), © NARBOWEB SRL. Please see License File for more information.