LinkedIn
Instagram
WhatsApp
Telegram
Kalendarz Google
Dołącz do społeczności SlackAPI OAuth do poczty e-mail: uwierzytelnianie skrzynek pocztowych użytkowników Prawidłowa Droga
Przestań przechowywać hasła. API poczty e-mail OAuth pozwala Twojej aplikacji bezpiecznie uzyskiwać dostęp do skrzynek odbiorczych użytkowników – za pomocą tokenów z usług Gmail, Outlook i IMAP, które można cofnąć i ograniczyć zakresowo. Ten przewodnik omawia każdy przepływ OAuth, każdy zakres, każde potencjalne potknięcie i jak wdrożyć w 5 minut za pomocą zunifikowanej warstwy uwierzytelniania hostowanej.
// Połącz dowolną skrzynkę pocztową użytkownika przez OAuth - 1 wywołanie API
const response = czekać fetch(
'https://api6.unipile.com:13226/api/v1/hosted/accounts/link',
{
method: 'POST',
headers: {
'Klucz API X': 'TWÓJ_KLUCZ_API',
'Content-Type': 'application/json'
},
body: JSON.stringify({
typ: 'GOOGLE', // lub MICROSOFT, IMAP
imię: 'użytkownik_123'
})
}
);
const { adres url } = czekać odzew.json();
// Przekieruj użytkownika na adres URL - OAuth obsługiwany przez Unipile
Czym jest OAuth Email API?
An API e-mail OAuth to programowalny interfejs, który umożliwia aplikacji dostęp do skrzynek pocztowych użytkownika za pomocą tokenów OAuth 2.0 – bez konieczności obsługi ani przechowywania hasła użytkownika. Zamiast prosić użytkowników o dane uwierzytelniające, przekierowujesz ich przez ekran zgody dostawcy, otrzymujesz krótkotrwały token dostępu i używasz go do odczytywania, wysyłania lub synchronizowania poczty e-mail w ich imieniu. Rozróżnienie ma znaczenie: chodzi o dostęp skrzynki pocztowe należące do użytkowników (Gmail, Outlook, poczta osobista), nie wysyłaj wiadomości transakcyjnych przez usługi przekaźnikowe SMTP, takie jak SendGrid.
An API e-mail OAuth jest połączeniem przepływu autoryzacji OAuth 2.0 (do uwierzytelniania użytkownika i uzyskiwania delegowanego dostępu) oraz interfejsu API poczty e-mail (do odczytywania, wysyłania, wyszukiwania lub synchronizowania skrzynki pocztowej użytkownika). Warstwa OAuth generuje kryptograficznie podpisany, odwoływalny, ograniczony zakresem token dostępu. Interfejs API poczty e-mail wykorzystuje ten token do interakcji z Gmail, Outlook lub dowolną skrzynką pocztową zgodną z IMAP – wszystko to bez ujawniania hasła użytkownika.
- Przechowuje hasła w postaci zwykłego tekstu lub zaszyfrowane w Twojej bazie danych
- Pełny dostęp do skrzynki pocztowej – brak kontroli zakresu
- Zablokowane przez Google/Microsoft od 2026 roku
- Odpowiedzialność RODO/SOC2 za przechowywanie poświadczeń
- Brak przechowywania haseł – tylko krótkotrwałe tokeny
- Granularne zakresy – tylko do odczytu, tylko do wysyłania, czy pełne
- Możliwe do cofnięcia w dowolnym momencie przez użytkownika
- Zgodne z RODO, SOC2
Dlaczego OAuth zastąpił dostęp do poczty e-mail oparty na hasłach
Używanie IMAP z nazwą użytkownika i hasłem było kiedyś standardowym sposobem programowego dostępu do poczty użytkownika. Ta era minęła. Google wycofał uwierzytelnianie podstawowe dla Gmaila w 2022 roku, a Microsoft zakończył wyłączanie uwierzytelniania podstawowego dla Exchange Online w październiku 2022 roku, z ostatnim etapem dla pozostałych protokołów w 2026 roku. Jeśli Twoja aplikacja nadal opiera się na dostępie IMAP opartym na hasłach, jest już uszkodzona lub wkrótce przestanie działać.
Tokeny OAuth są krótkotrwałe (zazwyczaj 1 godzinę) i ograniczone zakresem. Nawet jeśli wyciekną, nie można ich użyć do zalogowania się jako użytkownik, zmiany jego hasła ani uzyskania dostępu do innych usług. Nigdy nie dotykasz danych uwierzytelniających użytkownika.
Microsoft zakończył wycofywanie podstawowego uwierzytelniania dla Exchange Online i starszego IMAP w 2026 roku. Każda aplikacja nadal korzystająca z nazwy użytkownika i hasła do uzyskiwania dostępu do skrzynek pocztowych Outlook lub Microsoft 365, będzie otrzymywać błędy 401 Unauthorized.
Przechowywanie haseł użytkowników – nawet zahaszowanych – stanowi obciążenie związane ze zgodnością. Zasada minimalizacji danych w RODO wymaga, aby nie gromadzić tego, czego się nie potrzebuje. Audytorzy SOC2 zwracają uwagę na przechowywanie danych uwierzytelniających.
Krytyczny Hasła aplikacji Google i starsze protokoły firmy Microsoft nie są już wystarczające dla aplikacji produkcyjnych. Jeśli tworzysz produkt, który uzyskuje dostęp do skrzynek pocztowych użytkowników, API e-mail OAuth nie jest opcjonalne – to jedyna zgodna z przepisami ścieżka naprzód w 2026 roku.
Jak działa OAuth dla interfejsów API poczty e-mail (krok po kroku)
Przepływ kodu autoryzacji jest standardowym przepływem OAuth 2.0 dla aplikacji po stronie serwera, które potrzebują dostępu do poczty e-mail użytkownika. Zrozumienie go od początku do końca pomaga w jego prawidłowej implementacji, diagnozowaniu problemów z tokenami i wyjaśnianiu go zespołowi ds. bezpieczeństwa.
Konstruujesz adres URL z twoim client_id, a przekierowanie_uri, żądany zakres, losowy stan parametr (ochrona CSRF) oraz typ_odpowiedzi=kod. Użytkownik jest przekierowywany do ekranu zgody Google lub Microsoft.
Ekran zgody wyświetla nazwę aplikacji, logo i dokładnie te uprawnienia, o które prosisz. Użytkownik zatwierdza (udziela zgody) lub odrzuca. Najczęstszą przyczyną odrzucenia zgody jest żądanie zbyt wielu zakresów (scopes) na tym etapie.
Po uzyskaniu zgody, dostawca przekierowuje do Twojej przekierowanie_uri krótkotrwały kod parametr (ważny przez około 10 minut). Zweryfikuj stan parametr pasuje do tego, co wysłano, aby zapobiec atakom CSRF.
POST serwer-do-serwera do punktu końcowego tokenu z twoim client_id, client_secret, the kodoraz grant_type=authorization_code. Otrzymujesz token_dostępu i (jeśli zażądałeś dostępu offline) a token_odświeżający.
Przekaż token dostępu w Autoryzacja: Bearer nagłówek przy każdym zgłoszeniu do API. Kiedy wygaśnie (zazwyczaj po 1 godzinie), użyj tokenu odświeżania, aby uzyskać nowy token dostępu bez interakcji użytkownika.
Tokeny dostępu kontra tokeny odświeżania: cykl życia
Ważny przez 1 godzinę (Google) lub 1 godzinę (Microsoft). Przekazywany w nagłówku Authorization przy każdym wywołaniu API. Po wygaśnięciu wywołanie API OAuth dla poczty e-mail zwraca błąd 401 – sygnał do odświeżenia.
Ważny do odwołania (Google) lub 90 dni nieaktywności (Microsoft). Nigdy nie wysyłany do punktów końcowych API - używany tylko w komunikacji typu serwer-serwer do uzyskiwania nowych tokenów dostępu. Musi być zaszyfrowany w spoczynku.
Zbuduj ujednolicony przepływ OAuth w kilka minut
Pomiń poszczególne autoryzacje dostawców. Jedno wywołanie API Unipile zastępuje trzy integracje OAuth.
Przepływy OAuth wg dostawcy: Google i Microsoft
Google i Microsoft implementują OAuth 2.0 inaczej – różne punkty autoryzacji, różne zakresy, różne punkty tokenów i różne procesy weryfikacji. IMAP jest zabezpieczeniem opartym na poświadczeniach dla dostawców bez znormalizowanego OAuth. Oto, co musisz wiedzieć o każdym przypadku.
Implementacja OAuth w Google wykorzystuje standardowy przepływ kodu autoryzacji. Punkt końcowy tokenu to https://oauth2.googleapis.com/token. Krytyczna złożoność to Google CASA (Cloud Application Security Assessment): gdy Twoja aplikacja przekroczy 100 użytkowników, musisz przejść przegląd bezpieczeństwa. W przypadku wrażliwych zakresów, takich jak gmail.zmodyfikuj lub gmail.tylko_do_odczytu, Weryfikacja aplikacji jest wymagana przed użyciem w środowisku produkcyjnym. W celu uzyskania pełnych Integracja z Gmail API – dogłębne omówienie, zobacz nasz dedykowany przewodnik. Szczegóły implementacji znajdują się w Dokumentacja Google OAuth Unipile.
Kod autoryzacyjny # do uzyskania dostępu do Gmaila + tokeny odświeżające
zwijać się -X POST https://oauth2.googleapis.com/token \
-d "kod=KOD_AUTORYZACYJNY" \
-d "client_id=TWÓJ_CLIENT_ID" \
-d "client_secret=TWÓJ_CLIENT_SECRET" \
-d "redirect_uri=https://yourapp.com/callback" \
-d "typ_dostępu=kod_autoryzacyjny"
Odpowiedź #: { "access_token": "...", "refresh_token": "...", "expires_in": 3600 }
Microsoft korzysta z swojej Platformy Tożsamości (wcześniej Azure AD v2). Punkt końcowy tokenu to https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token. Weryfikacja wydawcy jest wymagana, zanim Twoja aplikacja OAuth dla interfejsu API poczty e-mail będzie mogła żądać wrażliwych zakresów poczty w środowisku produkcyjnym. Microsoft wycofał podstawowe uwierzytelnianie dla wszystkich protokołów Exchange Online – OAuth jest obowiązkowy. Zobacz nasze Kompletny przewodnik po poczcie e-mail w Microsoft Graph po pełne szczegóły i Dokumentacja Unipile Microsoft OAuth do celów referencyjnych wdrożenia.
Kod wymiany # dla tokenów OAuth firmy Microsoft
zwijać się -X POST https://login.microsoftonline.com/common/oauth2/v2.0/token \
-d "kod=KOD_AUTORYZACYJNY" \
-d "client_id=TWÓJ_CLIENT_ID" \
-d "client_secret=TWÓJ_CLIENT_SECRET" \
-d "redirect_uri=https://yourapp.com/callback" \
-d "typ_dostępu=kod_autoryzacyjny" \
-d "scope=https://graph.microsoft.com/Mail.Read offline_access"
Odpowiedź #: { "access_token": "...", "refresh_token": "...", "expires_in": 3600 }
IMAP nie jest dostawcą OAuth – jest to protokół uwierzytelniający się za pomocą nazwy użytkownika/hasła lub haseł aplikacji (takich jak hasło aplikacji Google lub hasło wygenerowane przez iCloud). Jest to rozwiązanie awaryjne dla niestandardowych serwerów pocztowych, domen firmowych spoza Microsoft 365 oraz wszelkich dostawców bez standardowego przepływu OAuth. XOAUTH2 istniał jako rozszerzenie IMAP SASL dla niewielkiej liczby dostawców, ale został w dużej mierze porzucony – Yahoo zaprzestało jego implementacji w 2022 roku. W większości wdrożeń IMAP, Unipile uwierzytelnia się bezpośrednio za pomocą danych uwierzytelniających. Zobacz pełne Przewodnik integracji IMAP do konfiguracji serwera i danych uwierzytelniających.
import base64, imaplib
# Utwórz ciąg znaków XOAUTH2 na podstawie tokenu dostępu OAuth
def konstruuj_xoauth2(adres_email_użytkownika, token_dostępu):
auth_str = użytkownik={user_email}\x01auth=Bearer {access_token}\x01\x01"
return base64.b64encode(auth_str.encode()).decode()
# – Połącz się przez IMAP przy użyciu XOAUTH2
połączyć = imaplib.IMAP4_SSL("imap.mail.yahoo.com")
auth_str = konstruuj_xoauth2("user@yahoo.com", token dostępu)
połączenie.uwierzytelnij("XOAUTH2", lambda x: auth_str)Ukryta złożoność wielodostawcowego OAuth
Wdrożenie interfejsu API poczty e-mail OAuth dla jednego dostawcy zajmuje kilka dni. Poprawne wdrożenie Gmail, Outlook i IMAP – z produkcyjnym zarządzaniem tokenami, obsługą błędów i zgodnością – zazwyczaj zajmuje od 4 do 8 tygodni pracy inżynierskiej. Oto dlaczego.
Konsola Google Cloud, Azure Portal i Yahoo Developer Network to 3 zupełnie inne panele o różnym UX, różnych przepływach rejestracji aplikacji i różnych wymaganiach weryfikacyjnych. Każde obracanie poświadczeń dotyka wszystkich 3.
Wrażliwe zakresy Gmail (w tym gmail.tylko_do_odczytu) są ograniczone do 100 użytkowników do czasu pozytywnego przejścia oceny CASA Tier 2. Obejmuje to testy przeprowadzane w laboratorium autoryzowanym przez CASA, test penetracyjny oraz formalny przegląd bezpieczeństwa – trwa to zazwyczaj od 6 do 12 tygodni, a koszt wynosi od 10 000 do 25 000 dolarów.
Microsoft wymaga weryfikacji wydawcy dla aplikacji żądających poufnych zakresów poczty e-mail. Bez niej użytkownicy zobaczą na ekranie zgody czerwone ostrzeżenie o "niezweryfikowanym wydawcy". Proces weryfikacji wymaga aktywnego konta w programie Microsoft Partner Network z zweryfikowaną domeną.
Tokeny odświeżające Google wygasają po 6 miesiącach braku aktywności (lub natychmiast, jeśli użytkownik je cofnie). Tokeny Microsoft wygasają po 90 dniach braku aktywności. Tokeny Yahoo/IMAP XOAUTH2 mają różne okresy ważności w zależności od dostawcy. Twoja warstwa zarządzania tokenami musi obsługiwać wszystkie 3 przypadki inaczej.
Google, Microsoft i Yahoo renderują ekrany zgody w różny sposób – inne brandowanie, inne opisy zakresu, inne schematy interfejsu użytkownika. Twoi użytkownicy widzą 3 różne przepływy w zależności od ich dostawcy poczty e-mail, co prowadzi do niekonsekwentnego UX i wyższych wskaźników rezygnacji.
Punkty końcowe OAuth się zmieniają. Nazwy zakresów są wycofywane. Dodawane są nowe wymagania bezpieczeństwa. Każdy dostawca ogłasza przełomowe zmiany w różnych terminach. Ktoś w Twoim zespole musi stale śledzić 3 blogi dostawców, 3 dzienniki zmian i 3 kalendarze zgodności.
Pomiń złożoność OAuth całkowicie
Obsługa uwierzytelniania w chmurze, zarządzanie zakresami, obsługa odświeżania. Unipile zajmuje się wszystkim, dzięki czemu możesz skupić się na swoim produkcie.
Architektura API OAuth do obsługi poczty e-mail: Porównanie 3 podejść
Istnieją 3 architektury do budowy warstwy API poczty e-mail OAuth. Każda z nich ma zasadniczo inny koszt wdrożenia, obciążenie konserwacyjne i profil bezpieczeństwa. Właściwy wybór zależy od tego, czy łączność e-mail jest Twoim podstawowym produktem, czy funkcją, którą wdrożysz obok swojego głównego produktu.
| Wymiar | Dostawca Bezpośredni OAuth (x3) | Samodzielnie hostowana brama OAuth | Zunifikowane hostowane OAuth (Unipile) Zalecane |
|---|---|---|---|
| Czas do pierwszego skrzynki pocztowej połączonej | 3-7 dni (na dostawcę) | 2-4 tygodnie | 5 minut |
| Przepływy OAuth do implementacji | 3 oddzielne przepływy | 3 przepływy + logika routingu | 1 hostowany punkt końcowy linku |
| Opinia o Google CASA | Zajmij się tym (6–12 tygodni, $10k+) | Ty tym zajmij się | Obsługiwane przez Unipile |
| Weryfikacja Microsoft Publisher | Ty tym zajmij się | Ty tym zajmij się | Obsługiwane przez Unipile |
| Zarządzanie odświeżaniem tokenów | 3 strategie budowania | Niestandardowe dla dostawcy | Automatyczna, przejrzysta |
| API do odczytu/wysyłania wiadomości e-mail | 3 różne API | Warstwa abstrakcji wymagana | 1 ujednolicone REST API |
| Webhook dla nowych wiadomości e-mail | Push/pull dla dostawcy | Niestandardowy | Ujednolicone zdarzenia webhook |
| Zgodność z SOC2 / RODO | Odpowiedzialność użytkownika | Odpowiedzialność użytkownika | Unipile posiada certyfikat SOC2 |
| Bieżąca konserwacja | Wysokie (3 logi zmian dostawcy) | Wysoki | Zero - obsłużone przez Unipile |
| Najlepszy dla | Produkty natywne dla poczty e-mail od jednego dostawcy | Duże zespoły z dedykowaną infrastrukturą | Każdy zespół wysyłający szybko |
Budować czy kupić: Hostowane OAuth API e-mail w 5 minut
Zamiast tworzyć 3 oddzielne przepływy OAuth, Unipile udostępnia hostowany link uwierzytelniający, który obsługuje za Ciebie Google OAuth, Microsoft Identity i IMAP OAuth. Twoja aplikacja generuje link, przekierowuje użytkownika i otrzymuje webhook po połączeniu skrzynki pocztowej. API OAuth do obsługi poczty e-mail jest wtedy natychmiast gotowe do użycia – bez konfiguracji w konsoli, bez przeglądu CASA, bez konieczności tworzenia logiki odświeżania tokenów.
Krok 1: Wygeneruj link autoryzacyjny hostowany
Jedno wywołanie API do utworzenia hostowanej sesji uwierzytelniania. Określ typ dostawcy i nazwę konta. Unipile zwraca adres URL przekierowania użytkownika do ekranu zgody OAuth.
// Połącz użytkownika Gmail za pomocą hostowanego przez Unipile API OAuth dla poczty e-mail
const response = czekać fetch(
'https://api6.unipile.com:13226/api/v1/hosted/accounts/link',
{
method: 'POST',
headers: {
'Klucz API X': 'Klucz_API_YOUR_UNIPILE',
'Content-Type': 'application/json'
},
body: JSON.stringify({
typ: 'GOOGLE',
imię: 'użytkownik_alicja_123',
success_redirect_url: 'https://yourapp.com/połączony',
failure_redirect_url: 'https://yourapp.com/błąd'
})
}
);
const { url, obiekt } = czekać odzew.json();
// Przekieruj użytkownika do adresu URL - Unipile obsługuje zgodę OAuth
window.location.href = adres URL;Krok 2: Połącz użytkownika programu Outlook
Ten sam punkt końcowy, ten sam wzorzec. Zmień typ do MICROSOFT. Brak Portalu Azure, brak weryfikacji wydawcy do zarządzania po Twojej stronie.
import żądania
# – Połącz użytkownika programu Outlook za pomocą interfejsu API poczty e-mail Unipile OAuth
response = żądania.stanowisko(
"https://api6.unipile.com:13226/api/v1/hosted/accounts/link",
nagłówki={"X-API-KEY": "TWÓJ_KLUCZ_API_UNIPILE"},
json={
"typ": "MICROSOFT",
"name": "user_bob_456",
"adres_przekierowania_sukces": "https://yourapp.com/połączono"
}
)
auth_url = response.json()["url"]
# Przekierowanie do auth_url – proces uwierzytelniania Microsoft obsługiwany przez UnipileKrok 3: Odbieranie webhooka na koncie.połączone
Po uzyskaniu zgody OAuth, Unipile wysyła webhooka do Twojego punktu końcowego. Ładunek zdarzenia zawiera nowy account_id - które przechowujesz i które wykorzystujesz we wszystkich kolejnych odczytaj API poczty e-mail oraz API do wysyłania e-maili połączenia.
Zdarzenie webhooku: Kiedy użytkownik zakończy proces OAuth, Unipile wysyła account.connected zdarzenie do adresu URL twojego webhooka. Ładunek zawiera account_id (zapamiętaj to), the provider (GOOGLE / MICROSOFT / IMAP) oraz powiązany adres e-mail. To jedyny stan, który musisz utrwalić – Unipile zarządza wszystkimi tokenami OAuth wewnętrznie.
Omiń 8-tygodniową implementację OAuth. Połącz skrzynki pocztowe w kilka minut.
Hostowane API pocztowe OAuth Unipile obsługuje Google CASA, weryfikację wydawcy Microsoft, XOAUTH2 oraz odświeżanie tokenów dla wszystkich dostawców. Twoi użytkownicy łączą swoje skrzynki pocztowe za pomocą jednego, hostowanego przepływu – Ty otrzymujesz ujednolicone API do odczytu, wysyłania i synchronizacji.
Zarządzanie tokenami OAuth: Odświeżanie, unieważnianie, rotacja
Zarządzanie tokenami jest najbardziej wymagającą operacyjnie częścią tworzenia API poczty e-mail OAuth. Tokeny dostępu wygasają, tokeny odświeżające są unieważniane przez użytkowników, a Twój system musi sobie z tym wszystkim radzić w sposób płynny – w przeciwnym razie ryzykujesz, że Twoi użytkownicy utracą dostęp do swoich skrzynek pocztowych bez ostrzeżenia.
Najlepsze praktyki dotyczące przechowywania tokenów
- Szyfruj tokeny odświeżania w spoczynku za pomocą AES-256 lub usługi KMS w chmurze (AWS KMS, GCP Cloud KMS, Azure Key Vault). Nigdy nie przechowuj ich w bazie danych w postaci zwykłego tekstu.
- Nigdy nie loguj tokenów dostępu ani tokenów odświeżania. Systemy logowania strukturalnego, takie jak Datadog lub Splunk, powinny mieć pola tokenów zamaskowane lub zredagowane.
- Przechowuj tokeny w dedykowanym magazynie sekretów (Vault, AWS Secrets Manager) zamiast w głównej bazie danych aplikacji, aby zminimalizować zasięg szkód w przypadku naruszenia bezpieczeństwa bazy danych.
- Wdróż rotację tokenów: po otrzymaniu nowego tokenu odświeżającego podczas wywołania odświeżania (niektórzy dostawcy wydają nowe tokeny odświeżające przy każdym użyciu), natychmiast unieważnij stary.
Grzeczne postępowanie z błędami odświeżania
Kiedy token odświeżania wygaśnie lub zostanie unieważniony, wywołanie odświeżenia zwróci błąd 400 lub 401. Twoje API OAuth do e-maili musi przechwycić ten błąd i uruchomić przepływ ponownej autoryzacji dla użytkownika – nie powinno to kończyć się cichym błędem. Najgorszym scenariuszem jest użytkownik, który myśli, że e-maile są czytane, podczas gdy token został unieważniony od tygodni. Zbuduj wyraźne sprawdzanie stanu konta i powiadamiaj użytkowników, gdy wymagane jest ponowne uwierzytelnienie.
Zakresy OAuth: o co pytać (i o co nie)
Minimalizacja zakresu to zarówno najlepsza praktyka w zakresie bezpieczeństwa, jak i strategia optymalizacji zgód. Wnioskowanie o większą liczbę zakresów niż jest to potrzebne powoduje wahanie (lub odrzucenie) ze strony użytkowników na ekranie zgody i wywołuje zwiększoną kontrolę podczas przeglądów Google CASA i Microsoft Publisher.
| Zakres | Dostawca | Przypadek użycia | Wrażliwość | Recenzja CASA? |
|---|---|---|---|---|
| gmail.tylko_do_odczytu | Gmail | Przeczytaj wszystkie e-maile i metadane | Wysoki | Tak - Poziom 2 |
| gmail.wyślij | Gmail | Wyślij e-mail jako użytkownik | Wysoki | Tak - Poziom 2 |
| gmail.zmodyfikuj | Gmail | Czytaj, wysyłaj, usuwaj, oznaczaj | Wysoki | Tak - Poziom 2 |
| etykiety gmail | Gmail | Czytaj i zarządzaj etykietami | Niski | Nie |
| Mail.Read | Perspektywy | Przeczytaj całą pocztę | Średni | Weryfikacja Wydawcy |
| Mail.Send | Perspektywy | Wyślij e-mail jako użytkownik | Średni | Weryfikacja Wydawcy |
| Mail.ReadWrite | Perspektywy | Czytaj, wysyłaj, usuwaj, zarządzanie folderami | Wysoki | Weryfikacja Wydawcy |
| dostęp offline | Perspektywy | Uzyskaj tokeny odświeżające | Niski | Nie |
| maile-r | IMAP (Yahoo) | Odczytaj e-mail przez IMAP/XOAUTH2 | Średni | Przegląd deweloperski Yahoo |
Tokeny zostały odświeżone i obrócone dla Ciebie
Przestań pisać kod obsługi cyklu życia tokenów. Połącz skrzynkę pocztową raz, Unipile utrzyma dostęp aktywny we wszystkich dostawcach.
Zgodność: SOC2, RODO, CASA
API poczty e-mail OAuth, która zarządza skrzynkami pocztowymi użytkowników, znajduje się na styku zgodności z przepisami dotyczącymi bezpieczeństwa i prywatności. Oto cztery rozwiązania, o które zapyta większość nabywców korporacyjnych – i co oznacza model tokenów OAuth dla każdego z nich.
Audytorzy SOC2 badają obsługę tokenów w ramach kryteriów dostępności i poufności. Tokeny OAuth muszą być szyfrowane w spoczynku (AES-256 lub KMS), rejestrowane pod kątem dostępu i podlegać formalnej polityce rotacji. Przechowywanie tokenów odświeżania w postaci czystego tekstu jest automatycznym ustaleniem. Korzystanie z hostowanego API OAuth e-mail, takiego jak Unipile (który posiada certyfikat SOC2), przenosi tę odpowiedzialność.
Zgodnie z RODO, Twoja aplikacja jest procesorem danych, gdy uzyskuje dostęp do treści e-maili użytkowników. Potrzebujesz umowy powierzenia przetwarzania danych (DPA) z dostawcą infrastruktury API poczty e-mail OAuth. Odwołalność OAuth bezpośrednio spełnia wymogi Artykułu 17 (prawo do usunięcia) – gdy użytkownik odwoła zgodę, Twój dostęp kończy się natychmiast. Udokumentuj swoją podstawę prawną do dostępu do danych poczty e-mail (zazwyczaj zgodę uzyskaną w procesie OAuth).
Gdy liczba użytkowników Twojej aplikacji korzystającej z interfejsu API poczty e-mail Gmaila w ramach protokołu OAuth przekroczy 100 osób z uprawnieniami do danych wrażliwych, Google zablokuje możliwość dodawania kolejnych użytkowników do czasu uzyskania certyfikatu CASA Tier 2. Wymaga to przeprowadzenia testu penetracyjnego przez laboratorium autoryzowane przez CASA, wypełnienia kwestionariusza dotyczącego bezpieczeństwa oraz przedłożenia Google formalnego raportu z oceny. Czas realizacji: 8–16 tygodni. Koszt: 1 000–25 000 TP4T. Zweryfikowane aplikacje otrzymują odznakę "Zweryfikowane przez Google" na ekranie zgody.
API OAuth do poczty e-mail: Cennik i modele kosztów
Darmowe API dostawców od Google i Microsoft ukrywają znaczące rzeczywiste koszty. Oto realistyczny model kosztowy wdrażania interfejsu API poczty e-mail OAuth na dużą skalę – obejmujący bezpośrednią ścieżkę dostawcy w porównaniu z ujednoliconymi interfejsami API.
Interfejsy API firm Google i Microsoft są technicznie bezpłatne na poziomie wywołań API. Jednak: usługa Google CASA Tier 2 kosztuje od 1 400 do 25 000 TP oraz wymaga co najmniej 3 miesięcy pracy inżynierów. Weryfikacja wydawcy w przypadku Microsoftu wymaga posiadania konta w Partner Network oraz prawnej weryfikacji domeny. Czas potrzebny na opracowanie trzech ścieżek, zarządzanie tokenami i obsługę błędów: 6–10 tygodni. Roczna konserwacja: 2–4 tygodnie rocznie na dostawcę.
API Unipile do obsługi poczty e-mail z uwierzytelnianiem OAuth zawiera pełną zgodność z dostawcami (CASA, Publisher Verification), zarządzanie tokenami i jednolite API poczty e-mail w ramach jednej subskrypcji. Dla zespołów, które wdrażają łączność poczty e-mail jako funkcję (a nie produkt), kalkulacja zwrotu z inwestycji jest prosta: tygodnie zaoszczędzonego czasu inżynierów w porównaniu do miesięcznego kosztu API. Zobacz porównaj dostawców API poczty e-mail Przewodnik po pełnym rozbiciu kosztów.
Najczęstsze pułapki podczas wdrażania OAuth w poczcie e-mail
Oto najczęstsze błędy popełniane przez programistów przy tworzeniu pierwszego adresu e-mail API OAuth – i co zrobić zamiast tego.
Google unieważnia tokeny odświeżania, jeśli użytkownik nie korzystał z Twojej aplikacji przez 6 miesięcy. Twoje wywołanie odświeżania tokenu zwraca nieprawidłowe_poświadczenie. Naprawa: wdrożenie okresowego "kontroli stanu tokenu", która wykonuje lekkie wywołanie Gmail API dla każdego połączonego konta przynajmniej raz na 30 dni, aby zapobiec wygaśnięciu z powodu braku aktywności.
Żądanie gmail.zmodyfikuj kiedy potrzebujesz tylko gmail.tylko_do_odczytu powiększa ekran zgody i powoduje, że użytkownicy porzucają przepływ OAuth. Zwiększa również Twoje wymagania dotyczące poziomu CASA. Zawsze żądaj minimalnego potrzebnego zakresu. Dodatkowe zakresy możesz żądać przyrostowo później.
Limit dla wrażliwego zakresu Gmaila wynoszący 100 użytkowników jest najczęstszą przeszkodą w rozwoju wdrożeń interfejsu API poczty e-mail OAuth. Zaplanuj przegląd CASA przed osiągnięciem 50 użytkowników – przegląd trwa 8–16 tygodni, a wzrost liczby użytkowników zostanie zablokowany do czasu jego zakończenia.
Szczegółowe logowanie żądań, które przechwytuje nagłówki autoryzacji, będzie logować Twoje tokeny dostępu w postaci zwykłego tekstu. Zaimplementuj middleware do czyszczenia logów, który redaguje Nośnik [TOKEN] wzorce przed zapisaniem dzienników do jakiegokolwiek trwałego magazynu.
Niektóre firmowe serwery pocztowe działają w oparciu o niestandardowe konfiguracje IMAP, które nie obsługują OAuth. Twoje API poczty e-mail oparte na OAuth musi mieć płynną ścieżkę awaryjną dla dostawców obsługujących tylko IMAP. Wdróż to w przepływie połączenia konta od pierwszego dnia, w przeciwnym razie wykluczysz znaczną część użytkowników B2B. Zobacz nasz Integracja IMAP Przewodnik po pełnym wzorcu awaryjnym (fallback pattern).
Zbuduj zamiast sklejać dostawców
Uzyskaj działającą integrację poczty e-mail przez OAuth już dziś. Bezpłatny poziom, bez karty kredytowej, pełne zakresy Gmail i Microsoft dostępne.
Często zadawane pytania
Najczęściej zadawane pytania przez deweloperów podczas tworzenia integracji z OAuth dla API poczty e-mail – odpowiedzi precyzyjnie.
https://oauth2.googleapis.com/token, zakresy w gmail.* przestrzeń nazw. Dla programu Outlook (obejmujący Outlook.com, Microsoft 365 i Exchange Online): Platforma tożsamości firmy Microsoft, punkt końcowy tokenu https://login.microsoftonline.com/common/oauth2/v2.0/token, zakresy pod https://graph.microsoft.com/. Dla IMAP: IMAP nie jest dostawcą OAuth. Używa poświadczeń nazwa użytkownika/hasło lub hasła aplikacji. XOAUTH2 istniało jako rozszerzenie SASL dla niewielkiej liczby dostawców, ale w dużej mierze zostało wycofane.grant_type=refresh_token. Dla Google: POST do https://oauth2.googleapis.com/token. Dla firmy Microsoft: POST do https://login.microsoftonline.com/common/oauth2/v2.0/token. Jeśli otrzymasz nieprawidłowe_poświadczenie, token odświeżający wygasł lub został unieważniony - wyświetl użytkownikowi komunikat o konieczności ponownego uwierzytelnienia.gmail.tylko_do_odczytu czytać, gmail.wyślij wysłać, gmail.zmodyfikuj do pełnego odczytu/zapisu/usunięcia. Dla programu Outlook: Mail.Read czytać, Mail.Send wysłać, Mail.ReadWrite dla pełnego dostępu - plus dostęp offline aby uzyskać tokeny odświeżania. Zawsze proś o minimalny zakres uprawnień wymagany przez przypadek użycia. Patrz strona API poczty elektronicznej do rekomendacji zakresu specyficznych dla danego przypadku użycia.etykiety gmail (nie podlega CASA), rozpocznij proces CASA, zanim osiągniesz 50 użytkowników (trwa to 8-16 tygodni), lub skorzystaj z hostowanego API poczty OAuth, takiego jak Unipile, którego infrastruktura przeszła już przegląd CASA – eliminując ten wymóg dla Twojej aplikacji całkowicie./api/v1/hosted/accounts/link. Przechodzisz przez typ (GOOGLE, MICROSOFT lub IMAP) a Unipile generuje hostowany adres URL uwierzytelniania. Użytkownik zatwierdza zgodę OAuth w infrastrukturze Unipile - która przeszła weryfikację Google CASA i weryfikację wydawcy Microsoft. Po otrzymaniu zgody Unipile wysyła webhook z account_id. Całe zarządzanie tokenami i ich odświeżanie jest obsługiwane wewnętrznie.nieprawidłowe_poświadczenie. Twoje OAuthowe API pocztowe musi to przechwycić, oznaczyć połączone konto jako odłączone i powiadomić użytkownika linkiem do ponownego uwierzytelnienia. Z Unipile, webhook z unieważnieniem uruchamia się automatycznie, dzięki czemu Twój system jest powiadamiany w czasie rzeczywistym – bez konieczności odpytywania.
PL 
EN 
FR 
ES 
DE 
IT 
BR 
NL 
TR