Integracja przez API: wysyłka transakcyjna i zapis kontaktów z własnej aplikacji

W skrócie

Oprócz panelu, w którym tworzysz kampanie ręcznie, Nadajnik ma dwa endpointy API: jeden do wysyłki pojedynczej wiadomości transakcyjnej z zapisanego szablonu, drugi do dopisania kontaktu do listy. Autoryzujesz się tokenem Bearer, który generujesz sam w panelu.

To nie jest osobny produkt do e-maili systemowych. To ta sama instancja, ten sam szablon bloków, ta sama domena wysyłkowa z DKIM i ten sam Strażnik dostarczalności, który pilnuje, żeby żadna wiadomość, marketingowa albo transakcyjna, nie trafiła z adresu, który wylądował na czarnej liście. Jedna infrastruktura, dwa sposoby jej używania: z panelu i z kodu.

Dlaczego e-mail transakcyjny potrzebuje tej samej infrastruktury, co kampania

Potwierdzenie zamówienia, powiadomienie o statusie wysyłki, reset hasła, link aktywacyjny. Takie wiadomości zwykle wysyła sam sklep albo aplikacja, przez konto pocztowe skonfigurowane na szybko, czasem bez poprawnego SPF, bez DKIM albo z dzieloną reputacją z codzienną skrzynką firmy.

Skutek: potwierdzenie zamówienia trafia do spamu klienta, który już zapłacił i czeka na informację, że transakcja się powiodła. To gorsza sytuacja niż niedostarczona kampania marketingowa, bo klient aktywnie czeka na tę konkretną wiadomość i traktuje jej brak jako sygnał, że coś poszło nie tak z zamówieniem.

Wysyłając wiadomości transakcyjne przez API Nadajnika, korzystasz z domeny wysyłkowej, która ma już poprawne SPF, DKIM i DMARC, i z monitoringu, który sam wychwytuje problem z dostarczalnością, zanim klienci zaczną się na to masowo skarżyć.

Jak działa autoryzacja: token Bearer

W panelu, w Ustawieniach, generujesz token dostępu. To ciąg znaków, który wklejasz w nagłówek Authorization: Bearer <token> każdego żądania do API. Token identyfikuje Twoją instancję, więc żadna dodatkowa konfiguracja po stronie serwera nie jest potrzebna.

Token traktuj jak hasło do konta z prawem wysyłki. Trzymaj go po stronie serwera Twojej aplikacji, nigdy w kodzie frontendu ani w aplikacji mobilnej, którą można rozłożyć na części i odczytać ciąg znaków. Jeśli podejrzewasz, że token wyciekł, wygenerujesz nowy w tym samym miejscu w panelu, a stary od razu przestaje działać.

POST /api/tx: wysyłka wiadomości transakcyjnej z szablonu

Mechanika jest prosta: w panelu tworzysz szablon wiadomości, tym samym edytorem bloków, którym budujesz kampanię, i oznaczasz go jako szablon transakcyjny, na przykład "potwierdzenie zamówienia" albo "reset hasła". W treści szablonu umieszczasz zmienne, dokładnie tak jak w kampanii: {{ imie }}, {{ firma }} albo własne pola, które chcesz podstawić.

Z kodu Twojej aplikacji wywołujesz POST /api/tx z nagłówkiem autoryzacji, wskazujesz, który szablon ma zostać użyty, adres odbiorcy i wartości zmiennych do podstawienia. Nadajnik renderuje szablon, wstawia wartości i wysyła wiadomość od razu, przez skonfigurowaną domenę wysyłkową. Schematycznie wygląda to tak:

Cała logika renderowania, podpisu DKIM i doboru serwera SMTP z puli zostaje po stronie Nadajnika. Twoja aplikacja wysyła jedno żądanie i nie musi wiedzieć nic o konfiguracji poczty.

POST /api/tx/subscribe: kontakt trafia do listy bez eksportu i importu

Drugi endpoint działa odwrotnie: nie wysyła wiadomości, tylko dopisuje kontakt do wskazanej listy w Nadajniku. Wywołujesz POST /api/tx/subscribe z tokenem, adresem e-mail i listą, do której kontakt ma trafić.

W praktyce to zamiana cyklicznego eksportu z jednego systemu i importu do drugiego na jedno wywołanie w momencie, w którym ktoś faktycznie zostawia swój adres: wypełnia formularz na Twojej stronie, zakłada konto w sklepie albo zapisuje się na webinar. Kontakt jest w liście od razu, gotowy do kolejnej kampanii, bez ręcznego pliku CSV, który trzeba pamiętać wysłać i zaimportować.

Jeśli lista, do której dopisujesz kontakt, ma włączony podwójny zapis (double opt-in), kontakt mimo wywołania przez API dostanie standardowy e-mail z potwierdzeniem, zanim trafi na aktywną listę wysyłkową. Reguła zgody działa tak samo, niezależnie od tego, czy kontakt dodał ktoś ręcznie w panelu, czy Twoja aplikacja przez API.

Przykład: sklep internetowy i e-mail "potwierdzenie zamówienia"

Sklep internetowy ma już swój system zamówień, ale wysyła potwierdzenia przez skrzynkę biuro@ firmy, bez DKIM, z adresu, który codziennie obsługuje też zwykłą korespondencję. Część potwierdzeń ląduje w spamie, część w zakładce promocje, a klient dzwoni z pytaniem, czy zamówienie w ogóle przeszło.

Po integracji: w chwili, gdy zamówienie zmienia status na "przyjęte", system sklepu wywołuje POST /api/tx z szablonem "potwierdzenie zamówienia", adresem klienta i danymi zamówienia jako zmiennymi (numer zamówienia, lista pozycji, kwota). Wiadomość idzie przez domenę wysyłkową z poprawnym DKIM i SPF, pod kontrolą tego samego Strażnika dostarczalności, który monitoruje 24 listy DNSBL i URIBL dla kampanii marketingowych sklepu. Klient dostaje potwierdzenie do głównej skrzynki, nie do spamu, a zespół sklepu nie musi pilnować osobnej konfiguracji poczty transakcyjnej.

Przykład: formularz na stronie firmy zapisuje kontakt sam

Firma usługowa ma na swojej stronie prosty formularz "zapisz się po bezpłatną wycenę". Bez integracji, ktoś musi co tydzień zebrać zgłoszenia z poczty albo panelu formularza i wkleić je do listy w Nadajniku, żeby wysłać dalszą kampanię.

Po integracji: formularz na stronie, zamiast wysyłać e-mail do skrzynki firmy, wywołuje POST /api/tx/subscribe z adresem, który wpisała osoba wypełniająca formularz, i z listą "zapytania z formularza". Kontakt jest w Nadajniku w chwili wysłania formularza. Jeśli lista ma double opt-in, dostaje e-mail z potwierdzeniem zapisu zgodnie z regułą, a po potwierdzeniu wchodzi do dalszych kampanii albo do automatycznej reguły Stacji, która np. doda go też do segmentu "nowe zapytania w tym tygodniu".

Ta sama ochrona dostarczalności, bez osobnej konfiguracji

Najważniejsza różnica między podłączeniem własnego, prostego SMTP do wysyłki transakcyjnej a wysyłką przez API Nadajnika nie leży w samej wysyłce, tylko w tym, co się dzieje, gdy coś zacznie iść źle.

• Jeśli adres IP serwera wysyłkowego trafi na jedną z 24 monitorowanych list DNSBL albo URIBL, Strażnik dostarczalności wstrzymuje wyłącznie dotknięte kampanie, a nie całą instalację, więc transakcyjne potwierdzenia, które idą przez inną, czystą domenę albo serwer, mogą działać dalej.
• SPF, DKIM i DMARC są skonfigurowane raz, dla całej domeny wysyłkowej, nie osobno dla każdego narzędzia, które akurat wysyła e-mail.
• Odbicia (hard, soft, complaint) są obsługiwane centralnie, więc adres, który regularnie odbija transakcyjne potwierdzenia, nie zaśmieca też list marketingowych.

Bez integracji musisz pilnować tego osobno dla każdego miejsca w swojej aplikacji, które wysyła e-mail. Z API pilnuje tego jedna infrastruktura, raz skonfigurowana.

Czego integracja przez API nie robi

Żeby nie było niejasności: API nie zastępuje Radaru i nie wyszukuje za Ciebie nowych firm. Nie zastępuje też edytora kampanii w panelu, jeśli wolisz budować wiadomości ręcznie, blok po bloku, i wysyłać je z interfejsu. To dodatkowa droga do tej samej infrastruktury, dla przypadków, w których wysyłka albo zapis kontaktu musi wynikać z akcji w Twojej własnej aplikacji, a nie z ręcznego kliknięcia w panelu.

API nie omija też reguł zgody. Lista z double opt-in zachowuje się tak samo, niezależnie od tego, skąd przyszedł kontakt, a wypis jednym kliknięciem i nagłówek List-Unsubscribe działają identycznie dla wiadomości wysłanych z panelu i z API.

Jak zacząć

1. Wygeneruj token w Ustawieniach panelu. Trzymaj go po stronie serwera swojej aplikacji.
2. Zbuduj szablon transakcyjny edytorem bloków, z potrzebnymi zmiennymi, i oznacz go jako szablon do wysyłki transakcyjnej.
3. Wywołaj POST /api/tx testowo, na własny adres, żeby zobaczyć, jak wygląda wiadomość po podstawieniu zmiennych.
4. Podłącz wywołanie do rzeczywistego zdarzenia w swojej aplikacji: zmiana statusu zamówienia, rejestracja konta, reset hasła.
5. Jeśli masz formularz na stronie, zamień wysyłkę e-maila do siebie na wywołanie POST /api/tx/subscribe z odpowiednią listą.

Dla kogo to rozwiązanie

Integracja przez API ma sens przede wszystkim dla firm, które mają własną aplikację, sklep internetowy albo system, z którego wychodzą pojedyncze, ważne wiadomości do konkretnej osoby w konkretnym momencie, a nie tylko kampanie masowe do całej listy.

Jeśli dziś wysyłasz potwierdzenia zamówień, powiadomienia albo linki aktywacyjne przez osobno skonfigurowany SMTP, bez pewności co do SPF i DKIM, przeniesienie tej wysyłki na infrastrukturę, którą już masz w licencji Nadajnika, nie wymaga dodatkowej opłaty za kolejne narzędzie. Wymaga jednego wywołania API w miejscu, gdzie dziś wywołujesz swoją funkcję wysyłki e-maila.

Najczęstsze pytania

Czy token API daje dostęp do wszystkich danych w panelu?

Token służy do wysyłki transakcyjnej i do zapisu kontaktów przez te dwa konkretne endpointy. Traktuj go jak dane dostępowe z prawem wysyłki i trzymaj wyłącznie po stronie serwera swojej aplikacji, nigdy w kodzie, który trafia do przeglądarki użytkownika.

Czy wysyłka przez API liczy się do tego samego limitu co kampanie?

Licencja Nadajnika nie ogranicza liczby kontaktów ani wiadomości. Jedyny praktyczny limit wynika z Twojego serwera wysyłkowego, własnego SMTP albo wybranego pakietu, tak samo jak w przypadku kampanii wysyłanych z panelu.

Czy mogę użyć własnego szablonu HTML w wiadomości transakcyjnej?

Szablon budujesz w tym samym edytorze bloków, który służy do kampanii, albo wklejasz własny HTML, tak jak przy zwykłej kampanii. API wywołuje gotowy, zapisany w panelu szablon, nie przyjmuje treści wiadomości w samym żądaniu.

Co się stanie, jeśli domena wysyłkowa trafi na czarną listę?

Strażnik dostarczalności wstrzymuje tylko kampanie i wysyłki powiązane z dotkniętym adresem IP albo domeną, nie całą instalację. Jeśli korzystasz z osobnej, czystej domeny do wysyłki transakcyjnej, może ona dalej działać, nawet gdy inna domena w Twojej instancji zostanie wstrzymana.

Czy POST /api/tx/subscribe wymaga podwójnej zgody?

Zachowanie zależy od ustawienia konkretnej listy, do której dopisujesz kontakt. Jeśli lista ma włączony double opt-in, kontakt dodany przez API dostanie standardowy e-mail z potwierdzeniem zapisu, zanim trafi na aktywną listę wysyłkową.

Jak bezpiecznie przechowywać token?

Token przechowuj jak każdy inny sekret aplikacji: w zmiennych środowiskowych albo managerze sekretów na serwerze, nigdy w repozytorium kodu i nigdy w aplikacji frontendowej czy mobilnej. Jeśli podejrzewasz wyciek, wygeneruj nowy token w panelu, a stary przestaje działać od razu.