Hold fronta

Žádný e-mail se nikdy potichu nezahodí. Když Frontmail nemůže zprávu odeslat hned – protože vaší organizaci došly kredity, nebo protože vaše e-mailová služba odmítla přihlašovací údaje – zprávu přijme, bezpečně ji uloží do hold fronty (v dashboardu Pozdržené zprávy) a odešle ji automaticky, jakmile je problém vyřešen.

Kdy se zprávy drží

Důvod	Stav	Příčina
Chybí kredity	held	Žádný grant nemá zbývající kredity (kvóta, balíčky i přečerpání jsou vyčerpané) a organizace používá režim hold
Chyba služby	held_service_error	Poskytovatel odmítl přihlašovací údaje (chyba autentizace) a šablona nemá funkční záložní službu

Při zadržení kvůli kreditům API odpoví okamžitě:

HTTP/1.1 202 Accepted

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

SDK vrátí výsledek se status: 'held' – je to úspěch, ne chyba. Zobrazte návštěvníkovi běžné potvrzení; e-mail odejde, jakmile budou kredity k dispozici.

Zadržení kvůli službě nastává až později, v odesílači: zpráva byla přijata jako queued, poskytovatel odmítl přihlašovací údaje, kredit se vrátil a zpráva přešla do stavu held_service_error.

Jak dlouho se zprávy drží

Tarif	Doba držení
Free	3 dny
Starter, Pro, Business	14 dní

Doba se počítá od okamžiku, kdy byla zpráva pozdržena, podle tarifu, který máte v tu chvíli. Když pozdrženým zprávám zbývá do vypršení méně než 24 hodin, dostanou vlastník, admini a členové s rolí Fakturace e-mail „Pozdržené e-maily brzy vyprší“ (nejvýš jednou denně). Zprávy, které dosáhnou konce doby držení, se zahodí (stav discarded) a stejní lidé dostanou e-mail s jejich seznamem a odkazem na stažení kompletního seznamu v CSV. Žádná pozdržená zpráva se nezahodí, aniž by o tom někdo věděl.

Limit hold fronty

Jedna organizace může mít pozdrženo nejvýš 10 % měsíční kvóty svého tarifu – nejméně 1 000 a nejvýš 10 000 zpráv (Free, Starter, Pro: 1 000; Business 50k: 5 000; Business 100k a 200k: 10 000). Když je fronta plná, nové požadavky bez kreditu se místo pozdržení odmítnou s 402 insufficient_credits a details.reason: "hold_queue_full". Kdo si zkopíruje váš veřejný klíč, tak frontu nezaplní nesmysly, které by se – uvolňované od nejstarší – postaraly o spotřebu všech nových kreditů dřív než vaše skutečné zprávy. Místo uvolníte tak, že pozdržené zprávy uvolníte nebo zahodíte, případně dokoupíte kredity.

Automatické uvolnění

Frontmail frontu uvolní automaticky, kdykoli přibudou kredity:

• koupíte kreditový balíček,
• proběhne auto top-up,
• přejdete na vyšší tarif,
• začne nové fakturační období (obnovení předplatného; Free: nový kalendářní měsíc),
• podpora Frontmailu přidá bonusové kredity.

…a u zpráv ve stavu held_service_error také ve chvíli, kdy je služba znovu v pořádku (aktualizované přihlašovací údaje, znovu připojené OAuth nebo úspěšný health-check).

Uvolňování zpracovává držené zprávy od nejstarší. Pro každou zprávu zarezervuje kredit, vrátí ji do stavu queued a předá ji odesílači. Zastaví se u první zprávy, na kterou už kredit nezbývá – zbytek zůstane držený, stále ve stejném pořadí. Uvolňování může bezpečně běžet souběžně; žádná zpráva se nikdy neodešle dvakrát.

Zprávy odeslané s veřejným klíčem se automaticky uvolňují jen z jiných kreditů než z overdraftu, pokud provozu s veřejným klíčem jeho čerpání nepovolíte ve Fakturace → Koupit kredity → Útrata za e-maily s veřejným klíčem. Když zbývá jen overdraft, takové zprávy zůstanou pozdržené a ostatní se uvolní. Ruční Uvolnit v dashboardu pro ně overdraft použít smí.

Držené zprávy se renderují s verzí šablony, která byla aktuální v době jejich přijetí.

Ruční uvolnění a zahození

Stránka Pozdržené zprávy v dashboardu vypisuje všechny pozdržené zprávy od nejstarší se sloupci Pozdrženo od, šablona (s předmětem), příjemce, Důvod a Vyprší. Řádky, které vyprší do 24 hodin, jsou zvýrazněné. Podle důvodu je vyfiltrujete přepínačem Vše / Chybí kredity / Chyba služby. Vlastník, admini a vývojáři můžou:

• Uvolnit N – uvolní vybrané zprávy. Hodí se po opravě služby, nebo když máte jen pár kreditů a chcete nejdřív poslat ty nejdůležitější. Zprávy se uvolňují od nejstarší, dokud stačí kredity; zbytek zůstane pozdržený a dashboard vám to oznámí.
• Uvolnit vše – uvolní všechny pozdržené zprávy od nejstarší, kam až kredity stačí.
• Zahodit N – po potvrzení zahodí vybrané zprávy. Nikdy se neodešlou a nečerpají kredity. Vrátit to nejde.

Vlastník a členové s rolí Fakturace na stránce vidí i tlačítko Koupit kredity. Pokud vaše organizace používá režim reject, stránka upozorní, že nové požadavky se místo držení odmítají.

Horní lišta dashboardu vždy ukazuje, kolik kreditů zbývá (Zbývá N požadavků). Po kliknutí uvidíte rozpad podle zdroje (předplatné, kreditové balíčky, bonus, přečerpání) a nejbližší expiraci. Když jsou nějaké zprávy pozdržené, objeví se vedle červený odznak s jejich počtem, který vede na Pozdržené zprávy.

Režim hold vs. reject

Každá organizace si v Zabezpečení → Když dojdou kredity vybírá, co se stane, když nejsou kredity (mění to vlastník a admini):

Režim	Odpověď	Kdy použít
Pozdržet e-maily (hold, výchozí, doporučeno)	202 se status: "held", zpráva se uloží a odešle později	Raději doručit pozdě než nikdy – kontaktní formuláře, objednávky, rezervace
Odmítat požadavky (reject)	402 insufficient_credits, nic se neukládá	Pozdní doručení je horší než žádné (jednorázové kódy, časově citlivá upozornění) a váš kód chybu ošetří

V režimu reject SDK vyhodí InsufficientCreditsError. Zadržení kvůli službě (held_service_error) nastává v obou režimech, protože požadavek už byl přijat.

Tip

Zkombinujte hold frontu s auto top-upem spouštěným při první držené zprávě: držené zprávy se pak obvykle uvolní během několika sekund, aniž by kdokoli sáhl na dashboard.

Notifikace

E-mail	Kdy	Komu
Došly kredity, e-maily čekají ve frontě	Když se v kalendářním měsíci poprvé pozdrží zpráva	vlastník, admini, Fakturace
Pozdržené e-maily brzy vyprší	Nejvýš jednou denně, dokud pozdrženým zprávám zbývá do vypršení méně než 24 hodin	vlastník, admini, Fakturace
Pozdržené e-maily jsme zahodili	Po vypršení, se seznamem zahozených zpráv a odkazem na CSV	vlastník, admini, Fakturace
Služba nefunguje / zase funguje	Když služba neprojde ověřením / když se vzpamatuje	vlastník, admini

Přehled všech e-mailů najdete v Notifikacích.

Kontrola stavu z kódu

const res = await send('svc_01J9…', 'tpl_order', params);
if (res.status === 'held') {
  // Přijato a v bezpečí – odešle se automaticky.
}

// Později (klienti s public key potřebují status token z výsledku odeslání):
const status = await getStatus(res.messageId, { token: res.statusToken });
console.log(status.status); // "held" → "queued" → "sent" …

V dashboardu

Průvodce obrazovkou Pozdržené zprávy najdete v části Pozdržené zprávy.