Rozwiązywanie problemów

Zacznij od kodu błędu: każdy błąd API zawiera code i docs_url, a Kody błędów wyjaśniają każdy z nich. Historia pokazuje każdą przyjętą wiadomość z osią czasu, odpowiedzią dostawcy i wyrenderowaną treścią.

Żądanie kończy się błędem

403 origin_not_allowed – Dodaj domenę swojej strony w Bezpieczeństwo → Dozwolone domeny (a do developmentu localhost). Sprawdź dokładny host, łącznie z www.. Przy details.reason: "no_origin" żądanie w ogóle nie miało nagłówka Origin (natywna aplikacja, skrypt na serwerze): w aplikacjach włącz Zezwól na aplikacje mobilne, na serwerach użyj klucza prywatnego. Zobacz Dozwolone domeny.

403 private_key_in_browser – Klucz prywatny został użyty ze strony internetowej. W przeglądarce używaj klucza publicznego, a prywatny trzymaj na serwerze. Zobacz Klucze.

403 captcha_required / captcha_failed – Szablon wymaga Turnstile. Wyrenderuj widżet wewnątrz formularza albo przekaż turnstileToken; po każdej próbie zresetuj widżet, bo tokeny są jednorazowe. captcha_failed z hostname_mismatch oznacza, że widżet został rozwiązany na hoście, który nie jest domeną żądania – dodaj wszystkie hosty swojej strony do widżetu Turnstile. Zobacz Turnstile.

403 captcha_not_configured – Szablon wymaga CAPTCHA, ale twoja organizacja nie dodała własnych kluczy Turnstile. Utwórz bezpłatny widżet w Cloudflare i wklej jego klucz witryny i klucz tajny w Bezpieczeństwo → Ochrona przed botami (Turnstile) albo wyłącz CAPTCHA w szablonie.

422 invalid_template_params – Spójrz na details.issues: każdy problem podaje param i regułę. Częste przyczyny: wymagane pole jest puste, parametr email dostał imię, parametr number dostał "12 szt.", parametr list dostał tekst, który nie jest JSON-em.

403 dynamic_recipient_not_allowed – To/CC/BCC szablonu używa parametru. Do potwierdzeń użyj automatycznej odpowiedzi albo włącz Zezwól na dynamicznego odbiorcę w Ustawienia → Ochrona szablonu.

429 rate_limited – Przekroczyłeś limit planu, IP albo klucza. SDK już odczekało i ponowiło próbę. Przy masowych wysyłkach z serwera użyj wysyłki zbiorczej.

Błąd CORS w konsoli przeglądarki – Zwykle to inny błąd w przebraniu: żądanie zablokowała Content-Security-Policy (connect-src), bloker reklam albo poszło na zły apiUrl. API Frontmaila wysyła nagłówki CORS dla wszystkich domen; dostęp kontrolują dozwolone domeny.

Żądanie się udaje, ale e-mail nie dociera

1. Znajdź wiadomość w Historii.
   • held – skończyły się kredyty. Kup pakiet (Kup kredyty) albo poczekaj na odnowienie; wiadomość zostanie wysłana automatycznie. Jest też na liście Wstrzymane wiadomości. Zobacz Kolejka wstrzymanych wiadomości.
   • held_service_error – dane dostępowe twojej usługi przestały działać. Otwórz Usługi e-mail, popraw albo ponownie połącz usługę; wstrzymane wiadomości zostaną potem wysłane automatycznie.
   • failed – otwórz wiadomość: błąd dostawcy jest na osi czasu. Typowe przyczyny to niezweryfikowana domena nadawcy albo nieprawidłowy odbiorca.
   • sent – dostawca ją przyjął. Czytaj dalej.
2. Sprawdź spam. Jeśli tam jest, skonfiguruj SPF, DKIM i DMARC dla domeny nadawcy zgodnie z poradnikiem dostawcy i używaj adresu nadawcy w tej domenie (a nie adresu @gmail.com przez dostawcę transakcyjnego).
3. Sprawdź listę wykluczeń. Wysyłki na wykluczone adresy kończą się błędem 451, ale jeśli po odbiciu usunąłeś adres z listy, skrzynka może nadal nie istnieć.
4. Skonfiguruj webhooki, żeby widzieć zdarzenia delivered / bounced zamiast zgadywać.

Usługa ciągle przestaje działać

• Gmail: Google unieważnia tokeny odświeżania po zmianie hasła, gdy użytkownik odbierze aplikacji dostęp albo po 6 miesiącach nieużywania. Połącz usługę ponownie.
• Dostawcy z API: klucz został zmieniony albo ograniczono jego uprawnienia. Utwórz klucz z uprawnieniem send i zaktualizuj usługę.
• SMTP: zmieniło się hasło do skrzynki albo dostawca wymaga hasła aplikacji przy włączonym 2FA.

Dodaj usługę zapasową, żeby zepsuta usługa nie zatrzymała twoich formularzy, zanim ją naprawisz.

E-maile źle wyglądają

• Brak stylów w Gmailu albo Outlooku → włącz Wstawiaj CSS inline przy zapisie w Ustawieniach szablonu.
• Tekst jest ucięty z dopiskiem „Wyświetl całą wiadomość” → e-mail ma ponad ~100 kB; usuń obrazki osadzone w treści albo duże style.
• Dosłowne <b> w e-mailu → wartość została escapowana. Jeśli naprawdę potrzebujesz znaczników, użyj parametru html (zobacz escapowanie).
• Daty w złym języku albo strefie czasowej → ustaw język szablonu i strefę czasową organizacji albo przekaż timeZone= do formatDate.

Nadal nie działa?

Napisz na support@frontmail.dev i podaj message_id (albo code i czas błędu). Nigdy nie wysyłaj swojego klucza prywatnego.