REST API: pierwszy request w dziesięć minut
Pierwszy request do REST API wysyłkowego zajmuje mniej czasu niż konfiguracja klienta pocztowego. Serio. Potrzebujesz klucza, zweryfikowanej domeny i jednego polecenia w terminalu. Cel tego tekstu jest wąski: doprowadzić cię do jednego działającego wywołania, które kończy się mailem w skrzynce. Pełna integracja, webhooki i higiena listy – to później. Najpierw musisz zobaczyć kod 202 i wiadomość, którą sam wysłałeś.
Po co ci REST API do wysyłki maili
Do newslettera panel wystarcza. Wrzucasz treść, wybierasz segment, planujesz wysyłkę i masz spokój. API zaczyna się liczyć wtedy, gdy wiadomość musi wyjść w sekundę po zdarzeniu w twoim systemie, a nikt nie siedzi przy przeglądarce.
Zastosowania? Przewidywalne: potwierdzenie zamówienia, reset hasła, powiadomienie z aplikacji mobilnej, synchronizacja listy odbiorców z bazą CRM. Wspólny mianownik to zdarzenie w kodzie, które ma natychmiast pociągnąć za sobą maila. Jeśli twój system ma już gotowy konektor, sprawdź najpierw listę dostępnych integracji – część pracy może być zrobiona za ciebie.
Technicznie nie ma tu magii. REST API to zwykły HTTP: adres zasobu, metoda, nagłówki, JSON w body i kod odpowiedzi. Tyle musisz umieć na start. Reszta to szczegóły konkretnej dokumentacji, których nauczysz się przy drugim i trzecim wywołaniu.
Od razu rozdzielmy dwie drogi. SMTP zostaw aplikacjom, które nie potrafią inaczej – starym systemom ERP, wtyczkom, drukarkom sieciowym. API daje ci coś, czego SMTP nie da wygodnie: identyfikator wiadomości i status, po którym możesz później odpytać o los przesyłki. Z SMTP masz odpowiedź serwera i nadzieję. Z API masz obiekt, do którego wracasz.
Czego potrzebujesz przed pierwszym requestem
Lista jest krótka i nie ma na niej niczego egzotycznego:
- Klucz API wygenerowany w panelu, najlepiej osobny dla środowiska testowego.
- Zweryfikowana domena nadawcy z ustawionym SPF i DKIM.
- Adres From na tej właśnie domenie, nie na gmailu ani na domenie klienta.
- Terminal z curl albo dowolny klient HTTP: Postman, Insomnia, wbudowany klient w IDE.
Klucz trzymasz w zmiennej środowiskowej albo w menedżerze sekretów. Nigdy w repozytorium, nigdy w kodzie frontendu. Klucz w JavaScripcie przeglądarki oznacza, że każdy odwiedzający twoją stronę może wysyłać maile z twojej domeny. Widzieliśmy takie wpadki i kończą się czyszczeniem reputacji przez kilka tygodni.
Rekordy DNS ustaw zanim wyślesz cokolwiek. Bez SPF i DKIM testowa wiadomość wpadnie do spamu i zaburzy ci obraz sytuacji – zaczniesz szukać błędu w kodzie, a problem siedzi w strefie DNS. Return-Path i PTR to zadanie infrastruktury wysyłkowej, w naszym przypadku własnej floty serwerów. Nie musisz ich konfigurować, ale dobrze wiedzieć, że ktoś je trzyma i że mają wpływ na to, czy filtry ci ufają.
Tip: pierwszy adres testowy załóż na skrzynce, do której masz pełny dostęp administracyjny. Musisz móc obejrzeć surowe nagłówki wiadomości, bo tam widać wynik uwierzytelnienia.
Anatomia requestu: uwierzytelnienie, endpoint, payload
Uwierzytelnienie idzie nagłówkiem Authorization z tokenem typu Bearer. Klucz w nagłówku, nigdy w query stringu. Query trafia do logów proxy, do historii przeglądarki i do systemów monitoringu, więc sekret w adresie URL to sekret ujawniony.
Nagłówki, bez których się nie obejdzie
Drugi obowiązkowy nagłówek to Content-Type: application/json plus faktycznie poprawny JSON w body. Brak tego nagłówka albo literówka w jego wartości to najczęstsza przyczyna odpowiedzi 415. Sprawdź też przecinki i cudzysłowy – JSON nie wybacza, a komunikat błędu bywa lakoniczny.
Metoda i zawartość body
Wysyłkę robisz metodą POST na zasób wiadomości, bo tworzysz nowy obiekt. GET służy do odpytywania o status już utworzonej wiadomości. Zwykła semantyka REST, ta sama co w każdym innym API.
Minimalny payload ma cztery pola: nadawca, odbiorca, temat i treść w HTML albo w czystym tekście. Reszta jest opcjonalna – kopie, załączniki, tagi, nagłówki własne, planowany czas wysyłki. Nie dokładaj ich przy pierwszej próbie. Każde dodatkowe pole to dodatkowe miejsce na błąd walidacji.
Przy ponawianiu żądań standardem branżowym jest klucz idempotencji przesyłany nagłówkiem. Dzięki niemu retry po timeoucie nie wyśle maila drugi raz. Zaimplementuj go od początku, bo dopisywanie tego później oznacza przepisanie warstwy obsługi błędów.
Pierwszy request krok po kroku
- Wygeneruj klucz API w panelu i zapisz go w zmiennej środowiskowej.
- Sprawdź rekordy DNS domeny nadawcy: SPF, DKIM, docelowo też DMARC.
- Złóż minimalny JSON z nadawcą, odbiorcą, tematem i treścią.
- Wyślij POST curlem z nagłówkami Authorization i Content-Type.
- Odczytaj kod odpowiedzi i treść zwróconego obiektu.
- Otwórz skrzynkę i obejrzyj wiadomość razem z nagłówkami.
Wywołanie w curlu ma stałą strukturę niezależnie od dostawcy: curl -X POST, adres zasobu wiadomości, -H „Authorization: Bearer $KLUCZ”, -H „Content-Type: application/json” i -d z twoim JSON-em. Dokładny adres endpointu bierzesz z dokumentacji swojego dostawcy, bo ta część różni się wszędzie.
Odpowiedź 2xx zawiera identyfikator wiadomości. Zapisz go od razu, najlepiej w logu aplikacji obok identyfikatora zamówienia czy użytkownika. Po tym identyfikatorze odpytujesz później o dostarczenie, otwarcie i bounce. Bez niego masz maila, którego nie umiesz odnaleźć w statystykach.
Tip: pierwszy request wyślij do siebie, drugi do skrzynki w zupełnie innej domenie i u innego dostawcy. Dopiero porównanie dwóch odbiorców pokazuje, czy uwierzytelnienie faktycznie działa, czy tylko twój własny serwer jest wobec ciebie wyrozumiały.
Kody odpowiedzi i błędy, które zobaczysz najpierw
Kody 401 i 403 oznaczają problem z kluczem. Zwykle klucz z innego środowiska, klucz skopiowany ze spacją na końcu albo klucz bez uprawnienia do konkretnego zasobu. Sprawdź to, zanim zaczniesz grzebać w payloadzie.
Kod 422 przy poprawnym składniowo JSON-ie to walidacja treści. Najczęściej nadawca spoza zweryfikowanej domeny, pusty temat albo adres odbiorcy w złym formacie. Jeśli błąd dotyczy odbiorcy, wygodniej wyłapać go wcześniej – weryfikacja adresu bez wysyłania maila odsiewa literówki i martwe skrzynki, zanim trafią do payloadu. Komunikat zwrotny zwykle wskazuje pole, więc czytaj body odpowiedzi, nie tylko status.
Kod 429 to limit żądań. Obsłuż nagłówek z czasem oczekiwania i zastosuj wykładniczy backoff. Pętla ponawiająca żądanie bez przerwy tylko pogłębia problem i bywa traktowana jak nadużycie. Warto przy okazji sprawdzić limity wysyłki w poszczególnych planach, bo część problemów z 429 to po prostu za ciasny pakiet.
Błędy 5xx leżą po stronie API. To sygnał do ponowienia z kluczem idempotencji, nie do modyfikowania payloadu. Zmiana treści przy błędzie serwera to typowa pomyłka, która potem generuje duplikaty.
No i jedna rzecz ważniejsza od reszty: kod 2xx znaczy przyjęte do wysyłki, a nie dostarczone. Wiadomość stoi w kolejce. O tym, czy dotarła, dowiesz się dopiero ze zdarzenia zwrotnego.
Od jednego requestu do produkcji: co zrobić dalej
Webhooki są następnym krokiem, nie opcją. Podepnij zdarzenia dostarczenia, otwarcia, kliknięcia, bounce’u twardego i miękkiego oraz skargi. Bez nich nie masz żadnego obrazu dostarczalności – widzisz tylko, że twój kod zawołał API.
Twarde bounce’y i skargi usuwaj z listy automatycznie, w tej samej transakcji, w której je odbierasz. Ręczne czyszczenie zawsze się rozjeżdża, a każda kolejna wysyłka na martwy adres podcina reputację nadawcy.
Rozdziel ruch transakcyjny od marketingowego, najlepiej na osobne domeny lub subdomeny. Kampania z wysokim odsetkiem skarg nie może ciągnąć w dół resetów hasła – to wiadomości o zupełnie innej wadze dla użytkownika. Jeśli szukasz miejsca, w którym oba typy ruchu są obsłużone na własnej flocie serwerów, sprawdź platformę do email marketingu MailCraft.
Nowa domena wymaga warmupu. Rosnący wolumen przez kilka tygodni, obserwacja zachowania dużych filtrów, reakcja na pierwszy spadek zamiast czekania. Wychodzenie z blokady trwa dłużej niż jej uniknięcie. Przy większym wolumenie musisz też spełnić wymogi Gmaila i Yahoo dla nadawców masowych, bo bez nich sam warmup niczego nie załatwi.
Uczciwie o granicach: część rzeczy z naszej roadmapy nie jest jeszcze dostępna w panelu. Opisujemy je tutaj jako praktykę branżową, bo tak się to rozwiązuje, a nie jako gotową funkcję do kliknięcia.
Zgoda i prawo: to nie jest osobny etap
RODO i artykuł 398 prawa komunikacji elektronicznej obowiązują także w B2B. Adres firmowy nie jest wyjątkiem, jeśli prowadzi do konkretnej osoby. Założenie, że można pisać do firm bez zgody, to kosztowna pomyłka.
Zapisuj dowód zgody: znacznik czasu, adres IP, źródło zapisu i treść klauzuli w brzmieniu z dnia jej udzielenia. Późniejsza zmiana regulaminu nie unieważnia starej zgody, ale musisz umieć pokazać, na co dokładnie ktoś się zgodził.
Transakcyjne i marketingowe opierają się na różnych podstawach prawnych. Nie doklejaj oferty do potwierdzenia zamówienia – jedno zdanie promocyjne zmienia kwalifikację całej wiadomości.
Rezygnacja musi działać przez API tak samo szybko jak w panelu. Bez opóźnienia, bez dodatkowych kroków dla odbiorcy, bez logowania. Utrudniona rezygnacja kończy się kliknięciem w przycisk zgłoszenia spamu, a to boli bardziej niż utrata adresu.
Zgodność przekłada się wprost na dostarczalność. Czysta lista ze zgodą generuje mniej skarg, a mniej skarg to lepsza reputacja nadawcy u dużych filtrów.
Podsumowanie: dziesięć minut to dopiero początek
Pierwszy request faktycznie zajmuje kilka minut. Reszta pracy to obsługa błędów, webhooki i higiena listy – i tam schodzi większość czasu integracji.
Kolejność, która się sprawdza: najpierw DNS, potem jeden mail do siebie, następnie obsługa kodów odpowiedzi, potem webhooki, dopiero na końcu wolumen. Odwrócenie tej kolejności kończy się blokadą przy pierwszej większej wysyłce.
Bez SPF, DKIM i reakcji na bounce nawet technicznie poprawny request nie da ci dostarczalności. API dowozi wiadomość do kolejki, o resztę dbają uwierzytelnienie domeny i jakość listy.
Jeśli twoja integracja jest nietypowa – własny system kolejkowania, wysokie szczyty wolumenu, migracja z innej platformy – napisz do naszego zespołu. Przejdziemy przez to razem, bez pośpiechu i bez sztucznych terminów.
