Przejdź do głównej zawartości
Frontmail Docs

Przegląd i pojęcia

Frontmail pozwala wysyłać e-maile prosto z frontendu – formularz kontaktowy, prośbę o rezerwację, potwierdzenie zamówienia – bez własnego backendu. Podłączasz dostawcę poczty, z którego już korzystasz, w panelu projektujesz szablon HTML z typowanymi parametrami i wywołujesz jedną funkcję:

import { init, send } from '@frontmail/browser';


init({ publicKey: 'pk_4f2a…' });
await send('svc_01J9…', 'tpl_01J9…', { name: 'Jana', message: 'Hello!' });

Żądanie trafia do API Frontmaila, które je sprawdza (domena, ochrona przed botami, rate limity, walidacja parametrów), rezerwuje jeden kredyt i ustawia e-mail w kolejce. Następnie nadawca renderuje szablon i dostarcza go przez twojego dostawcę. Zdarzenia doręczenia (dostarczono, odbito, otwarto…) wracają przez webhooki dostawcy do historii i statystyk.

Elementy składowe

Dział zatytułowany „Elementy składowe”

Organizacja

Dział zatytułowany „Organizacja”

Wszystko – klucze, usługi, szablony, kredyty, członkowie – należy do organizacji. Jeden użytkownik może być członkiem kilku organizacji i przełączać się między nimi. Każda organizacja ma swój plan i własne saldo kredytów.

Klucz publiczny i klucz prywatny

Dział zatytułowany „Klucz publiczny i klucz prywatny”
Klucz publiczny pk_… Klucz prywatny sk_…
Gdzie się znajduje W kodzie frontendu – nie jest tajny Tylko na twoim serwerze – traktuj go jak hasło
Jak się go wysyła user_id w treści żądania albo nagłówek X-Frontmail-Public-Key Authorization: Bearer sk_… (albo accessToken w treści) – nigdy z przeglądarki: żądania z nagłówkiem Origin są odrzucane
Co go chroni Dozwolone domeny, Turnstile, rate limity, ochrona przed botami Jego tajność – pomija sprawdzanie domeny i CAPTCHA
Co może send, send-form, przesyłanie plików, odczyt statusu własnych wiadomości Wszystko powyżej oraz send-batch, history, templates

Klucz publiczny widzi każdy, kto otworzy twoją stronę, więc Frontmail nigdy nie ufa tylko jemu. Przed uruchomieniem na produkcji przeczytaj Klucze publiczne i prywatne.

Usługi

Dział zatytułowany „Usługi”

Usługa to połączenie z dostawcą poczty: SMTP (Seznam, Zoho, własny serwer), Mailgun, Amazon SES, Postmark, Mailjet, Brevo, Resend, Gmail albo Outlook / Microsoft 365. Dane logowania są szyfrowane przez AWS KMS. Frontmail sprawdza każdą usługę codziennie i od razu po błędzie uwierzytelniania, a szablon może mieć usługę zapasową, która przejmuje wysyłkę, gdy główna zawiedzie. Zobacz Przegląd usług.

Szablony

Dział zatytułowany „Szablony”

Szablon to pełny e-mail HTML (z wygenerowaną wersją tekstową) plus temat, odbiorcy (To, CC, BCC, Reply-To, From) i schemat parametrów. Parametry są typowane (string, email, number, date, list…) i walidowane przy każdej wysyłce, a treść korzysta z Handlebars do warunków, pętli i helperów formatujących. Zobacz Szablony HTML i Parametry i typy.

Kredyty

Dział zatytułowany „Kredyty”

Jeden przyjęty e-mail = jeden kredyt. Kredyty pochodzą z przydziałów (grants):

  • subscription – miesięczny limit twojego planu (nie przechodzi na kolejny miesiąc),
  • pack – przedpłacone pakiety kredytów ważne 3–12 miesięcy, dostępne w każdym planie, także Free,
  • bonus – kredyty dodane przez wsparcie Frontmaila,
  • overdraft – 10% zapasu (debet) w płatnych planach, rozliczany na następnej fakturze.

Kredyty są zawsze pobierane z przydziału, który wygasa najwcześniej, debet na końcu. Wysyłki testowe z edytora szablonów są bezpłatne. Jeśli wysyłka trwale się nie powiedzie, kredyt wraca. Zobacz Kolejność zużycia.

Żaden e-mail nie znika bez śladu

Dział zatytułowany „Żaden e-mail nie znika bez śladu”

Gdy skończą się kredyty, Frontmail nie wyrzuca twojego e-maila. W domyślnym trybie hold przyjmuje żądanie z 202 { "status": "held" }, zapisuje wiadomość i wysyła ją automatycznie, gdy tylko kredyty znów będą dostępne – po zakupie pakietu, automatycznym doładowaniu, przejściu na wyższy plan albo w następnym okresie rozliczeniowym. Przeczytaj Kolejka wstrzymanych wiadomości.

Cykl życia wiadomości

Dział zatytułowany „Cykl życia wiadomości”
accepted ─┬─► queued ─► sending ─► sent ─┬─► delivered
          │                              ├─► bounced
          │                              └─► complained
          ├─► held (brak kredytów) ─► queued …   albo ─► discarded (wstrzymanie wygasło / ręcznie)
          └─► (błąd uwierzytelniania u dostawcy) held_service_error ─► queued … po naprawie usługi
                                     failed (trwały błąd, kredyt zwrócony)

Wszystkie statusy wyjaśnia strona Statusy wiadomości.

Co dalej

Dział zatytułowany „Co dalej”