LinkedIn
Instagram
WhatsApp
Telegram
Kalendarz Google
Dołącz do społeczności SlackCzym właściwie jest połączenie z serwerem IMAP
Połączenie z serwerem IMAP to stała sesja TCP pomiędzy klientem poczty elektronicznej a serwerem pocztowym, która wykorzystuje protokół IMAP (Internet Message Access Protocol) do synchronizacji, pobierania i zarządzania wiadomościami e-mail przechowywanymi zdalnie – bez ich pobierania lub usuwania z serwera.
W przeciwieństwie do POP3, który został zaprojektowany do pobierania wiadomości lokalnie i opcjonalnie ich usuwania z serwera, IMAP został stworzony do synchronizacji. Każde odczytanie, oznaczenie flagą, przeniesienie lub usunięcie wykonane lokalnie jest odzwierciedlane na serwerze, a tym samym na wszystkich urządzeniach podłączonych do tej samej skrzynki pocztowej. Dlatego właśnie IMAP stał się de facto protokołem dla nowoczesnych klientów poczty e-mail.
Na poziomie sieci połączenie serwera IMAP otwiera gniazdo TCP do serwera poczty (zazwyczaj port 993 dla SSL/TLS lub port 143 dla STARTTLS), przeprowadza uzgadnianie TLS, uwierzytelnia użytkownika (za pomocą hasła, hasła aplikacji lub OAuth 2.0 XOAUTH2), a następnie wchodzi do automatu stanów: Nie uwierzytelniono, Uwierzytelniony, Wybrane (wewnątrz folderu skrzynki pocztowej), lub Wyloguj. Większość użytecznych poleceń - FETCH, SEARCH, STORE, COPY, EXPUNGE - działa tylko w stanie Selected.
Dla programistów tworzących integracje pocztowe, połączenie z serwerem IMAP jest podstawowym elementem. Ustanawiasz je, uwierzytelniasz, wybierasz skrzynkę pocztową, a następnie sprawdzasz lub używasz trybu IDLE w poszukiwaniu nowych wiadomości. Ten przewodnik obejmuje każdy etap: właściwy host i port dla każdego dostawcy, właściwą metodę uwierzytelniania w 2026 roku (OAuth staje się coraz bardziej obowiązkowy) oraz kompletne odniesienie do rozwiązywania problemów z najczęstszymi błędami.
Porty IMAP wyjaśnione: 143, 993 i kiedy STARTTLS jest w porządku
Istnieją dokładnie dwa aktywne porty IMAP: 993 (Implicit TLS, nowoczesny standard) i 143 (aktualizacja STARTTLS lub zwykły tekst, czego większość serwerów już nie zezwala na zwykły tekst). Znajomość różnicy ma znaczenie, ponieważ użycie niewłaściwego portu jest jedną z najczęstszych przyczyn niepowodzeń połączenia podczas tworzenia integracji IMAP.
Klient łączy się i natychmiast inicjuje uzgadnianie TLS przed wymianą jakichkolwiek danych IMAP. Cały ruch jest szyfrowany od pierwszego bajtu. Jest to prawidłowa wartość domyślna dla każdej nowej integracji.
Klient łączy się w czystym tekście, a następnie wydaje STARTTLS polecenie uaktualnienia do TLS. Większość nowoczesnych serwerów wymaga tej aktualizacji i całkowicie odrzuca sesje w postaci zwykłego tekstu.
2026 zalecenie: zawsze używaj portu 993 z SSL_CONTEXT (TLS jawny). Jeśli tworzysz aplikację z myślą o firmowym serwerze IMAP, który udostępnia tylko port 143, włącz STARTTLS i zweryfikuj certyfikat serwera. Nigdy nie łącz się z serwerem IMAP w trybie tekstowym jawnym w środowisku produkcyjnym – dane uwierzytelniające przesyłane są w postaci jawnej, a większość dostawców odrzuca takie połączenia.
Krótka uwaga na temat RFC 9051 (IMAP4rev2), opublikowany w sierpniu 2021 r. jako następca RFC 3501. IMAP4rev2 formalnie wymaga protokołu TLS dla wszelkich połączeń przenoszących poświadczenia, wycofuje mechanizmy uwierzytelniania oparte na MD5 i usuwa LIST-ROZSZERZONY niekompatybilności, które powodowały subtelne błędy w starszych klientach. Większość głównych dostawców usług chmurowych (Gmail, Outlook) od lat jest zgodna z IMAP4rev2 w praktyce, jeszcze zanim RFC została sfinalizowana. W praktyce, docelowy port 993 + TLS sprawi, że domyślnie będziesz zgodny z RFC 9051.
Host i port - Gmail, Outlook, Yahoo, iCloud, Zoho, Fastmail, AOL, ProtonMail Bridge
Poniższa tabela zawiera poprawne ustawienia połączenia serwera IMAP dla najczęściej używanych dostawców poczty e-mail. Wszystkie wartości zostały zweryfikowane zgodnie z oficjalną dokumentacją każdego dostawcy na maj 2026 r. Użyj tej tabeli jako szybkiego punktu odniesienia podczas konfigurowania klienta IMAP lub tworzenia Integracja API IMAP.
| Dostawca | Host IMAP | Port | Szyfrowanie | OAuth 2.0 (XOAUTH2) | Notatki |
|---|---|---|---|---|---|
 Gmail |
imap.gmail.com | 993 | SSL/TLS | Tak (wymagane dla nowych aplikacji) |
Hasła do aplikacji działają, ale OAuth jest zdecydowanie preferowane. Najpierw włącz IMAP w ustawieniach Gmail. |
 Outlook / Microsoft 365 |
outlook.office365.com | 993 | SSL/TLS | Tak (Basic Auth przestarzałe w grudniu 2026) |
Basic Auth koniec życia grudzień 2026 dla wszystkich najemców. Migruj teraz do OAuth. |
Yahoo Mail |
imap.mail.yahoo.com | 993 | SSL/TLS | Tak |
Wymagane hasło aplikacji, jeśli włączona jest weryfikacja dwuetapowa. OAuth przez portal deweloperski Yahoo. |
Poczta iCloud |
imap.mail.me.com | 993 | SSL/TLS | Nie (tylko hasło aplikacji) |
Apple wymaga hasła specyficznego dla aplikacji z appleid.apple.com. Brak wsparcia OAuth XOAUTH2. |
Zoho Mail |
imap.zoho.com | 993 | SSL/TLS | Tak |
OAuth przez Zoho Accounts API. IMAP musi być włączony dla każdej skrzynki pocztowej w ustawieniach Zoho Mail. |
Fastmail |
imap.fastmail.com | 993 | SSL/TLS | Tak (preferowane JMAP) |
Fastmail natywnie obsługuje JMAP (szybszy niż IMAP), ale pełne poparcie ma również IMAP. Dostępne są hasła aplikacyjne. |
Poczta AOL |
imap.aol.com | 993 | SSL/TLS | Tak |
Obecnie część Yahoo Inc. Wymagane hasło aplikacji, jeśli włączono 2FA. OAuth przez portal deweloperski Yahoo. |
Mostek ProtonMail |
127.0.0.1 | 1143 | STARTTLS | Nie (autoryzacja tokenem mostu) |
ProtonMail Bridge działa lokalnie i udostępnia lokalny serwer IMAP. Nie nadaje się do integracji po stronie serwera. |
Ogólny IMAP |
twój-serwer-poczty.com | 993 / 143 | SSL/TLS STARTTLS | Zmienne (sprawdź konfigurację serwera) |
Dovecot, Postfix, Zimbra, Courier. Sprawdź odpowiedź CAPABILITY serwera pod kątem obsługiwanych mechanizmów uwierzytelniania. |
Gmail
Outlook / Microsoft 365
Uwaga dotycząca ProtonMail: architektura Bridge oznacza, że połączenia IMAP z ProtonMail są możliwe tylko w przypadku samodzielnych instalacji na komputery stacjonarne. W przypadku wielu kont lub integracji po stronie serwera, ProtonMail jest praktycznie nieobsługiwany za pośrednictwem standardowego IMAP. W przypadku Gmail i Outlook na dużą skalę, patrz nasze dedykowane przewodniki dotyczące OAuth dla interfejsów API poczty e-mail oraz Microsoft Graph API Poczta E-mail.
Krok po kroku: otwieranie surowego połączenia z serwerem IMAP
Poniżej znajdują się minimalne, działające przykłady otwierania uwierzytelnionego połączenia z serwerem IMAP przy użyciu wbudowanej w Pythona biblioteki imaplib i Node.js z imapflow. Oba przykłady łączą się z Gmailem przez port 993, korzystając z uwierzytelniania za pomocą hasła aplikacji. Informacje na temat OAuth XOAUTH2 znajdują się w sekcji H2 #7 poniżej.
import imaplib
import SSL
Ustawienia serwera IMAP #
HOST_IMAP = "imap.gmail.com"
IMAP_PORT = 993
NAZWA_UŻYTKOWNIKA = "you@gmail.com"
HASŁO = "twoje-hasło-do-aplikacji" Hasło do aplikacji #, a nie hasło do konta
# Utwórz kontekst SSL (zweryfikuj certyfikaty)
kontekst = SSL.utwórz_domyślny_kontekst()
# Otwórz połączenie SSL na porcie 993
z imaplib.IMAP4_SSL(IMAP_HOST, IMAP_PORT, ssl_context=kontekst jako imap:
# – uwierzytelnianie
imap.zaloguj(NAZWA UŻYTKOWNIKA, HASŁO)
# Wybierz skrzynkę odbiorczą (zwraca liczbę wiadomości)
status, dane = imap.wybierz("SKRZYNKA ODBIORCZA")
print(Skrzynka odbiorcza zawiera {data[0].decode()} wiadomości")
# Szukaj ukrytych wiadomości
status, msg_ids = imap.wyszukiwanie(Żaden, "NIEWIDZIALNY")
print(Niewidoczne: {msg_ids[0].decode()}")
# Wylogowanie (połączenie zostaje zamknięte po zakończeniu bloku 'with')// npm zainstaluj imapflow
import { ImapFlow } z 'imapflow';
const klient = nowy ImapFlow({
Gospodarz: 'imap.gmail.com',
port 993,
bezpieczny: true, // SSL/TLS na porcie 993
autoryzacja: {
użytkownik: 'you@gmail.com',
hasło: 'twoje-hasło-aplikacji'
},
rejestrator fałszywy
});
czekać klient.połącz();
// Zablokuj skrzynkę INBOX do wyłącznego dostępu
niech zamek = czekać klient.getMailboxLock('SKRZYNKA');
próbuj {
// Pobierz ostatnie 5 wiadomości (tylko nagłówki)
dla czekać (niech wiadomość z klient.fetch('1:5', { koperta: true })) {
konsola.log(temat.koperty.wiadomości);
}
} wreszcie {
zamek.zwolnić();
}
czekać klient.wyloguj();Przykład Pythona wykorzystuje IMAP4_SSL - wyższy poziom opakowania SSL, który automatycznie obsługuje uzgadnianie TLS. Unikaj używania IMAP4 + instrukcja starttls() dla dostawców chmury, ponieważ dodaje złożoności bez korzyści. Dla Node.js, imapflow jest nowoczesnym wyborem opartym na Promise (starszy node-imap biblioteka jest nieutrzymywana od 2024 roku i nie obsługuje XOAUTH2.
Oba przykłady używają haseł aplikacji, które są najprostszym typem poświadczeń do szybkiego testowania. W przypadku systemów produkcyjnych obsługujących wielu użytkowników potrzebne będzie OAuth 2.0 – patrz niższa sekcja XOAUTH2. Aby uzyskać kompletne rozwiązanie gotowe do produkcji bez zarządzania surowymi połączeniami IMAP, zobacz Przewodnik deweloperski API IMAP.
Pomiń standardowy tekst dotyczący protokołu IMAP. Unipile umożliwia odczyt, wysyłanie i synchronizację wiadomości w Gmailu, Outlooku i IMAP za pośrednictwem jednego interfejsu API REST – bez konieczności zarządzania połączeniami.
Pomiń standardowy kod IMAP — stwórz go za pomocą UnipileUwierzytelnianie: hasło, hasło aplikacji oraz OAuth 2.0 (XOAUTH2)
Po nawiązaniu połączenia z serwerem IMAP konieczne jest uwierzytelnienie po zakończeniu uzgadniania TLS. Obecnie stosuje się trzy metody uwierzytelniania – każda z nich charakteryzuje się innym profilem bezpieczeństwa, poziomem złożoności oraz kompatybilnością z dostawcami usług w chmurze w 2026 roku.
Oryginalny mechanizm IMAP AUTH PLAIN / LOGIN. Bezpośrednio wysyłasz adres e-mail konta i hasło konta na serwer IMAP. Prosty w implementacji, ale coraz częściej blokowany przez dostawców usług chmurowych ze względów bezpieczeństwa.
Wycofane dla chmury16-znakowe hasło wygenerowane przez dostawcę (Gmail, Yahoo, iCloud), które zastępuje rzeczywiste hasło konta. Działa z tym samym poleceniem IMAP LOGIN co uwierzytelnianie podstawowe, ale ma określony zakres i może być unieważnione niezależnie. Wymagane, gdy włączone jest uwierzytelnianie dwuskładnikowe.
Dopuszczalne do użytku osobistegoUżytkownik autoryzuje aplikację za pośrednictwem ekranu zgody. Aplikacja otrzymuje token dostępu (krótkotrwały, zazwyczaj na 1 godzinę), który należy zakodować w formacie Base64 i przekazać do polecenia IMAP AUTHENTICATE XOAUTH2. Tokeny są odświeżane za pomocą długotrwałego tokenu odświeżającego. Jest to jedyna realna metoda w przypadku produkcyjnych aplikacji obsługujących wielu użytkowników.
Niezbędne do produkcjiKiedy co stosować: Podczas lokalnego programowania i korzystania z narzędzi osobistych należy stosować hasła aplikacji. W przypadku integracji wieloużytkownikowych należy stosować OAuth 2.0 (XOAUTH2) – jest to jedyna metoda zapewniająca skalowalność, ponieważ nie przechowuje się haseł użytkowników, a każdy token można unieważnić bez konieczności zmiany hasła użytkownika. W przypadku Gmaila firma Google stopniowo ogranicza autoryzację Basic Auth dla "mniej bezpiecznych aplikacji" od 2022 r. W przypadku Microsoft/Outlook wycofanie autoryzacji Basic Auth jest zaplanowane na grudzień 2026 r. dla wszystkich dzierżawców (zobacz następną sekcję).
Aby uzyskać szczegółowe informacje na temat procesów OAuth – w tym wymiany tokenów, mechanizmów odświeżania i zakresów – zapoznaj się z naszym przewodnikiem na stronie OAuth dla interfejsów API poczty e-mail. Aby skonfigurować protokół OAuth specyficzny dla firmy Microsoft, zobacz Microsoft Graph OAuth dla Outlook.
Problem roku 2026: wycofanie protokołu Microsoft Basic Auth (grudzień 2026 r.)
Jeśli Twoja integracja IMAP łączy się z kontami Microsoft 365 lub Outlooka bezpośrednio przy użyciu nazwy użytkownika i hasła, czas ucieka. Firma Microsoft ogłosiła ostateczną datę wycofania uwierzytelniania podstawowego w protokołach IMAP, POP3 i SMTP dla wszystkich dzierżawców.
Według Microsoft Learn i Ogłoszenie dotyczące serwisu Microsoft Community Hub, W grudniu 2026 roku Exchange Online całkowicie wyłączy podstawowe uwierzytelnianie dla IMAP, POP3 i SMTP. dotyczy wszystkich użytkowników – w tym tych, którzy obecnie korzystają ze zwolnień. Każdy klient IMAP lub integracja po stronie serwera, które nadal wykorzystują uwierzytelnianie za pomocą nazwy użytkownika i hasła, przestaną działać. Nie ma możliwości dalszego przedłużenia terminu.
Kroki, które należy podjąć w celu przeprowadzenia migracji przed upływem terminu
Przeszukaj swój kod pod kątem połączeń IMAP, które wykorzystują zaloguj się (nazwa użytkownika, hasło) lub AUTH PLAIN. Sprawdź logi logowania w usłudze Microsoft Entra ID (dawniej Azure AD) pod kątem aktywności IMAP Basic Auth.
Utwórz rejestrację aplikacji na portalu portal.azure.com, używając IMAP.AccessAsUser.All (przekazane) lub IMAP.AccessAsApp (aplikacja) zezwolenie. Zobacz Microsoft Graph OAuth dla Outlook aby uzyskać szczegółowy przewodnik.
Użyj biblioteki MSAL (Microsoft Authentication Library) do pozyskiwania tokenów dostępu. Zaimplementuj logikę odświeżania tokenów - tokeny Microsoft wygasają po 1 godzinie i potrzebujesz przepływu odświeżania tokenów, aby utrzymać długoterminowe sesje IMAP bez ponownego uwierzytelniania użytkownika.
Zamień IMAP ZALOGUJ SIĘ polecenie z POTWIERDŹ XOAUTH2 za pomocą zakodowanego w base64 ciągu tokenu. Pełny przykładowy kod można znaleźć w sekcji XOAUTH2 poniżej.
Microsoft udostępnia możliwość wcześniejszego wyłączenia uwierzytelniania podstawowego na zasadzie dzierżawy – skorzystaj z tego, aby przetestować swój przepływ OAuth przed wymuszonym terminem w grudniu 2026 r., aby uniknąć debugowania problemów produkcyjnych pod presją czasu.
Jeśli zarządzasz połączeniami IMAP dla wielu użytkowników Microsoft 365 – co jest częstym scenariuszem dla narzędzi CRM, ATS lub automatyzacji sprzedaży – złożoność migracji szybko rośnie. Musisz obsługiwać przepływy zgody OAuth dla każdego użytkownika, bezpiecznie przechowywać i odświeżać tokeny oraz radzić sobie z zasadami dostępu warunkowego, które mogą blokować Twoją aplikację w niektórych dzierżawach. Jest to jeden z głównych powodów, dla których deweloperzy wybierają zarządzane API IMAP zamiast samodzielnego utrzymywania surowych połączeń.
Termin dla Microsoft Basic Auth zbliża się wielkimi krokami. Zbuduj przyszłościowy przepływ OAuth już dziś dzięki zunifikowanemu API e-mail Unipile - my zajmiemy się odświeżaniem tokenów, uwierzytelnianiem wielodostępnym i XOAUTH2.
Zbuduj przyszłościowy przepływ OAuthŁączenie przez OAuth XOAUTH2
XOAUTH2 to mechanizm SASL, który pozwala uwierzytelnić połączenie z serwerem IMAP za pomocą tokena dostępu OAuth 2.0 zamiast hasła. Token jest uzyskiwany przez standardowy przepływ kodu autoryzacji OAuth (lub poświadczenia klienta dla kont usług), zakodowany w formacie base64 i przekazany do POTWIERDŹ XOAUTH2 Polecenie IMAP.
Gmail (Google)Microsoft 365import imaplib, base64, json
z google.oauth2.credentials import Poświadczenia
z google.auth.transport.requests import Prośba
# Załaduj wcześniej uzyskane dane uwierzytelniające OAuth
# (z procesu google-auth-oauthlib)
poświadczenia = Uwierzytelnienia(
token=TOKEN_DOSTĘPU,
token_odświeżający=REFRESH_TOKEN,
token_uri="https://oauth2.googleapis.com/token",
client_id=CLIENT_ID,
client_secret=SECRET_KLIENTA,
zakresy=["https://mail.google.com/"]
)
# Odśwież token, jeśli wygasł
jeśli creds.expired:
dane uwierzytelniające.odśwież(Prośba())
# Utwórz ciąg znaków XOAUTH2: "user={email}\x01auth=Bearer {token}\x01\x01"
adres_email_użytkownika = "user@gmail.com"
ciąg_autoryzacyjny = f"user={user_email}\x01auth=Bearer {creds.token}\x01\x01"
auth_b64 = base64.b64encode(auth_string.koduj()).decode()
# Otwórz połączenie IMAP i uwierzytelnij się
z imaplib.IMAP4_SSL("imap.gmail.com", 993) jako imap:
imap.uwierzytelnij("XOAUTH2", lambda _: auth_b64)
imap.wybierz("SKRZYNKA ODBIORCZA")
print("Połączono przez XOAUTH2")import imaplib, base64
z msal import AplikacjaDlaKlientaPoufnego
# Pobieranie tokenu za pomocą MSAL (procedura uwierzytelniania klienta dla kont usługowych)
# W przypadku dostępu opartego na upoważnieniu użytkownika należy zamiast tego skorzystać z procedury opartej na kodzie uwierzytelniającym
aplikacja = AplikacjaDlaKlientaPoufnego(
client_id=CLIENT_ID,
autorytet=https://login.microsoftonline.com/{TENANT_ID}",
credential_klienta=KLUCZ_SEKRETNY
)
wynik = aplikacja.pozyskaj_token_dla_klienta(
zakresy=["https://outlook.office365.com/.default"]
)
token_dostępu = wynik["token dostępu"]
# Utwórz ciąg znaków XOAUTH2
adres_email_użytkownika = "user@company.com"
ciąg_autoryzacyjny = f"user={user_email} auth=Bearer {access_token}"
auth_b64 = base64.b64encode(auth_string.koduj()).decode()
# – Połącz z programem Outlook (IMAP)
z imaplib.IMAP4_SSL("outlook.office365.com", 993) jako imap:
imap.uwierzytelnij("XOAUTH2", lambda _: auth_b64)
imap.wybierz("SKRZYNKA ODBIORCZA")
print("Połączono przez XOAUTH2 z programem Outlook")Kluczowe różnice między Gmail a Microsoft XOAUTH2: Gmail wymaga https://mail.google.com/ zakres (pełny dostęp do Gmail). Microsoft wymaga IMAP.AccessAsUser.All (przekazane) lub IMAP.AccessAsApp (aplikacja). Format ciągu XOAUTH2 base64 jest identyczny dla obu dostawców: email\x01auth=Bearer {token}\x01\x01.
Jedna kluczowa kwestia implementacyjna: tokeny wygasają po 3600 sekundach. Długotrwała sesja IMAP IDLE (patrz następna sekcja) otrzyma błąd uwierzytelniania, gdy token wygaśnie w trakcie sesji. Musisz przechwycić NIEUDANE_UWWIERZTELNIENIE błąd, odśwież token za pomocą swojego tokenu odświeżającego, a następnie ponownie nawiąż połączenie IMAP. Ta pętla ponawiania prób nie jest trywialna i jest głównym powodem, dla którego zespoły wybierają zarządzane API, takie jak Przewodnik po zunifikowanym interfejsie API poczty e-mail zamiast surowych połączeń IMAP.
Kompletny przewodnik po konfiguracji OAuth dla firmy Microsoft, w tym uwagi dotyczące zasad dostępu warunkowego, znajdziesz pod adresem Microsoft Graph OAuth dla Outlook przewodnik.
OAuth XOAUTH2 w 10 linijkach. Mechanizm uwierzytelniania dla protokołów IMAP/POP3/SMTP. Wykorzystuje tokeny OAuth 2.0 zamiast tradycyjnych haseł. Klient wysyła żądanie uwierzytelnienia do serwera. Zawiera dane uwierzytelniające w formacie SASL XOAUTH2. Format: "base64(\x01user\x01scopes\x01\x11access_token\x02)". Serwer weryfikuje token OAuth z dostawcą tożsamości. Jeśli token jest ważny, połączenie zostaje uwierzytelnione. Zwiększa bezpieczeństwo, nie wymaga udostępniania hasła. Umożliwia aplikacjom dostęp do skrzynek pocztowych w imieniu użytkownika. Unipile automatycznie obsługuje pozyskiwanie, odświeżanie tokenów i ponowne uwierzytelnianie IMAP. Ty skupiasz się na czytaniu wiadomości e-mail, a nie na zarządzaniu połączeniem.
Zbuduj OAuth XOAUTH2 w 10 liniach z Unipile: 1. `pip install unipile` 2. `from unipile import Unipile` 3. `user_email = "twoj@email.com"` 4. `client_secret = "twoj_sekret"` 5. `client_id = "twoj_id"` 6. `scopes = ["https://www.googleapis.com/auth/gmail.send"]` 7. `unipile = Unipile(user_email, client_secret, client_id, scopes)` 8. `auth_url = unipile.get_authorization_url()` 9. `print(f"Otwórz ten link w przeglądarce: {auth_url}")` 10. `access_token = unipile.get_access_token(input("Wklej kod autoryzacji: "))`IDLE, sondowanie i powiadomienia push: utrzymywanie aktywnego połączenia IMAP
Gdy masz uwierzytelnione połączenie z serwerem IMAP, kolejnym wyzwaniem jest efektywne wykrywanie nowych wiadomości bez przeciążania serwera ciągłymi żądaniami. Obecnie stosowane są trzy wzorce – każdy z różnym czasem oczekiwania, złożonością i wymaganiami infrastrukturalnymi.
| Metoda | Jak to działa | Opóźnienie | Infrastruktura | Najlepszy dla | Ocena |
|---|---|---|---|---|---|
| IMAP IDLE (RFC 2177) | Klient zgłasza problem z komendą IDLE; serwer wysyła powiadomienia EXISTS/RECENT przez otwarte połączenie TCP, gdy nadchodzi nowa poczta. Klient musi wysłać DONE + ponownie wydać IDLE co 29 minut (timeout serwera). | ~1-5 sekund | 1 stałe połączenie TCP na skrzynkę pocztową. Wymaga dedykowanego wątku lub pętli asynchronicznej. | Narzędzia dla jednego użytkownika, klienty desktopowe, monitorowanie z niskim opóźnieniem | Dobrze |
| Sondaż (NOOP / CHECK) | Klient okresowo się rozłącza, wykonuje SELECT + SEARCH UNSEEN, aby wyszukać nowe wiadomości, a następnie się rozłącza. Proste i bezstanowe. | Równa interwałowi odpytywania (zazwyczaj 1-15 min) | Bezstanowy. Działa za NAT-em/firewalem. Brak stałego połączenia. | Przetwarzanie wsadowe, dopuszczalne duże opóźnienia, środowiska, w których zablokowane są połączenia stałe | Dopuszczalne |
| Dostawcy push (Gmail Pub/Sub, webhooky MS Graph) | Dostawca wysyła powiadomienie HTTP do Twojego punktu końcowego webhook po odebraniu nowej poczty. Połączenie IMAP nie jest wymagane w spoczynku. Gmail używa Google Cloud Pub/Sub; Microsoft używa powiadomień o zmianach MS Graph. | Prawie w czasie rzeczywistym(typowe poniżej 1 sekundy) | Wymaga publicznego punktu końcowego HTTPS i subskrypcji Pub/Sub. Brak trwałego połączenia IMAP w spoczynku. | Wielkoskalowe systemy produkcyjne z wieloma kontami, architektury bezserwerowe | Najlepszy w skali |
IDLE to dobry wybór dla prostych integracji gdzie kontrolujesz niewielką liczbę kont. Główne problemy: musisz ponownie połączyć się przed 29-minutowym limitem bezczynności (Gmail ściśle tego przestrzega) i potrzebujesz osobnych połączeń IMAP dla każdej skrzynki pocztowej – co staje się kosztowne przy setkach lub tysiącach kont.
Powiadomienia push od dostawcy są właściwą architekturą dla produkcyjnych systemów wielokontowych. Integracja Gmail z Pub/Sub i webhooki subskrypcyjne Microsoft Graph oba dostarczają powiadomienia w czasie niemal rzeczywistym, nie wymagając stałego połączenia IMAP dla każdego konta. Kompromis: nadal musisz otworzyć połączenie IMAP, aby pobrać treść wiadomości, gdy otrzymasz powiadomienie, co oznacza, że twój kod połączenia IMAP jest nadal potrzebny – po prostu nie jest utrzymywany stale otwarty. Aby odczytywać wiadomości e-mail za pomocą API, zapoznaj się z naszym przewodnikiem dotyczącym odczytywanie wiadomości e-mail przez API oraz wysyłanie e-maili przez API.
Matryca rozwiązywania problemów: przekroczenia limitu czasu, błędy uzgadniania, błędy uwierzytelniania, limity żądań
Poniżej znajduje się ustrukturyzowany spis najczęstszych błędów połączenia z serwerem IMAP. Dopasuj objaw (komunikat o błędzie lub obserwowalne zachowanie) do prawdopodobnej przyczyny i zalecanej poprawki.
| Objaw / Błąd | Kategoria | Prawdopodobna przyczyna | Naprawić |
|---|---|---|---|
| Odrzucono połączenie na porcie 993 | Połączenie | Nieprawidłowy host, IMAP wyłączony w ustawieniach dostawcy lub zapora sieciowa blokująca wychodzące połączenie 993 | Zweryfikuj host z powyższej tabeli. Włącz IMAP w ustawieniach dostawcy (Gmail: Ustawienia > Przekazywanie i POP/IMAP). Sprawdź zaporę sieciową/serwer proxy pod kątem wychodzącego połączenia TCP 993. |
| Przekroczenie limitu czasu uzgadniania SSL / CERTIFICATE_VERIFY_FAILED | TLS | Wygasły lub samopodpisany certyfikat, nieaktualny pakiet CA, zły port (143 zamiast 993) | Użycie ssl.create_default_context() (Python) - nie przechodź ssl._create_unverified_context() w produkcji. Zaktualizuj swój pakiet CA (pip install certifi). Potwierdź połączenie z portem 993. |
| NIEUDANA_AUTHENTHIKACJA / [NIEUDANA_AUTHENTHIKACJA] Nieprawidłowe dane logowania | Auth | Błędne hasło, hasło aplikacji nie zostało wygenerowane, włączona autoryzacja dwuskładnikowa, ale hasło aplikacji nie zostało użyte, uwierzytelnianie podstawowe zablokowane przez dostawcę | Wygeneruj hasło specyficzne dla aplikacji z ustawień bezpieczeństwa dostawcy. W przypadku Gmaila upewnij się, że "Dostęp mniej bezpiecznych aplikacji" nie jest metodą - użyj hasła aplikacji lub OAuth. W przypadku Microsoft sprawdź, czy uwierzytelnianie podstawowe nie jest wyłączone dla najemcy. |
| OTWIERANIE XOAUTH2 - nieprawidłowy_token | OAuth | Token dostępu wygasł (tokeny są ważne przez 3600 sekund), nieprawidłowy ciąg XOAUTH2 w kodowaniu base64, nieprawidłowy zakres | Odśwież token dostępu przed połączeniem. Zweryfikuj format ciągu znaków XOAUTH2: email\x01auth=Bearer {token}\x01\x01. Sprawdź zakres: Gmail potrzebuje https://mail.google.com/; Outlook potrzebuje IMAP.AccessAsUser.All. |
| imaplib.error: polecenie AUTHENTICATE nielegalne w stanie AUTH | Stan | Próba uwierzytelnienia w stanie uwierzytelnionym lub po nieudanej próbie uwierzytelnienia bez resetowania | Zamknij i ponownie otwórz połączenie IMAP przed ponowieniem próby uwierzytelnienia. Nigdy nie ponawiaj próby uwierzytelnienia na tym samym połączeniu po awarii. |
| Połączenie IMAP zrywa się po 29 minutach w trybie IDLE | BEZCZYNNOŚĆ | Limit czasu bezczynności wymuszony przez serwer (standardowo: 30 minut zgodnie z RFC 2177). Gmail wymusza 29 minut. | Problem ZROBIONE między 25. a 27. minutą, a następnie natychmiast wydać ponownie BEZCZYNNOŚĆ. Użyj wątku w tle lub zadania asynchronicznego z 25-minutowym zegarem „heartbeat”. |
| [PRZEKROCZONY LIMIT] lub Zbyt wiele jednoczesnych połączeń | Limit żądań | Przekroczono limit połączeń nałożony przez dostawcę. Gmail pozwala na 15 jednoczesnych połączeń IMAP na konto; Outlook różni się w zależności od planu. | Używaj puli połączeń. Dla Gmaila: maksymalnie 15 jednoczesnych połączeń na konto. Jawnie zamykaj nieaktywne połączenia (WYLOGUJniż rezygnacja z TCP. Zaimplementuj wykładnicze wycofywanie się w przypadku błędów połączeń. |
| NIE [ALARM] Zaloguj się przez przeglądarkę internetową | Auth | Wyzwanie bezpieczeństwa Google aktywowane (nietypowy wzorzec dostępu, nowe IP, wymagane CAPTCHA) | Zaloguj się przez przeglądarkę z tej samej sieci, aby rozwiązać wyzwanie bezpieczeństwa. Rozważ przełączenie się na OAuth – dostęp za pomocą hasła aplikacji z nieznanych adresów IP częściej wywołuje te wyzwania niż OAuth. |
| BYE Autowylogowanie; bezczynność przez zbyt długi czas | Połączenie | Połączenie IMAP w stanie uwierzytelnionym (skrzynka pocztowa nie jest wybrana) było bezczynne zbyt długo | Po uwierzytelnieniu, natychmiast wybierz skrzynkę pocztową lub wydaj polecenie IDLE. Zaimplementuj logikę ponownego połączenia po otrzymaniu komunikatu BYE. |
| FETCH zwraca pustą treść / puste części | Protokół | Wiadomość została usunięta między SEARCH i FETCH lub niezgodność UID po ponownym skanowaniu folderu | Zawsze używaj ID POBIERZ (bez numerów sekwencji) w przypadku operacji wieloetapowych. Obsłuż Żaden bezpiecznie zwracaj wartości z FETCH. Ponownie wydaj polecenie SEARCH po ponownym połączeniu, aby uzyskać nowe UID-y. |
ssl.create_default_context() (Python) - nie przechodź ssl._create_unverified_context() w produkcji. Zaktualizuj swój pakiet CA (pip install certifi). Potwierdź połączenie z portem 993.
email\x01auth=Bearer {token}\x01\x01. Sprawdź zakres: Gmail potrzebuje https://mail.google.com/; Outlook potrzebuje IMAP.AccessAsUser.All.
ZROBIONE między 25. a 27. minutą, a następnie natychmiast wydać ponownie BEZCZYNNOŚĆ. Użyj wątku w tle lub zadania asynchronicznego z 25-minutowym zegarem „heartbeat”.
WYLOGUJniż rezygnacja z TCP. Zaimplementuj wykładnicze wycofywanie się w przypadku błędów połączeń.
ID POBIERZ (bez numerów sekwencji) w przypadku operacji wieloetapowych. Obsłuż Żaden bezpiecznie zwracaj wartości z FETCH. Ponownie wydaj polecenie SEARCH po ponownym połączeniu, aby uzyskać nowe UID-y.
Przestań debugować błędy IMAP. Unipile udostępnia czyste obiekty poczty e-mail przez REST — bez stanowego automatu IMAP, logiki odświeżania tokenów ani zarządzania pulami połączeń.
Przestań debugować IMAP - Zacznij tworzyćDlaczego produkcyjne IMAP na dużą skalę jest trudniejsze niż się wydaje
Otwarcie pojedynczego połączenia z serwerem IMAP do skrzynki odbiorczej Gmail to 15 linii kodu w Pythonie. Skalowanie tego do setek lub tysięcy użytkowników w produkcie SaaS stanowi fundamentalnie inne wyzwanie inżynieryjne. Oto szczere omówienie, gdzie surowe połączenia IMAP tworzą nieoczywistą złożoność.
Tokeny dostępu wygasają co 3600 sekund. W przypadku 1000 połączonych kont potrzebujesz zadania w tle, które proaktywnie odświeża tokeny przed wygaśnięciem, obsługuje rotację tokenów odświeżających (Google obraca je w pewnych warunkach) i zarządza przypadkiem, gdy użytkownik cofa dostęp – czego dowiadujesz się dopiero przy następnym użyciu tokenu.
Każda aktywna sesja IMAP przechowuje stan: aktualnie wybraną skrzynkę pocztową, ostatnio widziane UID, licznik IDLE. Jeśli serwer zostanie zrestartowany, tracisz cały ten stan i musisz przeprowadzić ponowną synchronizację od zera – potencjalnie pobierając tysiące wiadomości, które już przetworzyłeś. Potrzebujesz trwałego magazynu stanu dla każdego konta.
Przejściowe błędy (problemy z siecią, błędy serwera 500, odpowiedzi z limitami żądań) wymagają logiki ponawiania z wykładniczym opóźnieniem i jitterem. Naiwne pętle ponawiania bombardują dostawców i prowadzą do tymczasowych banów IP. Potrzebujesz odpowiedniej kolejki zadań z konfigurowalnymi opóźnieniami ponawiania i obsługą martwych list dla trwale nieudanych kont.
Tokeny odświeżające OAuth to długoterminowe poświadczenia, które udzielają pełnego dostępu do poczty e-mail. Muszą być szyfrowane podczas przechowywania kluczem opartym na KMS, kontrolowane pod względem dostępu na poziomie infrastruktury i rotowane w przypadku jakichkolwiek oznak naruszenia. Jest to znacząca powierzchnia bezpieczeństwa, która wymaga odpowiedniej infrastruktury zarządzania kluczami.
Gmail ogranicza liczbę jednoczesnych połączeń IMAP do 15 na konto. Jeśli twoja aplikacja otwiera więcej połączeń niż dozwolono, otrzymuje błędy OVERQUOTA. Jednocześnie dostawcy nakładają również limity przepustowości na całkowitą ilość przesyłanych danych. Potrzebujesz puli połączeń, ograniczania żądań i śledzenia limitów na konto.
Etykiety Gmaila a foldery IMAP, niestandardowe nazewnictwo folderów przez Outlook dla wysłanych/usuniętych, serwery IMAP zwracające odpowiedzi CAPABILITY niezgodne z tym, co faktycznie obsługują, oraz serwery, które cicho zrywają połączenia podczas operacji FETCH na dużych załącznikach. Każdy dostawca ma swój unikalny zestaw dziwactw, które ujawniają się dopiero w praktyce.
To nie jest argument przeciwko tworzeniu niestandardowej integracji IMAP – dla narzędzia jednodostawcowego, jednego użytkownika, surowy IMAP jest całkowicie rozsądny. Ale dla każdego produktu, który potrzebuje czytaj i synchronizuj e-maile z wielu dostawców i wielu kont użytkowników, narzut operacyjny związany z utrzymaniem niestandardowej warstwy IMAP zazwyczaj przewyższa koszt korzystania z dedykowanego API poczty e-mail. Przewodnik po zunifikowanym interfejsie API poczty e-mail szczegółowo omawia kompromisy architektoniczne.
Synchronizacja poczty produkcyjnej bez narzutu IMAP. Unipile obsługuje pulowanie połączeń, odświeżanie tokenów, ponawianie prób w przypadku błędów i normalizację wielu dostawców – wystarczy wywołać API.
Buduj na dużą skalę bez narzutu IMAPTworzenie integracji IMAP bez zarządzania połączeniem: Unipile
Jeśli dotarłeś(aś) do tego miejsca, masz jasny obraz tego, co jest potrzebne do utrzymania surowych połączeń IMAP w środowisku produkcyjnym: pętle odświeżania tokenów OAuth, zarządzanie stanem na konto, pulowanie połączeń, logika ponawiania prób i specyficzne dla dostawcy niedoskonałości dla serwerów Gmail, Outlook i IMAP. Unipile abstrahuje całą tę warstwę i udostępnia jedno API REST do odczytu, wysyłania i synchronizowania wiadomości e-mail między wszystkimi trzema, z 5-minutowym przewodnikiem „szybki start” i mniej niż 10 liniami kodu na operację.
Unipile zarządza pełnym przepływem OAuth dla Gmail i Microsoft 365: pozyskiwaniem tokenów, odświeżaniem i rotacją. Nigdy nie masz bezpośredniego dostępu do tokena odświeżania.
Jeden interfejs API, jeden schemat odpowiedzi. Odczytuj e-maile z skrzynki odbiorczej Gmail i firmowego serwera IMAP przy użyciu tego samego wywołania GET /emails. Bez specyficznego dla dostawcy parsowania.
Otrzymuj powiadomienia HTTP po nadejściu nowych wiadomości e-mail. Brak konieczności zarządzania stałym połączeniem IMAP, brak problemu z 29-minutowym limitem czasowym IDLE ani dedytowanego wątku na konto.
Połącz konta użytkowników za pomocą hostowanego przepływu OAuth Unipile. Każde połączone konto otrzymuje własny identyfikator konta (`account_id`). Skaluj od 1 do 10 000 połączonych kont bez zmiany kodu integracji.
Poświadczenia zaszyfrowane w spoczynku za pomocą kluczy wspieranych przez KMS. Unipile posiada certyfikat SOC 2 Type II i ocenę CASA Tier 2. Żadne hasła IMAP ani tokeny OAuth nie są przechowywane w Twojej bazie danych.
import żądania
BASE_URL = "https://api7.unipile.com:13047/api/v1"
NAGŁÓWKI = {"X-API-KEY": "twój-klucz-api-unipile"}
# Krok 1: Wymień wszystkie połączone konta
konta = żądania.uzyskać(
f"{BAZA_URL}/konta", nagłówki=NAGŁÓWKI
).json()
account_id = konta["przedmioty"][0]["id"]
# Krok 2: Przeczytaj wiadomości w skrzynce odbiorczej
e-maile = żądania.uzyskać(
f"{BASE_URL}/emails",
nagłówki=NAGŁÓWKI,
parametry={"account_id": identyfikator_konta, "limit": 10}
).json()
dla e-mail w e-maile"przedmioty"]:
print(email"temat"], e-mail["od_uczestnika"])
# Brak połączenia IMAP, brak odświeżenia tokenu,
# – bez kontekstu SSL, bez maszyny stanów.
Często zadawane pytania
Często zadawane pytania dotyczące połączeń z serwerem IMAP, portów, uwierzytelniania i migracji OAuth.
Połączenie z serwerem IMAP to trwała sesja TCP między klientem poczty e-mail a serwerem pocztowym, która wykorzystuje protokół Internet Message Access Protocol do synchronizowania, pobierania i zarządzania wiadomościami e-mail przechowywanymi na serwerze – bez ich pobierania lub usuwania lokalnie. W przeciwieństwie do POP3, IMAP przechowuje wiadomości na serwerze i synchronizuje stan (odczytane, oznaczone flagą, przeniesione) na wszystkich podłączonych urządzeniach. Dla deweloperów jest to podstawowy protokół do tworzenia integracji pocztowych, które działają w Gmailu, Outlooku i każdym standardowym. INTERFEJS API IMAP.
Użycie port 993 dla IMAP przez SSL/TLS (niejawny TLS). Jest to nowoczesny standard i jest wymagany przez wszystkich głównych dostawców usług w chmurze, w tym Gmail i Outlook. Port 143 służy do uaktualnień STARTTLS i jest odpowiedni tylko dla samodzielnie hostowanych serwerów poczty. Nigdy nie łącz się z serwerem poczty w chmurze na porcie 143 w środowisku produkcyjnym – większość teraz całkowicie odrzuca takie połączenia. Jeśli nie masz pewności, zawsze domyślnie używaj portu 993 z ssl=True.
Tak, bez wyjątku. SSL/TLS jest obowiązkowy dla każdego połączenia serwera IMAP, które przesyła dane uwierzytelniające. Nowoczesne serwery pocztowe całkowicie odrzucają połączenia w postaci czystego tekstu. RFC 9051 (IMAP4rev2) formalnie wymaga TLS dla wszystkich uwierzytelnionych sesji. Zawsze używaj port 993 z jawnym TLS dla dostawców chmurowych. W przypadku połączenia z serwerem hostowanym lokalnie na porcie 143, należy przeprowadzić aktualizację do TLS za pomocą polecenia STARTTLS i zweryfikować certyfikat serwera - nigdy nie używaj ssl._create_unverified_context() w produkcji.
Adres serwera IMAP dla Gmail to imap.gmail.com on port 993 z protokołem SSL/TLS. Przed połączeniem należy włączyć dostęp IMAP w Ustawieniach Gmaila w sekcji "Przekazywanie i POP/IMAP". Uwierzytelnianie wymaga hasła specyficznego dla aplikacji (jeśli włączono 2FA) lub OAuth 2.0 XOAUTH2 z zakresem https://mail.google.com/. Google ograniczył uwierzytelnianie podstawowe dla nowych aplikacji i zdecydowanie zaleca OAuth do wszelkich programistycznych dostępów IMAP.
Adres serwera IMAP dla osobistych kont Outlook.com i firmowych kont Microsoft 365 to outlook.office365.com on port 993 z SSL/TLS. Pamiętaj, że firma Microsoft wycofuje wsparcie dla uwierzytelniania podstawowego (nazwa użytkownika/hasło) dla protokołu IMAP w Grudzień 2026. Wszystkie integracje muszą zostać przeniesione do OAuth 2.0 XOAUTH2 przed tym terminem. Zobacz nasz Microsoft Graph OAuth dla Outlook instrukcja kroków migracji.
Potrzebujesz hasła specyficznego dla aplikacji, jeśli Twoje konto ma włączone uwierzytelnianie dwuskładnikowe i używasz uwierzytelniania podstawowego (Basic Auth) dla IMAP. Hasła aplikacji to 16-znakowe tokeny generowane z ustawień bezpieczeństwa Twojego dostawcy (strona bezpieczeństwa konta Google dla Gmaila, Apple ID dla iCloud), które zastępują Twoje prawdziwe hasło, nie dając pełnego dostępu do konta. W przypadku produkcyjnych aplikacji wieloużytkownikowych, OAuth 2.0 jest zdecydowanie preferowany hasła specyficzne dla aplikacji – jest to bezpieczniejsze, nie wymaga przechowywania żadnych danych uwierzytelniających użytkownika w Twojej aplikacji i jest jedyną metodą, która pozostanie ważna po wycofaniu protokołu Microsoft Basic Auth w grudniu 2026 r.
Tak, dla usług Microsoft. Firma Microsoft potwierdziła ostateczne zakończenie wsparcia dla uwierzytelniania Basic w protokołach IMAP, POP3 i SMTP w Exchange Online w Grudzień 2026, wpływając na wszystkich najemców, w tym tych z istniejącymi zwolnieniami. Wszelkie integracje wykorzystujące uwierzytelnianie użytkownik/hasło do Outlooka lub Microsoft 365 IMAP przestaną działać po tym terminie. Google już ograniczyło dostęp do Basic Auth dla Gmaila i wymaga haseł do aplikacji lub OAuth do wszelkiego programowego dostępu od 2022 roku. Jeśli Twoja integracja IMAP łączy się z kontami Microsoft, musisz migrować do OAuth 2.0 XOAUTH2 przed grudniem 2026 r.
Aby połączyć się z serwerem IMAP z użyciem OAuth 2.0, należy użyć mechanizmu SASL XOAUTH2. Po uzyskaniu tokena dostępu za pomocą standardowego przepływu kodu autoryzacyjnego OAuth, zakoduj ciąg znaków email\x01auth=Bearer {token}\x01\x01 jako base64, a następnie przekazać go do POTWIERDŹ XOAUTH2 Polecenie IMAP. Dla Gmaila, wymagany zakres to https://mail.google.com/. W przypadku Microsoft 365 użyj biblioteki MSAL do uzyskania tokenu z IMAP.AccessAsUser.All zakres. Tokeny dostępu wygasają po 3600 sekundach i muszą zostać odświeżone przed ponownym połączeniem - zaimplementuj kontrolę odświeżania tokenu przed każdą nową sesją IMAP. Zobacz pełne przykłady kodu w sekcji XOAUTH2 powyżej.
PL 
EN 
FR 
ES 
DE 
IT 
BR 
NL 
TR