przypominamy

Oficjalny klient API SMS przypominamy.com dla Pythona ≥ 3.9. Zero zależności (standardowa biblioteka).

Polska bramka SMS: jeden endpoint do wysyłki, historia, saldo, własny nadpis, webhooki podpisane HMAC. Pay-as-you-go, bez abonamentu.

pip install przypominamy

Szybki start

import os
from przypominamy import Przypominamy

sms = Przypominamy(os.environ["PRZYPOMINAMY_API_KEY"])  # pk_live_…

msg = sms.send(
    "+48600100200",
    "Przypominamy o wizycie jutro o 10:00.",
    reference="wizyta-4711",          # Twój identyfikator, wraca w webhookach
    idempotency_key="wizyta-4711-1",  # retry nie wyśle SMS-a drugi raz
)
print(msg["id"], msg["status"], msg["cost_grosze"])  # msg_… queued 9

Klucz API dostaniesz po założeniu konta na przypominamy.com/register (weryfikacja w 24 h).

Wysyłka masowa i odroczona

from datetime import datetime, timezone

batch = sms.send(["+48600100200", "+48600100201"], "Promocja -20% do niedzieli. Kod: SMS20", sender="SKLEP")
print(batch["accepted"], "z", batch["count"], "przyjęto, koszt", batch["total_cost_grosze"] / 100, "zł")

sms.send("+48600100200", "Wizyta dziś o 14:00.", send_at=datetime(2026, 9, 18, 8, 0, tzinfo=timezone.utc))

Status, historia, konto

m = sms.get("msg_qY08hZ2mmDXAazdRTytS")
page = sms.list(status="delivered", limit=50)       # page["data"], page["next_cursor"]
for m in sms.iter_messages(reference="wizyta-4711"):  # cała historia, strona po stronie
    print(m["id"], m["status"])
acc = sms.account()                                   # acc["balance_grosze"], acc["price_per_part_grosze"]
print(sms.senders()["data"])
sms.set_sender("ZDROWKO")

Webhooki

secret = sms.set_webhook("https://twojadomena.pl/webhooks/sms")["webhook_secret"]

Handler we Flasku:

from flask import Flask, request, abort
from przypominamy import verify_webhook

app = Flask(__name__)

@app.post("/webhooks/sms")
def sms_webhook():
    try:
        event = verify_webhook(request.get_data(), request.headers.get("X-Przypominamy-Signature"), WEBHOOK_SECRET)
    except ValueError:
        abort(403)
    # event["type"]: message.sent | message.delivered | message.undelivered | message.failed | message.expired
    msg = event["data"]["message"]
    print(event["type"], msg["id"], msg["reference"])
    return "", 200

Błędy

Każdy błąd API to PrzypominamyError z polami status, code (invalid_request, unauthorized, insufficient_funds, rate_limited, idempotency_conflict, provider_error…), param, request_id i retry_after.

from przypominamy import PrzypominamyError
try:
    sms.send("+48600100200", "Hej")
except PrzypominamyError as e:
    if e.code == "rate_limited":
        time.sleep(e.retry_after or 5)

Dokumentacja

• Strona API · Redoc · OpenAPI 3.1
• Wsparcie: support@przypominamy.com

MIT