Kolejka wstrzymanych wiadomości

Żaden e-mail nigdy nie przepada po cichu. Gdy Frontmail nie może wysłać wiadomości od razu – bo twojej organizacji skończyły się kredyty albo twoja usługa e-mail odrzuciła dane logowania – przyjmuje wiadomość, bezpiecznie zapisuje ją w kolejce wstrzymanych wiadomości (w panelu Wstrzymane wiadomości) i wysyła automatycznie, gdy tylko problem zostanie rozwiązany.

Kiedy wiadomości są wstrzymywane

Powód	Status	Przyczyna
Brak kredytów	held	Żaden grant nie ma już kredytów (limit miesięczny, pakiety i debet są wyczerpane), a organizacja używa trybu `hold`
Błąd usługi	held_service_error	Dostawca odrzucił dane logowania (błąd uwierzytelniania), a szablon nie ma działającej usługi zapasowej

Przy wstrzymaniu z powodu kredytów API odpowiada od razu:

HTTP/1.1 202 Accepted

{ "message_id": "msg_01J9Z3K7Q2", "status": "held", "status_token": "…" }

SDK zwracają wynik ze status: 'held' – to sukces, a nie błąd. Pokaż odwiedzającemu zwykłe potwierdzenie; e-mail wyjdzie, gdy tylko kredyty będą dostępne.

Wstrzymanie z powodu usługi następuje później, w procesie wysyłki: wiadomość została przyjęta jako queued, dostawca odrzucił dane logowania, kredyt został zwrócony, a wiadomość przeszła do statusu held_service_error.

Jak długo wiadomości czekają

Plan	Czas wstrzymania
Free	3 dni
Starter, Pro, Business	14 dni

Czas liczy się od chwili wstrzymania wiadomości, według planu, który masz w tym momencie. Gdy wstrzymane wiadomości wygasną w ciągu najbliższych 24 godzin, właściciel, administratorzy i członkowie z rolą Płatności dostają e-mail „Wstrzymane e-maile wkrótce wygasną” (najwyżej raz dziennie). Wiadomości, które dotrą do końca czasu wstrzymania, są odrzucane (status discarded), a te same osoby dostają e-mail z ich listą i linkiem do pobrania pełnej listy w CSV. Żadna wstrzymana wiadomość nie zostanie odrzucona bez powiadomienia.

Limit kolejki wstrzymanych wiadomości

Jedna organizacja może mieć wstrzymanych najwyżej 10% miesięcznego limitu swojego planu – co najmniej 1000 i najwyżej 10 000 wiadomości (Free, Starter, Pro: 1000; Business 50k: 5000; Business 100k i 200k: 10 000). Gdy kolejka jest pełna, nowe żądania bez kredytu zamiast wstrzymania są odrzucane z kodem 402 insufficient_credits i details.reason: "hold_queue_full". Dzięki temu ktoś, kto skopiował twój klucz publiczny, nie zapełni kolejki śmieciami, które – zwalniane od najstarszych – zużyłyby każdy nowy kredyt przed twoimi prawdziwymi wiadomościami. Żeby zrobić miejsce, zwolnij lub odrzuć wstrzymane wiadomości albo dokup kredyty.

Automatyczne zwalnianie

Frontmail zwalnia kolejkę automatycznie za każdym razem, gdy pojawią się kredyty:

kupisz pakiet kredytów,
powiedzie się automatyczne doładowanie,
przejdziesz na wyższy plan,
zacznie się nowy okres rozliczeniowy (odnowienie subskrypcji; Free: nowy miesiąc kalendarzowy),
pomoc techniczna Frontmail doda kredyty bonusowe.

…a w przypadku wiadomości held_service_error także wtedy, gdy usługa znów działa (zaktualizowane dane logowania, ponownie połączone OAuth albo udany health check).

Zwalnianie przetwarza wstrzymane wiadomości od najstarszej. Dla każdej rezerwuje kredyt, przywraca ją do statusu queued i przekazuje do wysyłki. Zatrzymuje się na pierwszej wiadomości, dla której brakuje kredytu – reszta pozostaje wstrzymana, nadal w tej samej kolejności. Zwalnianie może bezpiecznie działać równolegle; żadna wiadomość nie zostanie wysłana dwa razy.

Wiadomości wysłane kluczem publicznym są zwalniane automatycznie tylko z kredytów innych niż debet, chyba że pozwolisz ruchowi na kluczu publicznym z niego korzystać w Płatności → Kup kredyty → Wydatki z ruchu na kluczu publicznym. Jeśli został już tylko debet, takie wiadomości pozostają wstrzymane, a pozostałe są zwalniane. Ręczne Zwolnij w panelu może użyć dla nich debetu.

Wstrzymane wiadomości są renderowane wersją szablonu, która była aktualna w chwili ich przyjęcia.

Ręczne zwalnianie i odrzucanie

Strona Wstrzymane wiadomości w panelu pokazuje wszystkie wstrzymane wiadomości od najstarszej, z kolumnami Wstrzymano, szablon (z tematem), odbiorca, Powód i Wygasa. Wiersze, które wygasną w ciągu 24 godzin, są wyróżnione. Możesz filtrować według powodu: Wszystkie / Brak kredytów / Błąd usługi. Właściciel, administratorzy i programiści mogą:

Zwolnij N – zwalnia zaznaczone wiadomości. Przydaje się po naprawieniu usługi albo gdy masz tylko kilka kredytów i chcesz najpierw wysłać najważniejsze wiadomości. Wiadomości są zwalniane od najstarszej, dopóki starcza kredytów; reszta pozostaje wstrzymana, a panel cię o tym informuje.
Zwolnij wszystkie – zwalnia wszystkie wstrzymane wiadomości od najstarszej, na ile pozwalają kredyty.
Odrzuć N – po potwierdzeniu odrzuca zaznaczone wiadomości. Nigdy nie zostaną wysłane i nie zużywają kredytów. Tego nie da się cofnąć.

Właściciel i członkowie z rolą Płatności widzą na tej stronie także przycisk Kup kredyty. Jeśli twoja organizacja używa trybu reject, strona informuje, że nowe żądania są odrzucane zamiast wstrzymywane.

Górny pasek panelu zawsze pokazuje, ile kredytów zostało (Zostało N żądań). Kliknij go, żeby zobaczyć podział według źródła (subskrypcja, pakiety kredytów, bonus, debet) i najbliższe wygaśnięcie. Gdy są wstrzymane wiadomości, obok pojawia się czerwona plakietka z ich liczbą, która prowadzi do Wstrzymanych wiadomości.

Tryb `hold` a `reject`

Każda organizacja wybiera, co się dzieje, gdy nie ma kredytów, w Bezpieczeństwo → Gdy skończą się kredyty (właściciel i administratorzy):

Tryb	Odpowiedź	Kiedy używać
Wstrzymuj e-maile (`hold`, domyślny, zalecany)	`202` ze `status: "held"`, wiadomość zostaje zapisana i wysłana później	Lepiej dostarczyć późno niż wcale – formularze kontaktowe, zamówienia, rezerwacje
Odrzucaj żądania (`reject`)	`402` `insufficient_credits`, nic nie jest zapisywane	Spóźnione doręczenie jest gorsze niż żadne (kody jednorazowe, pilne alerty), a twój kod obsługuje błąd

W trybie reject SDK rzucają InsufficientCreditsError. Wstrzymania z powodu usługi (held_service_error) zdarzają się w obu trybach, bo żądanie zostało już przyjęte.

Powiadomienia

E-mail	Kiedy	Do kogo
Skończyły się kredyty, e-maile czekają w kolejce	Gdy w danym miesiącu kalendarzowym po raz pierwszy zostanie wstrzymana wiadomość	właściciel, administratorzy, Płatności
Wstrzymane e-maile wkrótce wygasną	Najwyżej raz dziennie, dopóki wstrzymane wiadomości wygasną w ciągu 24 godzin	właściciel, administratorzy, Płatności
Odrzucono wstrzymane e-maile	Po wygaśnięciu, z listą odrzuconych wiadomości i linkiem do CSV	właściciel, administratorzy, Płatności
Usługa nie działa / znów działa	Gdy usługa nie przejdzie uwierzytelniania / gdy wróci do działania	właściciel, administratorzy

Wszystkie e-maile znajdziesz w Powiadomieniach.

Sprawdzanie statusu z kodu

const res = await send('svc_01J9…', 'tpl_order', params);
if (res.status === 'held') {
  // Przyjęte i bezpieczne – zostanie wysłane automatycznie.
}

// Później (klienci z kluczem publicznym potrzebują status tokenu z wyniku wysyłki):
const status = await getStatus(res.messageId, { token: res.statusToken });
console.log(status.status); // "held" → "queued" → "sent" …