SMS API: jak wysłać SMS przez API krok po kroku (z własnego numeru)

SMS API pozwala wysyłać wiadomości z Twojej aplikacji, sklepu albo skryptu bez ręcznego klikania. Zwykle płacisz wtedy dostawcy za każdy SMS, a klient dostaje wiadomość z obcego numeru lub nazwy, na którą nie może odpisać. Ten przewodnik pokazuje inną drogę: wysyłanie SMS przez API z własnego numeru, przy użyciu telefonu z Androidem jako bramki. Dostaniesz pełną konfigurację, kod w pięciu językach, obsługę błędów i sprawdzanie statusów.

Jak działa SMS API oparte na własnym telefonie?

Twoja aplikacja wysyła żądanie HTTP do serwera smsportal, serwer przekazuje zlecenie do telefonu z kartą SIM, a telefon wysyła zwykły SMS przez sieć operatora. Odbiorca widzi Twój numer, a odpowiedź wraca przez ten sam kanał do panelu, API i webhooków.

Cały obieg wygląda tak:

1. Twój kod wywołuje POST /gateway/send-sms z kluczem API.
2. Serwer przyjmuje zlecenie i zwraca smsBatchId (to jeszcze nie jest wysyłka).
3. Telefon pobiera zlecenie i wysyła SMS ze swojej karty SIM.
4. Telefon zgłasza do serwera statusy: wysłana, dostarczona albo nieudana.

Dzięki temu nie ma opłaty „od sztuki” po stronie smsportal. Koszt samej wiadomości to koszt w Twoim planie komórkowym, a wiele polskich i europejskich abonamentów zawiera nielimitowane SMS-y. Do tego dochodzi plan smsportal: bezpłatny na start, płatne miesięczne plany opisane w cenniku. Szczegóły kosztów porównamy w osobnym artykule, ile kosztuje wysyłka SMS.

Uwaga: telefon jest nadajnikiem. Musi mieć zasilanie, zasięg i internet. Jeśli jest offline, wiadomości czekają w kolejce do 72 godzin, potem wygasają.

Czego potrzebujesz, żeby zacząć?

Potrzebujesz trzech rzeczy i około 15 minut:

• telefonu z Androidem 7.0 lub nowszym i aktywną kartą SIM (może być starszy model, najlepiej na stałe pod ładowarką),
• konta w smsportal (rejestracja, plan bezpłatny wystarczy na start),
• dowolnego języka, który potrafi wysłać żądanie HTTP: cURL, PHP, Python, Node.js, Go.

Aplikację pobierzesz bezpośrednio ze strony: smsportal.apk. Opis aplikacji znajdziesz w funkcjach aplikacji Android.

Krok 1: Jak podłączyć telefon do konta?

Zainstaluj aplikację, nadaj jej uprawnienia do SMS-ów i zeskanuj kod QR z panelu. Telefon pojawi się na liście urządzeń. To jednorazowa konfiguracja.

1. Zainstaluj APK na telefonie z kartą SIM, z której chcesz wysyłać.
2. Przejdź przez krótkie wprowadzenie i zezwól na wysyłanie oraz odbieranie SMS-ów.
3. W panelu kliknij Dodaj urządzenie i zeskanuj kod QR (albo wpisz klucz ręcznie).
4. Nazwij telefon, np. „Recepcja”.

Aplikacja pokaże ekran uprawnień. Wyłączenie optymalizacji baterii dla aplikacji jest ważne: Android potrafi uśpić ją w tle i wtedy wysyłka stoi.

Krok 2: Jak wygenerować klucz API?

Klucz API tworzysz w panelu jednym kliknięciem. Identyfikuje Twoje konto i można go w każdej chwili unieważnić. Trzymaj go w zmiennej środowiskowej, nigdy w repozytorium.

export SMSPORTAL_API_KEY="wklej_tutaj_klucz"

Każde żądanie dołącza klucz w nagłówku x-api-key. Adres bazowy API to https://smsportal.app/api/v1.

Krok 3: Jak wysłać pierwszy SMS przez API?

Wyślij POST /gateway/send-sms z listą odbiorców w formacie międzynarodowym (+48...) i treścią. Przy jednym urządzeniu nie musisz podawać deviceId. Bez niego API użyje urządzenia domyślnego albo aktywnego z najświeższym sygnałem.

Pola żądania:

cURL

curl -X POST "https://smsportal.app/api/v1/gateway/send-sms" \
  -H "x-api-key: $SMSPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+48600100200"],
    "message": "Samochod gotowy do odbioru. Warsztat Kowalski, ul. Polna 5."
  }'

Poprawna odpowiedź ma kod 200 i wygląda tak:

{
  "data": {
    "success": true,
    "message": "Message queued for delivery",
    "smsBatchId": "665f1c2a9b1e4a0012ab34cd"
  }
}

Zapisz smsBatchId. Dzięki niemu odnajdziesz wszystkie wiadomości z tej wysyłki.

Python

import os
import requests

API = "https://smsportal.app/api/v1"
HEADERS = {"x-api-key": os.environ["SMSPORTAL_API_KEY"]}

res = requests.post(
    f"{API}/gateway/send-sms",
    headers=HEADERS,
    json={
        "recipients": ["+48600100200"],
        "message": "Przypominamy o wizycie jutro o 10:00. Odpisz TAK, aby potwierdzic.",
    },
    timeout=15,
)
res.raise_for_status()
print(res.json()["data"]["smsBatchId"])

Node.js

const API = 'https://smsportal.app/api/v1'

const res = await fetch(`${API}/gateway/send-sms`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.SMSPORTAL_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    recipients: ['+48600100200'],
    message: 'Zamowienie 1042 wyslane. Numer przesylki: 5200123456.',
  }),
})

if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`)
const { data } = await res.json()
console.log(data.smsBatchId)

PHP

<?php
$ch = curl_init('https://smsportal.app/api/v1/gateway/send-sms');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'x-api-key: ' . getenv('SMSPORTAL_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'recipients' => ['+48600100200'],
        'message' => 'Dzien dobry! Wizyta jutro o 10:00.',
    ]),
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("HTTP $status: $body");
}
echo json_decode($body, true)['data']['smsBatchId'];

Go

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{"recipients":["+48600100200"],"message":"Test z Go"}`)

	req, _ := http.NewRequest("POST",
		"https://smsportal.app/api/v1/gateway/send-sms",
		bytes.NewBuffer(body))
	req.Header.Set("x-api-key", os.Getenv("SMSPORTAL_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	if res.StatusCode != http.StatusOK {
		panic(fmt.Sprintf("HTTP %d: %s", res.StatusCode, out))
	}
	fmt.Println(string(out))
}

Gotowe, wielojęzyczne klienty z obsługą błędów i ponawianiem znajdziesz w osobnym artykule: wysyłanie SMS w PHP, Pythonie i Node.js. Pełna lista pól jest też w dokumentacji API.

Wskazówka: nie ma oficjalnej paczki (SDK) na npm ani pip. Zwykłe żądanie HTTP z fetch, requests czy cURL wystarczy i nie dokłada zależności.

Jak obsłużyć błędy odpowiedzi API?

Sprawdzaj kod HTTP każdego żądania. Kod 200 oznacza przyjęcie zlecenia, a kody 400, 401 i 429 mają konkretne przyczyny. Nie ponawiaj ślepo błędów 400 i 401, bo ten sam błąd wróci.

Przykład obsługi w Pythonie:

import os
import requests

res = requests.post(
    "https://smsportal.app/api/v1/gateway/send-sms",
    headers={"x-api-key": os.environ["SMSPORTAL_API_KEY"]},
    json={"recipients": ["+48600100200"], "message": "Test"},
    timeout=15,
)

if res.status_code == 200:
    print("OK", res.json()["data"]["smsBatchId"])
elif res.status_code == 429:
    print("Limit planu:", res.text)      # nie ponawiaj od razu
elif res.status_code in (400, 401):
    print("Błąd żądania:", res.text)     # popraw dane lub klucz
else:
    print("Błąd serwera, ponów później:", res.status_code)

Pamiętaj: przyjęcie żądania nie oznacza dostarczenia. API odpowiada 200, gdy zlecenie trafiło do kolejki. Telefon musi być jeszcze online i wysłać wiadomość.

Jak sprawdzić status wysłanego SMS-a?

Odczytaj status przez GET /gateway/messages z filtrem smsBatchId, albo odbierz go natychmiast webhookiem. Wiadomość przechodzi od pending przez dispatched i sent do delivered, a w razie problemu kończy jako failed.

curl "https://smsportal.app/api/v1/gateway/messages?smsBatchId=665f1c2a9b1e4a0012ab34cd" \
  -H "x-api-key: $SMSPORTAL_API_KEY"

Odpowiedź zawiera listę wiadomości z polami status, recipient, sentAt i deliveredAt. Możesz też filtrować po statusie, na przykład listę nieudanych wysyłek z jednej partii:

curl "https://smsportal.app/api/v1/gateway/messages?smsBatchId=665f1c2a9b1e4a0012ab34cd&status=failed" \
  -H "x-api-key: $SMSPORTAL_API_KEY"

W panelu te wartości widać jako etykiety: w kolejce (pending i dispatched), wysłana (sent), dostarczona (delivered) i nieudana (failed).

Brak raportu doręczenia nie zawsze znaczy błąd: niektóre sieci i numery nie zwracają potwierdzeń. Traktuj sent jako „SMS opuścił telefon”, a delivered jako potwierdzenie z sieci.

Zamiast odpytywać API w pętli, lepiej skonfigurować webhook na zdarzenia MESSAGE_SENT, MESSAGE_DELIVERED i MESSAGE_FAILED. Jak go zbudować i zweryfikować podpis, opisuje artykuł odbieranie SMS przez API i webhook.

Jak wysłać wiele SMS-ów albo zaplanować wysyłkę?

Do wielu wiadomości z różną treścią użyj POST /gateway/send-bulk-sms. Do wysyłki o wybranej godzinie dodaj pole scheduledAt w żądaniu send-sms.

Wysyłka zbiorcza, każda pozycja ma własną treść i odbiorców:

curl -X POST "https://smsportal.app/api/v1/gateway/send-bulk-sms" \
  -H "x-api-key: $SMSPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "recipients": ["+48600100200"], "message": "Dzien dobry Anno, wizyta jutro o 10:00." },
      { "recipients": ["+48601200300"], "message": "Dzien dobry Piotrze, wizyta jutro o 11:30." }
    ]
  }'

Wysyłka zaplanowana (czas w ISO 8601, musi być w przyszłości):

curl -X POST "https://smsportal.app/api/v1/gateway/send-sms" \
  -H "x-api-key: $SMSPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipients": ["+48600100200"],
    "message": "Przypomnienie: jutro o 10:00 wizyta w gabinecie.",
    "scheduledAt": "2026-10-08T08:00:00Z"
  }'

Serwer przetrzymuje wiadomość i wypuszcza ją o podanej porze. Takie planowanie to podstawa automatycznych przypomnień o wizycie. Jeśli wolisz wgrać plik, panel obsługuje też wysyłkę z CSV ze zmiennymi w treści, opisaną w artykule masowa wysyłka SMS z CSV lub Excela.

W telefonie z dwiema kartami SIM wybierzesz kartę polem simSubscriptionId (wartość pochodzi z informacji o SIM urządzenia). Bez niego używana jest domyślna karta telefonu.

Ile SMS-ów można wysłać i co z polskimi znakami?

Z jednego telefonu wyślesz około 12 SMS-ów na minutę, bo aplikacja domyślnie czeka 5 sekund między wiadomościami. Polskie znaki skracają jeden segment SMS-a z 160 do 70 znaków.

Praktyczne liczby:

• Tempo: 5 s przerwy to około 720 SMS-ów na godzinę z jednego telefonu. Przerwę zmienisz w ustawieniach aplikacji. Duże wysyłki serwer wypuszcza falami dopasowanymi do tej przerwy.
• Więcej wolumenu: podłącz kilka telefonów (urządzeń) i rozdzielaj wysyłki między nie.
• Znaki: SMS bez polskich liter (alfabet GSM-7) mieści 160 znaków w segmencie. Jedna litera z ogonkiem, np. „ś” lub „ł”, przełącza całą wiadomość na kodowanie UCS-2 i segment ma 70 znaków. Dłuższe wiadomości są dzielone na segmenty.
• Licznik: ekran tworzenia wiadomości w aplikacji pokazuje liczbę znaków i segmentów na żywo, więc możesz sprawdzić tekst przed wysyłką.

Wiadomość „Dzień dobry, Pani Aniu” ma ogonki, więc kosztuje więcej segmentów niż „Dzien dobry, Pani Aniu”. Przy krótkich, transakcyjnych powiadomieniach zwykle nie ma to znaczenia, a przy długich tekstach dobrze skracać treść.

Kiedy własny numer, a kiedy hurtowa bramka SMS?

Własny numer pasuje do wiadomości transakcyjnych, rozmów z klientem, alertów wewnętrznych i agentów AI. Do kampanii marketingowych na tysiące odbiorców na godzinę lepsza jest hurtowa bramka.

Operatorzy mogą blokować masową wysyłkę z kart abonamentowych i narusza ona zwykle ich regulaminy. Dlatego uczciwa rada brzmi: kampanie masowe zlecaj dostawcy hurtowemu, a wiadomości jeden do jednego i powiadomienia wysyłaj z własnego numeru. Różnice w nadawcy opisuje artykuł nazwa nadawcy czy własny numer. Pamiętaj też, że wiadomości marketingowe wymagają zgody odbiorcy. Szczegóły w UODO: uodo.gov.pl. To nie jest porada prawna.

Jak podłączyć SMS API do automatyzacji i agentów AI?

Ten sam klucz API działa w narzędziach no-code i w serwerze MCP dla asystentów AI. Do automatyzacji użyjesz węzła HTTP, a agent AI korzysta z gotowych narzędzi MCP.

• n8n, Make, Zapier: użyj węzła HTTP Request z nagłówkiem x-api-key i adresem /gateway/send-sms, a odbiór odpowiedzi klientów oprzyj na webhooku. Nie ma natywnej aplikacji w tych platformach, ale zwykły HTTP w pełni wystarcza. Zobacz automatyzację w n8n.
• Agenci AI: serwer MCP (https://smsportal.app/mcp) udostępnia Claude Code, Cursorowi i Codexowi narzędzia do wysyłania i czytania SMS-ów. Przewodnik: SMS dla agentów AI przez MCP i strona integracji MCP.
• Sklep internetowy: zdarzenie zamówienia wywołuje żądanie na /gateway/send-sms. Wzorzec opisuje artykuł powiadomienia SMS o zamówieniu.

W aplikacji na telefonie widzisz wszystko, co poszło przez API: listę wiadomości z filtrami i osobną oś czasu każdej z nich.

Jak przetestować integrację przed wdrożeniem?

Testuj w trzech krokach: własny numer, celowe błędy i telefon offline. Dzięki temu zobaczysz każdy status i kod błędu, zanim zobaczy je klient.

1. Własny numer. Wyślij wiadomość do siebie i obejrzyj jej oś czasu w aplikacji.
2. Błędy. Podaj losowy klucz w x-api-key (oczekuj 401), pustą treść (oczekuj 400) i scheduledAt z przeszłości (oczekuj 400). Upewnij się, że kod nie ponawia tych żądań.
3. Telefon offline. Wyłącz internet w telefonie, wyślij SMS i obserwuj status pending. Po włączeniu internetu powinien przejść do sent, a potem delivered.

W testach automatycznych nie wysyłaj prawdziwych SMS-ów. Podmień funkcję wysyłki na atrapę i sprawdzaj, że dostaje poprawny numer oraz treść. Osobny test niech zwraca 401 i 500, żeby potwierdzić, że kod ponawia tylko błędy chwilowe.

Jak zabezpieczyć klucz API i dane klientów?

Klucz API trzymaj w zmiennej środowiskowej lub menedżerze sekretów, a numery telefonów traktuj jak dane osobowe. Klucz da się w każdej chwili unieważnić w panelu, więc przy podejrzeniu wycieku wygeneruj nowy.

• Osobne klucze dla produkcji, testów i każdej integracji ułatwiają unieważnienie jednego bez przerywania pozostałych.
• Nie wysyłaj klucza z przeglądarki. Wywołania API rób po stronie serwera, bo kod w przeglądarce może odczytać każdy.
• Nie loguj treści SMS-ów z kodami jednorazowymi ani danymi zdrowotnymi. Loguj smsBatchId i status.
• Ogranicz dane w treści. SMS jest zwykłą wiadomością, bez szyfrowania do odbiorcy, więc nie wysyłaj nim haseł ani pełnych danych osobowych.

Zasady przetwarzania numerów reguluje RODO, a wiadomości marketingowe wymagają zgody. To nie jest porada prawna.

Co zrobić, gdy wiadomość nie dociera?

Zacznij od statusu z API, bo pokazuje, na którym etapie utknęła wiadomość. Większość przyczyn leży po stronie telefonu, nie kodu.

Gdy wszystko wygląda poprawnie, wyślij wiadomość ręcznie z ekranu tworzenia w aplikacji. Jeśli ręcznie działa, a z API nie, problem leży w żądaniu. Jeśli nie działa też ręcznie, szukaj w karcie SIM i operatorze.

Lista kontrolna przed uruchomieniem na produkcji

Przed pierwszym prawdziwym klientem sprawdź siedem punktów. Zajmie to około 10 minut i oszczędza najczęstszych wpadek.

1. Klucz API leży w zmiennej środowiskowej, nie w repozytorium.
2. Kod sprawdza status HTTP i zapisuje smsBatchId.
3. Ponawiasz tylko błędy chwilowe (timeout, 5xx), z rosnącą przerwą.
4. Telefon ma stałe zasilanie, internet i wyłączoną optymalizację baterii.
5. Webhook na MESSAGE_FAILED powiadamia Cię o nieudanych wysyłkach.
6. Wiadomości z kodami jednorazowymi mają krótką ważność po stronie kodu, bo kolejka offline wygasa po 72 godzinach.
7. Znasz limit: około 720 SMS-ów na godzinę z jednego telefonu.

Najczęstsze problemy przy wysyłce SMS przez API

Większość problemów to telefon, nie kod. Zacznij od ekranu zdrowia urządzenia w aplikacji i od kodu odpowiedzi API.

• 400 „no enabled device”: telefon jest wyłączony w panelu albo nigdy nie został połączony. Sprawdź listę urządzeń.
• Status pending nie zmienia się: telefon jest offline albo Android uśpił aplikację. Wyłącz optymalizację baterii i sprawdź internet.
• Status failed: błędny numer, brak środków lub zasięgu na karcie SIM albo blokada operatora. Sprawdź numer w formacie +48....
• Brak statusu delivered: sieć nie zwróciła raportu doręczenia. Wiadomość mogła dojść, status zostaje sent.
• OTP i kody jednorazowe: po 72 godzinach offline kolejka wygasa, więc ważność kodu ustaw po swojej stronie krótko.

Więcej o stabilności bramki znajdziesz na stronie niezawodność.

Pierwszy SMS z API w 15 minut

Załóż konto, podłącz telefon, wygeneruj klucz i wklej jeden z powyższych przykładów. Plan bezpłatny wystarczy do przetestowania całego obiegu, łącznie ze statusami i webhookiem.

1. Utwórz konto w smsportal.
2. Pobierz aplikację na Androida i zeskanuj kod QR.
3. Wyślij pierwszy curl ze swojego telefonu na własny numer.

Przy wzroście wolumenu zerknij na plany i na artykuł bramka SMS: co to jest i jak działa.