Řešení problémů

Začněte kódem chyby: každá chyba API obsahuje code a docs_url a stránka Kódy chyb vysvětluje každou z nich. Historie ukazuje každou přijatou zprávu s časovou osou, odpovědí poskytovatele a vyrenderovaným obsahem.

Požadavek selže

403 origin_not_allowed – Přidejte doménu svého webu do Zabezpečení → Povolené weby (a pro vývoj i localhost). Zkontrolujte přesný hostname včetně www.. Pokud je v chybě details.reason: "no_origin", požadavek neměl Origin vůbec (nativní aplikace, serverový skript): pro aplikace zapněte Povolit mobilní aplikace, na serveru použijte private key. Viz Povolené domény.

403 private_key_in_browser – Private key byl použit z webové stránky. V prohlížeči používejte public key a private key nechte na serveru. Viz Klíče.

403 captcha_required / captcha_failed – Šablona vyžaduje Turnstile. Vyrenderujte widget uvnitř formuláře nebo předejte turnstileToken; po každém pokusu widget resetujte, protože tokeny jsou jednorázové. captcha_failed s hostname_mismatch znamená, že widget byl vyřešen na jiné doméně, než ze které požadavek přišel – do svého widgetu Turnstile přidejte všechny domény webu. Viz Turnstile.

403 captcha_not_configured – Šablona vyžaduje CAPTCHA, ale vaše organizace nepřidala vlastní klíče Turnstile. Vytvořte si v Cloudflare bezplatný widget a jeho site key a secret key vložte do Zabezpečení → Ochrana proti botům (Turnstile), nebo u šablony CAPTCHA vypněte.

422 invalid_template_params – Podívejte se do details.issues: každá položka uvádí param a pravidlo, které porušuje. Časté příčiny: povinné pole je prázdné, parametr typu email dostal jméno, parametr typu number dostal "12 pcs", parametr typu list dostal řetězec, který není JSON.

403 dynamic_recipient_not_allowed – Pole To/CC/BCC šablony používá parametr. Pro potvrzení použijte automatickou odpověď, nebo v šabloně zapněte Povolit dynamického příjemce (Nastavení → Ochrana).

429 rate_limited – Překročili jste limit tarifu, IP adresy nebo klíče. SDK už počkalo a pokus zopakovalo. Pro hromadné odesílání ze serveru použijte hromadné odeslání.

Chyba CORS v konzoli prohlížeče – Obvykle jde o jinou chybu v přestrojení: požadavek zablokovala Content-Security-Policy (connect-src) nebo blokátor reklam, případně šel na špatnou apiUrl. API Frontmailu posílá CORS hlavičky pro všechny originy; přístup řídí povolené domény.

Požadavek projde, ale e-mail nedorazí

1. Najděte zprávu v Historii.
   • held – došly vám kredity. Kupte balíček (Koupit kredity) nebo počkejte na obnovení; zpráva se odešle automaticky. Najdete ji i v Pozdržených zprávách. Viz Hold fronta.
   • held_service_error – přestaly fungovat přihlašovací údaje vaší služby. Otevřete E-mailové služby a službu opravte nebo znovu připojte; pozdržené zprávy se pak odešlou automaticky.
   • failed – otevřete zprávu: chyba poskytovatele je vidět v časové ose. Typické příčiny jsou neověřená doména odesílatele nebo neplatný příjemce.
   • sent – poskytovatel zprávu přijal. Pokračujte dál.
2. Zkontrolujte spam. Pokud tam zpráva je, nastavte SPF, DKIM a DMARC pro doménu odesílatele podle návodu pro vašeho poskytovatele a jako From použijte adresu na této doméně (ne adresu @gmail.com přes transakčního poskytovatele).
3. Zkontrolujte suppression list. Odeslání na blokované adresy selže s 451, ale i když jste adresu po bounce ze seznamu odstranili, schránka pořád nemusí existovat.
4. Nastavte webhooky, abyste místo hádání viděli události delivered / bounced.

Služba je opakovaně nefunkční

• Gmail: Google zneplatní refresh tokeny, když se změní heslo, když uživatel aplikaci odebere přístup, nebo po 6 měsících bez použití. Službu znovu připojte.
• API poskytovatelé: klíč byl zrotován nebo mu byla omezena oprávnění. Vytvořte klíč s oprávněním send a aktualizujte službu.
• SMTP: změnilo se heslo ke schránce, nebo poskytovatel při zapnutém 2FA vyžaduje heslo aplikace.

Přidejte záložní službu, aby nefunkční služba nezastavila vaše formuláře, zatímco ji opravujete.

E-maily vypadají špatně

• V Gmailu nebo Outlooku chybí styly → v Nastavení šablony zapněte Při uložení vložit CSS do prvků.
• Text je useknutý s odkazem „Zobrazit celou zprávu“ → e-mail má přes ~100 kB; odstraňte vložené obrázky nebo rozsáhlé styly.
• V e-mailu je doslova <b> → hodnota byla escapována. Pokud markup opravdu potřebujete, použijte parametr typu html (viz escapování).
• Data jsou ve špatném jazyce nebo časovém pásmu → nastavte locale šablony a časové pásmo organizace, nebo předejte formatDate parametr timeZone=.

Pořád si nevíte rady?

Napište na support@frontmail.dev a uveďte message_id (nebo code a čas chyby). Nikdy nepřikládejte svůj private key.