API SMS dla polskich firm - REST, JSON, Bearer token
Wyślij SMS przez POST /v1/messages: jeden numer, tablica do 500 albo grupa kontaktów. Saldo prepaid, stawka od 0,10 zł za część po doładowaniu od 500 zł, webhook DLR z HMAC. Odbiór odpowiedzi (2-way) włączamy na życzenie; na alfanumeryczny nadpis nie da się odpisać.
Co chcesz osiągnąć?
Pierwszy SMS: konto i curl
Rejestracja na app.przypominamy.com daje od razu pk_test_… i 25 SMS na dwa zweryfikowane numery. Poniżej demo bez konta albo trzy kroki z własnym kluczem.
Wyślij testowego SMS-a na swój numer. Bez konta.
Wpisz polski numer komórkowy. Za chwilę dostaniesz SMS, a poniżej zobaczysz dokładnie to żądanie i odpowiedź, które wykonałby Twój kod. Jeden test na numer dziennie.
Tyle. Załóż konto, a dostaniesz klucz i 25 SMS-ów gratis na własne numery.
Załóż konto
Rejestracja na /register trwa minutę. Konto testowe z 25 SMS-ami i klucz pk_test_… działają od razu, bez ręcznej weryfikacji konta. Wysyłka testowa wymaga potwierdzenia własnego numeru kodem.
Odbierz klucz
W panelu (Klucze) generujesz pk_test_… od razu; pk_live_… po pierwszym doładowaniu. Klucz widzisz tylko raz: zapisz go w menedżerze sekretów.
Wyślij SMS
Wykonaj jeden POST na /v1/messages z numerem i treścią.
curl -X POST https://api.przypominamy.com/v1/messages \
-H "Authorization: Bearer $PRZYPOMINAMY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"to": "+48600123456",
"text": "Cześć! Przypominamy o wizycie jutro o 14:00.",
"from": "FIRMA",
"reference": "wizyta-4711"
}'
# 201 Created
{
"id": "msg_qY08hZ2mmDXAazdRTytS",
"status": "queued",
"to": "+48600123456",
"from": "FIRMA",
"parts": 1,
"cost_grosze": 10,
"reference": "wizyta-4711",
...
}Jeden endpoint do wysyłki. Reszta to konto i historia.
Bez SOAP-u, bez tysiąca opcji konfiguracyjnych. Pełna specyfikacja w Redoc i openapi.json.
Wyślij SMS
Jeden numer, tablica do 500 numerów lub grupa kontaktów (group:VIP) z personalizacją {{imie}}. Nadpis, wysyłka odroczona do 90 dni, okno godzin send_window, ważność expires_at, link wypisu {{opt_out}}, śledzony link {{link:https://…}}, Idempotency-Key. Treść z szablonu (template_id + params) i SMS priorytetowy (priority: true, osobna kolejka, 2× stawka).
Anuluj zaplanowaną wysyłkę
Do 30 s przed terminem. Status cancelled, koszt wraca na saldo.
Historia wiadomości
Paginacja kursorem, filtry po statusie, numerze i reference. Do 200 na stronę.
Status wiadomości
Pełny rekord: status doręczenia, liczba części, koszt, czas doręczenia, powód odrzucenia.
Saldo i cennik
Saldo w groszach, cena za część SMS i za HLR, limit kredytowy, model rozliczenia (billing_mode), aktualny nadpis, okno godzin wysyłki i zakresy klucza (scopes).
Nadpisy
Lista aktywnych nazw nadawcy. Domyślną ustawisz przez PATCH /v1/account.
Webhook
Ustaw adres https i odbierz sekret HMAC. Zdarzenia przy każdej zmianie statusu, 3 próby dostarczenia.
Czarna lista i opt-out
Numery, na które nie wysyłasz: dodane przez API albo przez osobisty link {{opt_out}} z SMS-a. Wysyłka na taki numer = status rejected, koszt 0.
Kontakty i grupy
Książka odbiorców z polami własnymi, import tablicą do 500, grupy (/v1/groups). Wysyłka na grupę z {{imie}}, {{nazwisko}}, {{pole}}.
Szablony
Te same szablony co w panelu, z placeholderami {{klucz}}. Tworzysz przez POST, wysyłasz podając template_id i params zamiast treści.
Sprawdź numer (HLR)
Czy numer jest aktywny i w jakiej sieci - bez wysyłania SMS-a. Status active / inactive, operator, przeniesienie. 0,05 zł, ten sam numer w ciągu 24 h bez opłaty.
Śledzone linki i kliknięcia
Wstaw {{link:https://…}} w treści - każdy odbiorca dostaje własny krótki link api.przypominamy.com/l/…. Kto kliknął, ile razy i kiedy: tu, w links[] wiadomości i webhookiem link.clicked. Bez dopłaty.
Odpowiedzi odbiorców (2-way)
SMS-y przychodzące na numer odbiorczy: po Twoim słowie kluczowym (inbound_prefix) albo jako odpowiedź na Twoją wysyłkę (reply_to). STOP trafia na czarną listę. Uruchamiamy na życzenie - po włączeniu numeru odbiorczego dla konta.
Autoryzacja: Bearer token
Każde żądanie wymaga nagłówka Authorization: Bearer <klucz>. Klucz generujesz sam w panelu, od razu po rejestracji.
curl https://api.przypominamy.com/v1/account \
-H "Authorization: Bearer pk_live_a1b2c3d4..."
{ "balance_grosze": 4982, "price_per_part_grosze": 9,
"sender_name": "FIRMA", "status": "active", ... }- Klucz
pk_test_…generujesz w panelu od razu po rejestracji;pk_live_…po pierwszym doładowaniu od 50 zł. Pokazujemy go raz. Zakresy: send, read, manage. - Przechowujemy tylko skrót klucza. Jeśli wycieknie, napisz do nas - odwołamy go natychmiast i wydamy nowy.
- Nie wspieramy Basic Auth ani klucza w query string. Tylko Bearer.
- Kluczy nie ograniczamy per-IP - używaj tej samej wartości z dowolnego środowiska.
Webhooki: statusy, odpowiedzi i kliknięcia z podpisem HMAC
Ustaw adres przez PUT /v1/account/webhook, a przy każdej zmianie statusu, odpowiedzi odbiorcy i pierwszym kliknięciu śledzonego linku dostaniesz POST application/json. Odpowiedz 2xx - inaczej ponawiamy (3 próby).
📥 Zdarzenia
Statusy: message.sent, message.delivered, message.undelivered, message.failed, message.expired - w data.message pełny rekord wiadomości razem z Twoim reference. Odpowiedź odbiorcy: message.received (data.inbound z from, text, reply_to; data.opt_out: true, gdy STOP dopisało numer do czarnej listy). Pierwsze kliknięcie śledzonego linku: link.clicked (data.link z to, url, clicks i data.clicked_at).
{
"id": "evt_8sK2mQ…",
"type": "message.delivered",
"created_at": "2026-09-07T07:12:40.000Z",
"data": {
"message": {
"id": "msg_qY08hZ2mmDXAazdRTytS",
"status": "delivered",
"to": "+48600123456",
"reference": "wizyta-4711",
"delivered_at": "2026-09-07T07:12:38.000Z",
...
}
}
}🔏 Weryfikacja podpisu
Nagłówek X-Przypominamy-Signature: t=<unix>,v1=<hex>, gdzie v1 = HMAC-SHA256(webhook_secret, "<t>.<body>"). Odrzucaj, gdy podpis się nie zgadza albo t jest starsze niż 5 minut.
const crypto = require('crypto');
const h = req.headers['x-przypominamy-signature'];
const t = h.match(/t=(\d+)/)[1];
const sig = h.match(/v1=([0-9a-f]+)/)[1];
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(`${t}.${rawBody}`)
.digest('hex');
const ok = crypto.timingSafeEqual(
Buffer.from(sig), Buffer.from(expected));
if (!ok || Math.abs(Date.now()/1000 - t) > 300)
return res.status(403).end();Limity i kody błędów
API używa standardowych kodów HTTP. Wszystkie błędy zwracają JSON: {"error":{"code":"insufficient_funds","message":"…","param":"to"},"request_id":"req_…"}. Każda odpowiedź ma nagłówek X-Request-Id.
Rate limit
Limit per konto. Do kampanii użyj tablicy to (do 500 numerów w jednym żądaniu). Po przekroczeniu HTTP 429 z nagłówkiem Retry-After.
Wyższe limity dostępne - napisz na [email protected].
| Kod | Znaczenie |
|---|---|
| 400 | invalid_request - błąd walidacji, pole w param |
| 401 | unauthorized - brak, nieprawidłowy lub odwołany klucz |
| 402 | insufficient_funds - niewystarczające środki |
| 403 | forbidden - konto zawieszone lub zamknięte |
| 409 | idempotency_conflict - ten sam Idempotency-Key, inna treść |
| 422 | invalid_request - odrzucone przez dostawcę (numer, nadpis) |
| 429 | rate_limited - przekroczono limit, patrz Retry-After |
| 502 / 504 | provider_error - błąd lub timeout dostawcy SMS |
Cennik API: pay-as-you-go
API dostępne w każdym progu. Kwota doładowania ustala stawkę za część SMS i zostaje na stałe - każde większe doładowanie obniża ją. Minimalne doładowanie 50 zł. Ceny netto za jedną część SMS do Polski, prepaid, bez abonamentu. Te same stawki obowiązują na całej platformie.
- Stawka na stałe, nigdy nie rośnie
- Wszystkie endpointy API, SDK, MCP
- Webhooki statusów (HMAC)
- Śledzone linki bez dopłaty
- Rate limit 120 req/min
- Stawka na stałe, nigdy nie rośnie
- Wszystkie endpointy API, SDK, MCP
- Webhooki statusów (HMAC)
- Śledzone linki bez dopłaty
- Rate limit 120 req/min
- Stawka na stałe, nigdy nie rośnie
- Wszystkie endpointy API, SDK, MCP
- Webhooki statusów (HMAC)
- Śledzone linki bez dopłaty
- Rate limit 120 req/min
- Stawka na stałe, nigdy nie rośnie
- Wszystkie endpointy API, SDK, MCP
- Webhooki statusów (HMAC)
- Śledzone linki bez dopłaty
- Rate limit 120 req/min
Enterprise - powyżej 50 tys. SMS/mies.: stawka indywidualna od 0,10 zł, faktura miesięczna i limit kredytowy (postpaid na życzenie, po weryfikacji), dedykowane numery także odbiorcze (2-way), SLA, custom rate limits, dedykowany opiekun. Zapytaj o ofertę.
Ceny dotyczą SMS-ów wysyłanych do Polski. SMS priorytetowy (priority: true) to 2× stawka za część; sprawdzenie numeru HLR 0,05 zł. MMS i wiadomości głosowe wycenione osobno - pełen cennik na życzenie. SMS zagraniczny: 2× krajowa stawka konta za część netto. Kraje UE są aktywne; pozostałe kierunki po potwierdzeniu dostępności. Konto testowe: 25 SMS-ów gratis. Pełny cennik i kalkulator: /cennik.
Konto testowe od razu, weryfikacja przed produkcją
Klucz pk_test_ i 25 darmowych SMS-ów na własne, zweryfikowane numery dostajesz natychmiast po rejestracji. Wysyłka do dowolnych numerów rusza po pierwszym doładowaniu, a przy nietypowym ruchu sprawdzamy konto ręcznie. To celowy wybór, nie ograniczenie techniczne.
Antyfraud
Konto testowe wysyła tylko na numery potwierdzone kodem SMS, a wysyłki produkcyjne wymagają doładowania i danych firmy. To odcina phishing i spam, zanim trafią do sieci operatorów.
Reputacja nadawcy
Operatorzy filtrują numery, z których wychodzi spam. Konto testowe i pierwsze doładowanie ograniczają nadużycia, więc legalny ruch transakcyjny nie miesza się z masowym phishingiem na tej samej trasie.
Ludzkie wsparcie
Na [email protected] i pod telefonem odpowiadają osoby, które piszą gateway i panel. Przy nietypowej wysyłce lub migracji z innej bramki podpowiemy nadpis, treść i częstotliwość.
SDK i integracje no-code
Oficjalne paczki dla Node.js i Pythona, klasa klienta dla PHP, a dla no-code moduł HTTP w Zapierze, Make i n8n.
npm install przypominamy - TypeScript, zero zależności, działa też w Deno, Bun i Cloudflare Workers.pip install przypominamy - standardowa biblioteka, Python 3.9+, weryfikacja webhooków.wp_remote_post.mcp.przypominamy.com/mcp, ten sam klucz Bearer, wysyłka po potwierdzeniu.codex mcp add, config.toml, polecenia po polsku, klucze o zawężonym zakresie.Najczęstsze pytania o API
Jak zdobyć klucz API?
Załóż konto na /register - działa od razu, bez ręcznej weryfikacji. W panelu (Klucze) generujesz klucz pk_test_… natychmiast, z 25 SMS-ami gratis na 2 własne numery; po pierwszym doładowaniu od 50 zł wydajesz klucz pk_live_…. Klucz jest pokazywany raz i może mieć zakresy send/read/manage. Webhook ustawiasz sam w panelu albo przez PUT /v1/account/webhook.
Czy macie sandbox lub środowisko testowe?
Tak, w innej formie niż anonimowy sandbox: po rejestracji dostajesz od razu klucz pk_test_ i 25 darmowych SMS-ów na maksymalnie 2 własne numery potwierdzone kodem. Ten sam kod, te same endpointy i statusy co na produkcji. Wysyłkę do dowolnych numerów odblokowuje pierwsze doładowanie (od 50 zł); nietypowy ruch sprawdzamy ręcznie.
Jaki jest limit zapytań?
120 żądań na minutę per konto. Po przekroczeniu API zwraca HTTP 429 z nagłówkiem Retry-After. Do wysyłki masowej użyj tablicy to - do 500 numerów w jednym żądaniu liczy się jako jedno wywołanie.
Jak działa rozliczenie?
Prepaid. Każda wysyłka obciąża saldo w groszach według ceny za część SMS ustalonej dla Twojego konta (price_per_part_grosze w GET /v1/account). Części liczymy jak operatorzy: 160 znaków bez polskich znaków, 70 z polskimi; SMS priorytetowy liczy się podwójnie, sprawdzenie numeru HLR kosztuje 0,05 zł. Przy braku środków dostajesz 402 i nic nie jest wysyłane. Prepaid to domyślny i zalecany model; firmom po weryfikacji włączamy na życzenie rozliczenie miesięczne (postpaid: limit kredytowy, zestawienie 1. dnia miesiąca, 14 dni na przelew - pole billing_mode w GET /v1/account).
Czym różnicicie się od innych dostawców API SMS?
Jesteśmy nastawieni na małe i średnie firmy: pay-as-you-go od 50 zł, bez abonamentu i minimalnych zobowiązań. Konto testowe z 25 SMS-ami i klucz API od razu po rejestracji, bez czekania na weryfikację. Serwer MCP dla asystentów AI, natywny node n8n, SDK npm i PyPI. Polskie wsparcie. Dokumentacja po polsku. Jeden endpoint do wysyłki zamiast SOAP-u czy SDK z 30 metodami. Szczegółowe zestawienie: porównanie bramek SMS.
Czy API obsługuje MMS i wiadomości głosowe?
API v2 obsługuje SMS. MMS i wiadomości głosowe IVR/TTS realizujemy z poziomu platformy - napisz na [email protected], jeśli potrzebujesz ich przez API.
Jak skonfigurować webhook dla statusów doręczenia?
Wywołaj PUT /v1/account/webhook z adresem https. W odpowiedzi dostaniesz webhook_secret. Przy każdej zmianie statusu wysyłamy POST application/json ze zdarzeniem (message.delivered, message.failed…) i pełnym obiektem wiadomości - a także message.received (odpowiedź odbiorcy) i link.clicked (pierwsze kliknięcie śledzonego linku) - podpisany nagłówkiem X-Przypominamy-Signature. Odpowiedz 2xx; przy błędzie ponawiamy do 3 razy.
Czy mogę mierzyć kliknięcia w linki z SMS-a?
Tak. Wstaw {{link:https://…}} w treści (do 2 różnych adresów). Każdy odbiorca dostaje własny krótki link api.przypominamy.com/l/<token>, więc wiesz, kto kliknął, ile razy i kiedy: GET /v1/messages/{id} zwraca links[], GET /v1/links?message_id=… zestawienie z totals, a przy pierwszym kliknięciu przychodzi webhook link.clicked. Bez dopłaty, na każdym koncie. Linki, {{opt_out}} i pola z kontaktów dzielą wspólny budżet 4 placeholderów na wiadomość.
Czy odbiorca może odpowiedzieć na SMS?
Tak - odbiór odpowiedzi (2-way) uruchamiamy na życzenie, po włączeniu numeru odbiorczego dla Twojego konta (napisz na [email protected]). Odpowiedź trafia do Ciebie, gdy zaczyna się od Twojego słowa kluczowego (inbound_prefix, ustawiane przez PATCH /v1/account) albo gdy to Ty ostatni pisałeś na ten numer w ciągu 30 dni (reply_to = id wysyłki). Czytasz je przez GET /v1/inbound, webhookiem message.received albo w panelu; STOP automatycznie trafia na czarną listę. Dostępność numeru i warunki odbioru potwierdza obsługa przed uruchomieniem. Endpointy działają już dziś; do uruchomienia inbound_number w GET /v1/account jest null.
Czy mogę używać własnej nazwy nadawcy (nadpisu)?
Tak. Nadpis (do 11 znaków) rejestrujemy na życzenie; po weryfikacji u operatora (zwykle 1–2 dni robocze) widzisz go w GET /v1/senders. Ustaw go jako domyślny przez PATCH /v1/account albo podaj per wiadomość w polu from. Bez własnego nadpisu SMS-y wychodzą jako PRZYPOMINAM.
Jak uniknąć podwójnej wysyłki przy retry?
Dodaj nagłówek Idempotency-Key (np. id wizyty). Powtórzenie żądania z tym samym kluczem i tą samą treścią w ciągu 24h zwraca pierwotną odpowiedź bez ponownej wysyłki i obciążenia. Ten sam klucz z inną treścią dostaje 409.
Czy są SDK dla Pythona, Node.js lub innych języków?
Tak: npm install przypominamy (Node.js, Deno, Bun, Cloudflare Workers) i pip install przypominamy (Python 3.9+). Obie paczki są bez zależności, MIT, z typowanym błędem i weryfikacją podpisu webhooków. Możesz też użyć dowolnego klienta HTTP - przykłady curl, Python, Node.js i PHP znajdziesz w dokumentacji Redoc i na blogu.
Następny krok: klucz testowy
Załóż konto, wygeneruj pk_test_… i wyślij pierwszy POST /v1/messages. Specyfikacja: /api/docs, ceny: /cennik.
Masz pytania? Napisz na [email protected].
Uruchomienie produkcyjne
Po doładowaniu utwórz nowy klucz pk_live_ w panelu i podmień go w integracji. Stary pk_test_ nie uruchamia płatnych wysyłek. Zagraniczne kierunki wymagają indywidualnej stawki i aktywacji.
Przy ponowieniu zachowaj Idempotency-Key (MCP: idempotency_key). Zakończony wynik jest odtwarzany przez 24 h. HTTP 409 może oznaczać operację w toku lub nierozstrzygniętą - sprawdź historię, nie używaj nowego klucza po timeoutcie.
Nowości i praktyczne zastosowania
Co nowego w platformie · SMS w gastronomii: zamówienia i opóźnienia
