Webhook dla poczty przychodzącej API odbiera wiadomości wysłane na adres lub domenę, którą posiadasz, parsuje je i dostarcza do Twojej aplikacji jako ustrukturyzowany HTTP POST. Zamiast uruchamiać serwer pocztowy i odpytywać skrzynkę przez IMAP, kierujesz rekordy MX swojej domeny na dostawcę, a każda przychodząca wiadomość trafia na Twój endpoint z nagłówkami, treścią i załącznikami już sparsowanymi do JSON.
Jak działa poczta przychodząca?
Routing zaczyna się od DNS. Ustawiasz rekordy MX dla domeny lub subdomeny (np. reply.yourapp.com) tak, aby wskazywały na serwery pocztowe dostawcy. Gdy ktoś wyśle wiadomość na dowolny adres w tej domenie, trafia ona na infrastrukturę dostawcy, a nie Twoją. Dostawca przyjmuje wiadomość, parsuje ją i wysyła żądanie POST na zarejestrowany przez Ciebie URL ze sparsowaną zawartością.
Sparsowany payload zazwyczaj zawiera nadawcę i odbiorcę, temat, treść w postaci zwykłego tekstu i HTML, pełny zestaw nagłówków oraz załączniki (często zakodowane w base64 lub dostępne pod URL). Twoja aplikacja odczytuje ten JSON i reaguje na niego, bez kodu SMTP ani IMAP do utrzymywania. Mechanizmem dostarczania jest webhook, więc obowiązują te same zasady: odpowiedz szybkim 2xx, a wiadomość przetwórz asynchronicznie.
Do czego służy poczta przychodząca?
Poczta przychodząca zamienia odebrane wiadomości w zdarzenia aplikacji. Typowe zastosowania to:
- Obsługa odpowiedzi. Wyślij powiadomienie z
notifications@yourapp.com, a gdy użytkownik odpowie, odpowiedź dotrze jako POST i możesz dołączyć ją do wątku konwersacji. - Zgłoszenia do supportu. Wiadomość na
support@yourapp.comstaje się nowym zgłoszeniem, a nadawca i treść trafiają bezpośrednio do Twojego help desku. - Parsowanie do bazy danych. Przesłane dalej paragony lub ustrukturyzowane e-maile są parsowane i zapisywane w tabeli, bez ręcznego wprowadzania.
- E-mail jako akcja. Wiadomość na specjalny adres uruchamia workflow: utwórz rekord, rozpocznij zadanie, opublikuj na kanale.
Czym różni się od wysyłania poczty?
Poczta wychodząca i przychodząca to dwa osobne zadania. Wychodząca to Twoja aplikacja dostarczająca wiadomości odbiorcom przez SMTP lub HTTP send API. Przychodząca to odwrotność: zewnętrzni nadawcy dostarczają wiadomości do Twojej aplikacji. Pełna integracja e-mail zazwyczaj obsługuje oba kierunki, wysyłanie powiadomień i odbieranie odpowiedzi, ale konfiguruje się je niezależnie, a strona przychodząca zależy od Twoich rekordów MX.
Dlaczego nie odpytywać skrzynki przez IMAP?
Możesz uruchomić poller IMAP na rzeczywistej skrzynce, ale wiąże się to ze stałym kosztem. Zarządzasz danymi uwierzytelniającymi, decydujesz, jak często odpytywać (co zwiększa opóźnienia i generuje bezczynne połączenia), samodzielnie parsujesz surowy MIME i śledzisz, które wiadomości już przetworzyłeś. Webhook dla poczty przychodzącej API eliminuje większość tych problemów: dostawca parsuje MIME, wypycha każdą wiadomość jednokrotnie jako czysty JSON, a Ty reagujesz niemal w czasie rzeczywistym. Porównanie protokołów znajdziesz w artykule SMTP vs. IMAP.
Często zadawane pytania
Jakie zmiany DNS muszę wprowadzić?
Ustaw rekordy MX dla domeny lub subdomeny, na której chcesz odbierać pocztę, tak aby wskazywały na Twojego dostawcę poczty przychodzącej. Po propagacji wiadomości na dowolny adres w tej domenie trafiają do dostawcy, który je parsuje i przesyła POST-em na Twój endpoint. Użycie dedykowanej subdomeny pozwala oddzielić routing poczty przychodzącej od poczty głównej domeny.
Jak obsługiwane są załączniki?
Sparsowany payload zawiera załączniki, zazwyczaj zakodowane inline w base64 lub jako URL-e do pobrania osobno. Twój handler dekoduje je lub pobiera i zapisuje tam, gdzie przechowujesz pliki. Większe załączniki są zwykle udostępniane pod URL-em, aby payload pozostał mały.
Czy poczta przychodząca to to samo co webhook?
Dostarczanie odbywa się przez webhook: dostawca wysyła do Twojej aplikacji HTTP POST dla każdej wiadomości. Różnica polega na tym, że payload to w pełni sparsowany e-mail, a nie ogólne zdarzenie. Traktuj go jak każdy inny webhook: zweryfikuj, odpowiedz szybko i przetwarzaj asynchronicznie.
Aby zobaczyć, jak Bird obsługuje e-mail w obu kierunkach, zacznij od przeglądu produktu e-mail i przewodnika po zdarzeniach e-mail, który opisuje model dostarczania zdarzeń, na którym oprzesz swój handler poczty przychodzącej.