SMSTunnel for Python

pip install smstunnel

import os
import smstunnel

client = smstunnel.Client(os.environ["SMSTUNNEL_API_KEY"])  # sk_live_...

result = client.send_sms("+14155550123", "Your order #1042 has shipped.")

print(result.message_id)  # keep it to look up the status later

result = client.send_sms(
    "+14155550123",               # international format
    "See you at 10:30.",          # up to 1600 characters
    device_id=None,               # a phone id from get_devices(), or None to let SMSTunnel pick one of yours
    default_country_code=None,    # e.g. "+40": completes numbers given without + or 00
)

result.message_id  # str
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": 95} (clean -1 and total "unlimited": no limit)

client.send_verification_code("+14155550123", "Your sign-in code is 482913")

from smstunnel import MessageStatus

status = client.get_message_status(result.message_id)

status.status           # "pending", "sent", "delivered" or "failed"
status.delivery_status  # the same, or "unconfirmed": handed to the SIM but the phone got no confirmation
status.sent_at          # a datetime (UTC), or None
status.error_message    # why it failed, or None
status.is_final         # True once it will not change any more

if status.status == MessageStatus.FAILED:
    ...

from datetime import datetime, timedelta, timezone

page = client.get_received_messages(
    limit=20,                                            # at most 100
    page=1,
    since=datetime.now(timezone.utc) - timedelta(days=1),  # or an ISO 8601 string
    phone="+14155550123",                                # only from this sender
    device_id=None,                                      # only this phone
)

for text in page:
    print(text.sender, text.message)  # text.received_at, text.device_name, ...

page.total     # all texts that match, on every page
page.has_more  # ask for the next page

for phone in client.get_devices():
    print(phone.name, "online" if phone.is_online else "offline")  # phone.id, phone.last_seen_at

usage = client.get_usage()
usage.plan       # e.g. "standard"
usage.usage      # {"smsClean": 15, "smsBranded": 0, "twoFaClean": 4}
usage.remaining  # {"smsClean": 1985, "twoFaClean": "unlimited"}

import asyncio
import os

import smstunnel


async def main() -> None:
    async with smstunnel.AsyncClient(os.environ["SMSTUNNEL_API_KEY"]) as client:
        await client.send_sms("+14155550123", "Your table is ready.")


asyncio.run(main())

import logging
import time

from smstunnel import ApiError, RateLimitError, TransportError

try:
    client.send_sms("+14155550123", "Your table is ready.")
except RateLimitError as error:
    if error.retry_after:
        time.sleep(error.retry_after)  # then try again
    else:
        ...  # the plan's limit for the day or month is reached: no retry until then
except ApiError as error:
    logging.warning("SMSTunnel %s %s: %s", error.status_code, error.error_code or "-", error.message)
except TransportError:
    ...  # no answer: after a timeout the text may still go out, so check before you send it again

# settings.py
import os

SMSTUNNEL_API_KEY = os.environ.get("SMSTUNNEL_API_KEY", "")

# shop/sms.py
from functools import cache

import smstunnel
from django.conf import settings


@cache
def sms() -> smstunnel.Client:
    return smstunnel.Client(settings.SMSTUNNEL_API_KEY)

# shop/views.py
import logging

from django.db import transaction
from django.shortcuts import get_object_or_404, redirect

from smstunnel import SmsTunnelError

from .models import Order
from .sms import sms

log = logging.getLogger(__name__)


def text_customer(order: Order) -> None:
    try:
        sms().send_sms(order.phone, f"Your order #{order.pk} has shipped.")
    except SmsTunnelError:
        log.exception("The shipping text for order %s did not go out", order.pk)


def mark_shipped(request, pk):
    order = get_object_or_404(Order, pk=pk)
    order.status = "shipped"
    order.save()
    transaction.on_commit(lambda: text_customer(order))
    return redirect("order-detail", pk=pk)

import os

from flask import Flask, abort, request
from smstunnel import Client, SmsTunnelError

app = Flask(__name__)
app.config["SMSTUNNEL_API_KEY"] = os.environ["SMSTUNNEL_API_KEY"]
sms = Client(app.config["SMSTUNNEL_API_KEY"])


@app.post("/appointments/<int:appointment_id>/remind")
def remind(appointment_id: int):
    phone = request.form.get("phone", "")
    if not phone.startswith("+"):
        abort(400, "Give the number in international format, e.g. +14155550123.")
    try:
        result = sms.send_sms(phone, "Reminder: your appointment is tomorrow at 10:30.")
    except SmsTunnelError as error:
        app.logger.warning("SMSTunnel: %s", error)
        return {"sent": False}, 502
    return {"sent": True, "messageId": result.message_id}

import ssl

from smstunnel import Client
from smstunnel.transport import UrllibTransport

client = Client(api_key, timeout=10, transport=UrllibTransport(ssl_context=ssl.create_default_context(cafile="ca.pem")))

import httpx
from smstunnel import AsyncClient, Client
from smstunnel.transport import AsyncHttpxTransport, HttpxTransport

client = Client(api_key, transport=HttpxTransport(httpx.Client(proxy="http://proxy.internal:3128")))
async_client = AsyncClient(api_key, transport=AsyncHttpxTransport(httpx.AsyncClient()))