Search by

smstunnel / smstunnel-php

narcisbodea

PHP client for SMSTunnel: send texts from your own apps through your own Android phone, from your own number.

v1.2.1 2026-11-21 09:08 UTC

This package is auto-updated.

Last update: 2026-11-21 09:49:56 UTC


README

smstunnel/smstunnel-php: a small PHP client for SMSTunnel. Send texts from your own PHP apps through your own Android phone, from your own number.

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

Using Laravel? smstunnel/smstunnel-laravel builds on this package, so $user->notify(new OrderShipped) sends the text from your phone.

Requirements

  • PHP 8.1 or newer
  • the curl extension (most PHP installs have it), or any PSR-18 HTTP client (see Your own HTTP client)

No other dependencies.

Installation

composer require smstunnel/smstunnel-php

Get an API key

  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. Reading received texts only works with a key you have explicitly allowed to (Can also read received texts, the sms:inbox permission, a separate opt-in per key). Syncing received texts is off by default in the app; when you turn it on, only texts that arrive from then on are synced, and the phone's existing messages are never read.

Keep the key out of your code: put it in an environment variable such as SMSTUNNEL_API_KEY.

Usage

use SmsTunnel\Client;

$client = new Client((string) getenv('SMSTUNNEL_API_KEY')); // sk_live_...

$result = $client->sendSms('+14155550123', 'Your order #1042 has shipped.');

echo $result->messageId; // keep it to look up the status later

Send a text

$result = $client->sendSms(
    to: '+14155550123',            // international format
    message: 'See you at 10:30.',  // up to 1600 characters
    deviceId: null,                // a phone id from getDevices(), or null to let SMSTunnel pick one of yours
    defaultCountryCode: null,      // e.g. '+40': completes numbers given without + or 00
    idempotencyKey: null,          // e.g. 'order-1042-shipped': a retry with the same key can't send it twice
);

$result->messageId; // string
$result->queued;    // true when the phone was offline: it sends the text as soon as it is back
$result->branded;   // true when the text carries a short SMSTunnel signature (plans with a free quota)
$result->remaining; // today's quota left, e.g. ['clean' => 95, 'total' => 'unlimited'] (-1 means no limit)

One call sends one text to one number. To text several people, call sendSms() once for each.

Send a sign-in or verification code

$client->sendVerificationCode('+14155550123', 'Your sign-in code is 482913');

The text must contain the code, 4 to 10 digits (for example 482913 or 123-456); SMSTunnel refuses it otherwise. Codes count against a separate quota, and the text can be up to 320 characters.

Scheduled texts

Give sendSms() a sendAt, 1 minute to 30 days ahead: SMSTunnel keeps the text and hands it to your phone at that time. The call then returns a SmsTunnel\Response\ScheduledText instead of a SendResult.

$text = $client->sendSms(
    '+14155550123',
    'Reminder: your appointment is tomorrow at 10:30.',
    sendAt: new DateTimeImmutable('2026-11-16 09:00', new DateTimeZone('Europe/Bucharest')),
);

$text->id;     // keep it to look the text up or cancel it
$text->sendAt; // '2026-11-16T07:00:00.000Z' (UTC)
$text->status; // 'scheduled', later 'sent', 'failed' (see $text->error) or 'canceled'

$client->listScheduled();            // what still waits, soonest first; listScheduled('done') for the rest
$client->getScheduled($text->id);    // ->messageId once it went out, for getMessageStatus()
$client->cancelScheduled($text->id); // while it still waits
  • sendAt is a DateTimeInterface, sent with its own offset (so make it in the time zone you mean), or an ISO 8601 string with an offset, such as 2026-11-16T09:00:00+02:00 or 2026-11-16T07:00:00Z. A string without an offset throws \InvalidArgumentException before anything is sent.
  • At that time SMSTunnel sends the text as if your app called sendSms() then, with the same API key: it picks the phone then (unless you named one), and the text counts toward that day's allowance. If the phone is offline, the text waits for it up to 3 days.
  • Plain texts only: sign-in codes can't be scheduled.
  • idempotencyKey works as for any send. Keep the same sendAt on every retry: another time with the same key is refused (422).
  • A key lists, reads and cancels only the texts it scheduled. Listing and reading need sms:read, cancelling sms:send.
  • Refusals keep SMSTunnel's code in getErrorCode(): ApiException 400 SCHEDULE_TOO_SOON or SCHEDULE_TOO_FAR (and the other SCHEDULE_* codes), 404 SCHEDULE_NOT_FOUND, 409 SCHEDULE_NOT_EDITABLE (it already went out or was canceled), and PermissionException 403 SCHEDULE_LIMIT_REACHED when as many texts wait as your plan allows (getBody()['max']: 10 on Free, 50 Starter, 200 Standard, 500 Professional, 1000 Enterprise). listScheduled() also says how many wait in your account (->waiting) and the cap (->max).

Look up a status

Needs a key with sms:read.

use SmsTunnel\Response\MessageStatus;

$status = $client->getMessageStatus($result->messageId);

$status->status;         // 'pending', 'sent' or 'failed'
$status->deliveryStatus; // the same, or 'unconfirmed': handed to the SIM but the phone got no confirmation
$status->sentAt;         // ISO 8601, or null
$status->errorMessage;   // why it failed, or null
$status->isFinal();      // true once there is nothing more to wait for: sent, delivered, failed or unconfirmed

if ($status->status === MessageStatus::FAILED) {
    // ...
}

sent is the last good status today: the SMSTunnel app gets no delivery reports, so a text that went out stays sent. delivered is reserved.

Read received texts

Needs a key you allowed to read received texts (sms:inbox) and syncing turned on in the app.

$page = $client->getReceivedMessages([
    'limit' => 20,                                     // at most 100
    'page' => 1,
    'since' => new DateTimeImmutable('-1 day'),        // or an ISO 8601 string
    'phone' => '+14155550123',                         // only from this sender
    'deviceId' => null,                                // only this phone
]);

foreach ($page as $text) {
    echo $text->sender, ': ', $text->message, PHP_EOL; // $text->receivedAt, $text->deviceName, ...
}

$page->total;   // all texts that match, on every page
$page->hasMore; // ask for the next page

Your phones and your usage

foreach ($client->getDevices() as $phone) {
    echo $phone->name, $phone->isOnline ? ' (online)' : ' (offline)', PHP_EOL; // $phone->id, $phone->lastSeenAt
}

$usage = $client->getUsage();
$usage->plan;      // e.g. 'pro'
$usage->usage;     // ['smsClean' => 15, 'smsBranded' => 0, 'twoFaClean' => 4]
$usage->remaining; // ['smsClean' => 'unlimited', 'twoFaClean' => 96]

Every response object also has $raw, the whole answer, for fields this version does not map yet.

Errors

Every call throws a SmsTunnel\Exception\SmsTunnelException when it does not go through:

Exception When
AuthenticationException (401) The API key is wrong, was deleted, or its account is suspended.
PermissionException (403) The key lacks a permission (getErrorCode() is PERMISSION_REQUIRED, getPermission() names it, e.g. sms:inbox), or the plan does not include the feature.
RateLimitException (429) Too many requests. getRetryAfter() gives the seconds to wait, when SMSTunnel says.
ApiException Any other error answer: 400 (a number it cannot read, a verification text without a code), 404 (no such message), 409 and 422 for an idempotencyKey (see Retrying safely), 5xx. The three above extend it.
TransportException SMSTunnel could not be reached (DNS, TLS, timeout).
use SmsTunnel\Exception\ApiException;
use SmsTunnel\Exception\RateLimitException;
use SmsTunnel\Exception\TransportException;

try {
    $client->sendSms('+14155550123', 'Your table is ready.');
} catch (RateLimitException $e) {
    // wait $e->getRetryAfter() seconds and try again
} catch (ApiException $e) {
    error_log(sprintf('SMSTunnel %d %s: %s', $e->getStatusCode(), $e->getErrorCode() ?? '-', $e->getMessage()));
} catch (TransportException $e) {
    // network problem: try again later
}

getMessage() is SMSTunnel's own explanation, getStatusCode() (also getCode()) the HTTP status, getBody() the decoded answer, and getRetryAfter() the seconds to wait when SMSTunnel says. An empty number or text throws \InvalidArgumentException before anything is sent.

Retrying safely

The client never retries on its own. To retry a text without risking a second copy, give the send an idempotencyKey: one new key per text, and the same key on every retry of that text. It goes out as the Idempotency-Key header, and for 24 hours SMSTunnel answers a repeat with its first answer (the same messageId) instead of sending the text again.

use SmsTunnel\Exception\ApiException;
use SmsTunnel\Exception\TransportException;

$key = bin2hex(random_bytes(16)); // or your own id for this text, e.g. 'order-1042-shipped'

for ($attempt = 1; $attempt <= 3; ++$attempt) {
    try {
        $result = $client->sendSms('+14155550123', 'Your order #1042 has shipped.', idempotencyKey: $key);
        break;
    } catch (TransportException $e) {
        $wait = 2; // no answer came, so the text may or may not have gone out: try again with the same key
    } catch (ApiException $e) {
        $wait = $e->getRetryAfter(); // 429 too many requests, or 409 while the first try is still running
    }
    if ($wait === null || $attempt === 3) {
        throw $e; // a refusal (the same call would be refused again), or the last try
    }
    sleep($wait);
}
  • sendVerificationCode() takes idempotencyKey too.
  • $result->replayed is true when SMSTunnel answered with the first answer (its Idempotent-Replayed header): that call sent no new text.
  • The same key with a different text, number, phone or country code gets an ApiException with status 422 and getErrorCode() IDEMPOTENCY_KEY_REUSED, and nothing goes out.
  • A refusal (4xx) means nothing went out: fix the cause, then retry with the same key. A server error (5xx) is kept with the key, because the text may have gone out before it: a retry gets the same error back. Check your dashboard before you send that text again with a new key.
  • A key is 1 to 255 printable ASCII characters, without spaces at the ends. Anything else throws \InvalidArgumentException before anything is sent.
  • SMSTunnel remembers a key for 24 hours: a retry after that sends the text again.

Your own HTTP client

The built-in transport uses curl with a 30-second timeout and never follows redirects. Change the timeouts, or add curl options such as a proxy:

use SmsTunnel\Transport\CurlTransport;

$client = new Client($apiKey, transport: new CurlTransport(timeout: 10, connectTimeout: 5, curlOptions: [
    CURLOPT_PROXY => 'http://proxy.internal:3128',
]));

Or send through any PSR-18 client (Guzzle, Symfony HttpClient, ...) so SMSTunnel calls share your app's HTTP setup:

use SmsTunnel\Transport\Psr18Transport;

$factory = new GuzzleHttp\Psr7\HttpFactory(); // a PSR-17 request and stream factory
$client = new Client($apiKey, transport: new Psr18Transport(new GuzzleHttp\Client(), $factory, $factory));

In your own tests, implement SmsTunnel\Transport\TransportInterface (one method) to answer without a network, or mock SmsTunnel\Client.

new Client($apiKey, 'https://your-own-host') points the client at a self-hosted SMSTunnel; the default is https://smstunnel.io.

Notes and limits

  • Rate limit: sending allows 30 requests a minute.
  • Length: up to 1600 characters (10 joined SMS); verification codes up to 320.
  • Numbers: use the international format (+14155550123). For local numbers, pass defaultCountryCode: it always takes precedence (+49, 49 and 0049 all work).
  • Offline phone: the text waits on your account (queued is true) and goes out when the phone is back online.

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 text messages from my PHP app 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:
- Use the official client: composer require smstunnel/smstunnel-php (PHP 8.1+, the curl extension or
  any PSR-18 client; no other dependencies).
- $client = new \SmsTunnel\Client((string) getenv('SMSTUNNEL_API_KEY'));
- $result = $client->sendSms(to: '+14155550123', message: '...', deviceId: null, defaultCountryCode:
  null, idempotencyKey: null); returns ->messageId, ->queued (true: the phone is offline and the text
  goes out when it is back), ->branded, ->remaining. One call sends one text to one number: loop for
  several.
- Retries: the client never retries on its own. idempotencyKey (one new key per text, such as
  bin2hex(random_bytes(16)), the same on every retry of that text) makes a retry within 24 hours get
  the first answer back instead of sending a second text. The same key with a different text is
  refused: ApiException 422, getErrorCode() IDEMPOTENCY_KEY_REUSED.
- Scheduled texts: sendSms(..., sendAt: new DateTimeImmutable('2026-11-16 09:00', new
  DateTimeZone('Europe/Bucharest'))), 1 minute to 30 days ahead (a DateTimeInterface, or an ISO 8601
  string with an offset), returns a ScheduledText (->id, ->sendAt, ->status) instead of a
  SendResult; $client->listScheduled(), getScheduled($id), cancelScheduled($id). Not for sign-in
  codes.
- Sign-in codes: $client->sendVerificationCode('+14155550123', 'Your sign-in code is 482913'); the
  text must contain the code as 4 to 10 digits (or 123-456) and can be up to 320 characters. Codes
  have their own daily allowance.
- $client->getMessageStatus($messageId): ->status ('pending', 'sent' or 'failed'; 'sent' is the last good status, there are no delivery reports),
  ->deliveryStatus ('unconfirmed' = handed to the SIM without a confirmation, probably sent: never
  resend it automatically), ->errorMessage, ->isFinal().
- Exceptions, all extending SmsTunnel\Exception\SmsTunnelException: AuthenticationException (401),
  PermissionException (403; getErrorCode() is PERMISSION_REQUIRED, getPermission()),
  RateLimitException (429; getRetryAfter()), ApiException (other errors: 400 bad number or code text
  without a code, 404, 5xx; getStatusCode(), getErrorCode(), getMessage()), TransportException
  (network). An empty number or text throws \InvalidArgumentException.
- Numbers in international format. 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.
- 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. Retry only after a network error or when
  getRetryAfter() says when (429, 409), a few times at most, always with the same idempotencyKey,
  so the same text never goes out twice.
- 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).

Development

composer install
composer test      # PHPUnit
composer analyse   # PHPStan, level max
composer cs        # PSR-12 check (composer cs:fix to fix)

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

Changelog

See CHANGELOG.md.

License

MIT, © NARBOWEB SRL. See LICENSE.