Dokumentacja

Pierwsze kroki

BgLetter to Channel: narzędzie, za pomocą którego wysyłają Państwo e-maile przez własną skrzynkę pocztową (bring-your-own-SMTP). Wysyłka przebiega przez Państwa serwer pocztowy, nadawcą pozostają Państwo, a reputacja nadawcy pozostaje Państwa – nie dostarczamy infrastruktury wysyłkowej i nie pobieramy opłat za pojedyncze e-maile.

Państwa lista odbiorców zostaje u Państwa: odbiorcy pochodzą przy każdej wysyłce z pliku CSV. Nie ma zarządzania kontaktami – żadnych zapisanych list, segmentów ani formularzy zapisu. A dane potrzebne do wysyłki są usuwane najpóźniej po 30 dniach (zob. Przechowywanie i usuwanie).

Gotowi do startu w czterech krokach

1. Utworzenie konta. Proszę zarejestrować się bezpłatnie pod adresem /register.
2. Podłączenie własnej skrzynki. Proszę wprowadzić dane dostępowe swojego serwera pocztowego (zob. „Podłączanie SMTP”).
3. Przygotowanie treści. Proszę napisać wiadomość w kreatorze lub w edytorze kodu.
4. Wgranie listy odbiorców i wysyłka. Proszę wgrać plik CSV dla tej wysyłki i wysłać od razu lub zaplanować termin.

Oferta skierowana jest wyłącznie do firm oraz innych użytkowników komercyjnych i instytucjonalnych, nie do konsumentów.

Podłączanie SMTP

W sekcji Konta nadawcy zapisują Państwo jedno lub więcej kont wysyłkowych. BgLetter zawiera prekonfigurowane szablony dostawców, które wstępnie uzupełniają host, port i szyfrowanie (np. Gmail/Google Workspace, Microsoft 365, Brevo, SendGrid, Mailgun, Postmark). W przypadku niektórych dostawców (np. Amazon SES i all-inkl/KAS) host wpisują Państwo samodzielnie, ponieważ różni się on w zależności od regionu lub pakietu.

Typowe ustawienia

Host:               smtp.panstwadomena.pl
Port:               587   (STARTTLS)  lub  465 (SSL/TLS)
Nazwa użytkownika:  wysylka@panstwadomena.pl
Hasło:              ••••••••  (zalecane hasło aplikacji)
Nadawca:            "Państwa nazwa" <newsletter@panstwadomena.pl>

Po zapisaniu mogą Państwo uruchomić połączenie testowe. BgLetter informuje, czy logowanie i szyfrowanie działają.

Dostarczalność (SPF / DKIM / DMARC)

O tym, czy Państwa e-maile docierają do odbiorców, decyduje przede wszystkim konfiguracja DNS. Kluczowe są trzy wpisy:

W skrócie: SPF autoryzuje serwery, DKIM potwierdza autentyczność, DMARC mówi odbiorcom, co ma się stać w razie fałszerstw. Wszystkie trzy razem znacząco zwiększają wskaźnik dostarczeń.

Odbiorcy i wysyłka

Odbiorcy pochodzą przy każdej wysyłce z pliku CSV. Wgrywają Państwo plik w edytorze, przypisują kolumny i wysyłają. Nie ma zapisanych list, segmentów ani formularzy zapisu: Państwa lista odbiorców zostaje u Państwa, a plik źródłowy pozostaje na Państwa komputerze.

Budowa pliku CSV

Pierwszy wiersz to nagłówek z nazwami kolumn. Jako separatora używa się zwykle przecinka lub średnika; plik najlepiej zapisać w kodowaniu UTF-8, aby zachować polskie znaki.

Email;Imie;Faktura;Jezyk;Kraj
anna@example.com;Anna Berger;R-2041;de;DE
paul@example.org;Paul Vetter;R-2042;fr;FR

Kolumny mogą nosić dowolne nazwy: po wgraniu pliku wybierają Państwo w edytorze, która kolumna zawiera adres e-mail, która nazwę, a która język lub kraj. Przykładowy plik znajdą Państwo w edytorze w sekcji „Jak ma wyglądać plik CSV?”.

Duplikaty i lista blokowana

• Duplikaty są automatycznie scalane: jeśli ten sam adres występuje w pliku kilkakrotnie, wiadomość trafia do niego tylko raz – liczy się pierwszy wiersz wraz z jego wartościami personalizacji. Wielkość liter nie ma znaczenia.
• Niekompletne wiersze bez adresu lub z adresem wyraźnie nieprawidłowym są odrzucane przed wysyłką.
• Lista blokowana obowiązuje zawsze. Adresy z Państwa listy wypisów są automatycznie pomijane przy każdej wysyłce – nie trzeba wcześniej czyścić pliku CSV.

Wysyłka

• Podgląd dla komputera i urządzeń mobilnych – z przykładowymi danymi z pierwszego wiersza Państwa pliku CSV.
• Personalizacja przez symbole zastępcze, takie jak {{NAME}}, {{EMAIL}} oraz Państwa własne kolumny.
• Link wypisu jest dodawany automatycznie – to obowiązek i korzyść dla reputacji.
• Wysyłka odbywa się z ograniczoną prędkością przez Państwa własną skrzynkę, aby zachować jej limity.

W sekcji Tryb wysyłki wybierają Państwo jedną z trzech prędkości: Bezpieczne dostarczanie (maksymalna niezawodność, zalecane), Średnia prędkość (zrównoważona) lub Wysoka prędkość (tylko dla skrzynek z wysokimi limitami wysyłki). BgLetter automatycznie rozkłada wysyłkę tak, aby e-maile do tego samego dostawcy nie następowały zbyt szybko po sobie – ręczne ustawianie odstępów nie jest potrzebne, a tymczasowo nieudane dostarczenia są automatycznie ponawiane do dwóch razy. Wysyłają Państwo natychmiast lub według harmonogramu w wybranym terminie.

Przy wysyłce natychmiastowej śledzą Państwo postęp na żywo i mogą trwającą wysyłkę wstrzymać, wznowić lub anulować. Śledzenie otwarć i kliknięć jest przy tym zawsze aktywne.

Wypisy / lista blokowana

Zarządzanie wypisami to Państwa centralna lista blokowana: każdy widniejący tu adres jest niezawodnie pomijany przy każdej wysyłce – nawet jeśli nadal znajduje się w Państwa pliku CSV. Gdy odbiorca kliknie link wypisu – także przez one-click list unsubscribe bezpośrednio w skrzynce – trafia tu natychmiast.

Od planu Pro do strony prowadzi osobna pozycja menu Wypisy; można też przejść do niej bezpośrednio pod adresem /app/unsubscribes.

• Dodawanie: ręczne wpisywanie adresów (jeden na wiersz) – z powodem do wyboru: Ręcznie, Skarga, Niedostarczalny (odbicie) lub Inny.
• Import: wczytywanie istniejących list blokowanych jako pliku CSV lub tekstowego.
• Eksport: pobranie pełnej listy jako CSV (e-mail, powód, data).

Lista blokowana to jedyny zbiór danych przechowywany trwale. Wymaga tego prawo: tylko w ten sposób wypis działa dłużej niż jedna wysyłka, nawet jeśli ten sam adres pojawi się w pliku CSV wiele miesięcy później.

Przechowywanie i usuwanie

BgLetter przechowuje możliwie najmniej danych i możliwie najkrócej. Dla każdej wysyłki obowiązuje stały termin: najpóźniej 30 dni po wysyłce dane z nią związane są automatycznie usuwane. Dzieje się to bez Państwa udziału i nie da się tego przedłużyć.

Co jest usuwane po 30 dniach

• Adresy odbiorców z wgranego pliku CSV.
• Dane personalizacji – nazwy oraz wszystkie pozostałe kolumny Państwa pliku.
• Treść wiadomości danej wysyłki (tekst, HTML, bloki, tłumaczenia).
• Zdarzenia śledzenia – pojedyncze otwarcia i kliknięcia wraz z czasem i powiązaniem z odbiorcą.

Co pozostaje

• Temat wiadomości oraz moment wysyłki.
• Anonimowe wskaźniki: liczba odbiorców, wysłane, nieudane, wskaźnik dostarczeń oraz otwarcia i kliknięcia jako sumy – bez powiązania z konkretnymi osobami.
• Lista wypisów (lista blokowana). Pozostaje trwale, ponieważ w przeciwnym razie wypis przestałby działać po 30 dniach.

Wersje robocze i szablony

Również niezmienione wersje robocze są usuwane 30 dni po ostatniej zmianie. Treści, które chcą Państwo zachować i wykorzystywać ponownie, należy więc zapisać w szablonie: szablony nie są powiązane z żadną wysyłką i pozostają, dopóki sami ich Państwo nie usuną.

Mniej przechowywanych danych oznacza mniej danych, które mogą zostać utracone. Ten termin nie jest ograniczeniem, lecz powodem, dla którego Państwa lista odbiorców nigdy nie leży u nas na stałe.

Wiadomości (transakcyjne)

W sekcji Wiadomości wysyłają Państwo pojedyncze e-maile transakcyjne – np. faktury, przypomnienia o płatnościach, potwierdzenia zapłaty, przypomnienia o terminach, potwierdzenia zamówień lub powiadomienia – do dokładnie jednego odbiorcy przez własne konto nadawcy. Wiadomości są dostępne w każdym planie (także Free).

Do płatności kreator oferuje dwa bloki: przycisk płatności (link płatności jako szablon – PayPal.Me, PayPal Checkout, Stripe Payment Link lub dowolny własny adres URL; zmienne takie jak {{AMOUNT}} czy {{INVOICE_NUMBER}} są wstawiane dla każdego odbiorcy podczas wysyłki, kwoty w formacie z kropką, np. 12.50) oraz kod QR SEPA (Girocode): odbiorcy skanują go aplikacją bankową i otrzymują wstępnie wypełniony przelew z numerem IBAN, kwotą i tytułem płatności – zupełnie bez operatora płatności. Oba bloki są już przygotowane w szablonach „Faktura” i „Przypomnienie o płatności” i są wysyłane dopiero wtedy, gdy zostaną skonfigurowane (URL lub IBAN).

• Szablony dla najczęstszych przypadków (faktura, przypomnienie o płatności, potwierdzenie, przypomnienie o terminie, potwierdzenie zamówienia, powiadomienie).
• Załączniki: do 10 plików o łącznym rozmiarze maks. 10 MB (np. faktura w PDF).
• Personalizacja przez {{NAME}} i {{EMAIL}}.
• Opcjonalne śledzenie otwarć dla każdej wiadomości.

Edytor i kreator

Newslettery tworzą Państwo w edytorze w dwóch trybach: kreatorze (bloki przeciągane metodą drag & drop, z formatowaniem inline – zaznaczony tekst można od razu zmieniać w zakresie rozmiaru, koloru, pogrubienia itd.) oraz edytorze kodu dla własnego HTML. Kreator generuje kod e-maila, który jest niezawodnie wyświetlany w Outlooku, Gmailu i Apple Mail.

Dostępne bloki

• Tekst, przycisk i obraz dla treści.
• Kolumny (2, 3 lub 4), linia oddzielająca i odstęp dla układu.
• Sieci społecznościowe oraz blok HTML dla własnych fragmentów kodu.

Tłumaczenie AI

W edytorze tłumaczą Państwo temat i treść jednym kliknięciem na maksymalnie 36 języków. Wybierają Państwo język źródłowy, formę zwracania się (formalną lub swobodną) oraz żądane języki docelowe. Symbole zastępcze, takie jak {{NAME}}, zostają zachowane.

Przy wysyłce wielojęzycznej każdy odbiorca otrzymuje odpowiednią wersję językową: jeśli Państwa plik CSV zawiera kolumnę języka (np. „Język”) lub kolumnę kraju (np. „Kraj”), do każdego odbiorcy automatycznie wysyłane jest właściwe tłumaczenie – w przeciwnym razie wersja źródłowa.

Nie muszą Państwo tłumaczyć z wyprzedzeniem: wszystkie języki rozpoznane wśród odbiorców są tłumaczone automatycznie na początku wysyłki (widoczne jako status „Trwa tłumaczenie”) – dostarczanie rozpoczyna się dopiero wtedy, gdy wszystkie wersje są gotowe.

Tak działa przypisywanie języka: kolumna może nosić dowolną nazwę – po wgraniu pliku wybierają Państwo w edytorze, która kolumna zawiera język. Rozpoznawane są kody języków (de, deu, ger), locale (de-DE, en-US), nazwy języków (Deutsch, German) oraz nazwy i kody krajów (Deutschland, Germany, DE, AT). Puste lub nieznane wartości otrzymują wersję oryginalną. Kolumna pozostaje dodatkowo dostępna jako symbol zastępczy.

Śledzenie

BgLetter rejestruje otwarcia i kliknięcia dla każdej wysyłki. W analizie widzą Państwo wskaźnik otwarć i kliknięć oraz najczęściej klikane linki.

Pojedyncze zdarzenia są powiązane z odbiorcą tylko tak długo, jak istnieje dana wysyłka – najpóźniej 30 dni po wysyłce są usuwane. Później pozostają wyłącznie anonimowe sumy (zob. Przechowywanie i usuwanie).

Wysyłki i raporty

W sekcji Kampanie i statystyki znajdą Państwo wszystkie wysyłki z datą, tematem, statusem, liczbą odbiorców, wysłanymi, nieudanymi oraz wskaźnikiem dostarczeń (wysłane ÷ wszyscy odbiorcy). Najnowsze są na górze. Ikoną oka otwierają Państwo raport.

Raport pokazuje u góry wskaźniki, w tym otwarcia i kliknięcia, oraz pasek „Postęp wysyłki”. Karta Reakcje odbiorców wykazuje otwarcia i kliknięcia jako unikalne i łączne oraz oblicza współczynnik kliknięć (CTR) z unikalnych kliknięć na unikalne otwarcie. Tabela wymienia najczęściej klikane linki z kliknięciami i unikalnymi kliknięciami.

• Tabela odbiorców: dla każdego odbiorcy e-mail, dostawca poczty, nazwa, status oraz – przy błędach – dokładny komunikat błędu SMTP i czas wysyłki. Tabela jest dostępna przez 30 dni.
• Filtry: wszystkie, wysłane, nieudane, oczekujące.
• Eksport CSV: „Eksportuj jako tabelę (CSV)” pobiera wszystkich odbiorców – niezależnie od aktywnego filtra. Proszę eksportować w odpowiednim czasie, dopóki dane jeszcze istnieją.

W zestawieniu nie ma ręcznego usuwania – i nie jest ono potrzebne: po 30 dniach BgLetter sam usuwa dane odbiorców, treść i zdarzenia śledzenia. Temat i anonimowe wskaźniki pozostają jako historia.

REST-API (krótki przegląd)

Na potrzeby integracji BgLetter oferuje REST-API. Klucze API generują Państwo w sekcji dla deweloperów swojego konta. Uwierzytelnianie odbywa się przez token Bearer w nagłówku.

# Wysłanie wiadomości transakcyjnej
curl -X POST https://bgletter.com/api/v1/messages \
  -H "Authorization: Bearer PANSTWA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to": "klient@example.com", "subject": "Państwa faktura", "html": "<p>Dzień dobry …</p>" }'

Adres bazowy to <panstwa-domena>/api/v1; uwierzytelnianie odbywa się przez Authorization: Bearer bgl_… lub X-Api-Key: bgl_…. Dostępne są punkty końcowe dla wiadomości transakcyjnych (POST /api/v1/messages), dla listy wypisów oraz punkty końcowe tylko do odczytu dla konta i wysyłek. Pełna specyfikacja znajduje się pod adresem /api/v1/openapi.json.

• Idempotencja: nagłówek Idempotency-Key przy wysyłaniu wiadomości zapobiega podwójnemu dostarczeniu przy ponowieniach.
• Podpis webhooka: każde dostarczenie zawiera X-BgLetter-Signature: sha256=… (HMAC-SHA256 z surowej treści z Państwa kluczem whsec_) – proszę go zweryfikować przed przetwarzaniem.
• Limit zapytań: 120 zapytań/minutę na konto (wiadomości dodatkowo 300/godzinę).

Dodatkowo dostępne są webhooki, które w czasie rzeczywistym powiadamiają Państwa system o zdarzeniach (np. wypis, odbicie/bounce). Punkty końcowe i przykładowe odpowiedzi znajdą Państwo w sekcji dla deweloperów.

Rozliczenia

BgLetter rozlicza się według stałej miesięcznej ceny planu – bez opłat za każdy e-mail. Plany różnią się miesięcznym wolumenem wysyłki, liczbą kont nadawcy i innymi limitami.

• Bezpłatny plan Free do wypróbowania – karta kredytowa nie jest potrzebna.
• Przejście na wyższy plan w każdej chwili w sekcji Rozliczenia. Aby przejść na niższy plan, należy wypowiedzieć subskrypcję (na koniec okresu przechodzi na „Free”).
• Wszystkie ceny podane są w euro; rozliczenia prowadzi Fontemia GmbH, Grammetstr. 14, CH-4410 Liestal.

Zespół i konto

W sekcji Zarządzanie zapraszają Państwo członków zespołu i nadają role: Właściciel, Admin lub Członek. Zarządzanie widzą tylko właściciel i administratorzy; tylko właściciel może zapraszać, zmieniać role i usuwać członków.

Liczba miejsc zależy od planu – drugi członek zespołu jest możliwy od planu Pro. Każdy członek samodzielnie aktywuje swoje uwierzytelnianie dwuskładnikowe (2FA) w ustawieniach.

Ustawienia

W sekcji Ustawienia zarządzają Państwo kontem na jednej stronie z pięcioma kartami. Hasło i uwierzytelnianie dwuskładnikowe są dostępne dla każdego członka; adres rozliczeniowy, branding oraz dane i prywatność są zastrzeżone dla właściciela.

• Zmiana hasła – nowe hasło o długości co najmniej 8 znaków. Zmiana automatycznie wylogowuje wszystkie pozostałe sesje.
• Uwierzytelnianie dwuskładnikowe – konfiguracja przez kod QR; następnie 8 jednorazowych kodów odzyskiwania jest wyświetlanych dokładnie raz (proszę je bezpiecznie przechować – nie można ich wyświetlić ponownie). Do wyłączenia potrzebny jest aktualny kod z Państwa aplikacji.
• Adres rozliczeniowy – firma, adres i numer VAT; pojawia się na Państwa fakturach (tylko właściciel).
• Branding – kolor marki, URL logo, adres pocztowy i własna stopka e-mail (szczegóły poniżej).
• Dane i prywatność – „Eksportuj moje dane (JSON)” jako plik oraz ostateczne usunięcie konta (dwuetapowe, nieodwracalne).

W brandingu kolor marki i URL logo działają tylko na publiczne strony, które widzą Państwa odbiorcy – np. stronę wypisu – a nie na wysyłane e-maile. Natomiast adres pocztowy (nadawca) jest wstawiany do stopki każdego wychodzącego e-maila – jeśli pozostawią go Państwo pusty, zabraknie wiersza z adresem (obowiązek impressum zgodnie z § 5 TMG). Własna stopka HTML jest dostępna od planu Business.

Rozwiązywanie problemów

Najczęstsze pytania i ich rozwiązania w skrócie. Większość problemów z dostarczaniem można usunąć w kilka minut.

Funkcja jest wyszarzona? Oznacza to, że nie jest zawarta w Państwa planie – obok przycisku podany jest wymagany plan (np. „Od planu Pro”). Przejście na wyższy plan w sekcji Rozliczenia ją odblokowuje.