LinkedIn
Instagram
Facebook
WhatsApp
Telegram
Kalendarz Google
Kalendarz Outlook
Dołącz do społeczności SlackJak czytać e-maile przez API: Przewodnik dla deweloperów Dostęp do skrzynki odbiorczej
Zakres Ten poradnik obejmuje synchronizuj API do odczytu istniejących skrzynek odbiorczych użytkowników — Gmail API, Microsoft Graph, IMAP oraz zunifikowane warstwy, takie jak Unipile. Różni się to od usług transakcyjnych (SendGrid, Mailgun), które wysyłają pocztę wychodzącą z domen Twojej firmy.
Twórz produkty, które programowo odczytują wiadomości e-mail użytkowników. Z jednego POBIERZ /api/v1/emails W niniejszym przewodniku omówiono wszystkie metody wywoływania webhooków w czasie rzeczywistym wraz z działającym kodem w językach Node.js, Python i cURL.
// Odczytaj e-maile za pomocą jednego ujednoliconego wywołania API
const response = czekać fetch(
'https://api3.unipile.com:PORT/api/v1/emails',
{
nagłówki: {
'Klucz API X': process.env.UNIPILE_API_KEY,
'id_konta': accountId
}
}
);
const { e-maile } = czekać odzew.json();
// Ten sam kształt JSON dla Gmail, Outlook i IMAP
e-maile.dla każdego(email => {
konsola.log(email.temat, email.od_uczestnika);
});
Gmail, Outlook i IMAP
Co to jest interfejs API do odczytu wiadomości e-mail?
API do odczytu poczty e-mail to interfejs HTTP, który pozwala Twojej aplikacji na dostęp do wiadomości e-mail z istniejącej skrzynki pocztowej użytkownika, ich pobieranie i przetwarzanie – bez przechowywania haseł czy tworzenia specyficznych dla dostawcy integracji. Jest to fundament każdego produktu wymagającego wglądu do skrzynki odbiorczej: synchronizacji CRM, asystentów e-mail opartych na sztucznej inteligencji, automatyzacji wsparcia czy archiwizacji zgodności.
A odczytaj API poczty e-mail udostępnia punkty końcowe do uwierzytelniania za pomocą skrzynki pocztowej użytkownika (za pomocą poświadczeń OAuth 2.0 lub IMAP), listowania wiadomości w skrzynce odbiorczej, pobierania pełnych treści wiadomości e-mail z załącznikami oraz subskrybowania zdarzeń dostarczania w czasie rzeczywistym. Działa on na istniejącym koncie Gmail, Outlook lub IMAP użytkownika - nie domenę, nad którą masz kontrolę. Odróżnia to od transakcyjnych API poczty e-mail (SendGrid, Mailgun, Resend), które wysyłają pocztę wychodzącą w imieniu Twojej aplikacji.
Połącz się z istniejącymi skrzynkami pocztowymi użytkowników. Odczytuj, synchronizuj i reaguj na wiadomości e-mail w czasie rzeczywistym. Uwierzytelnianie za pomocą OAuth 2.0 lub IMAP. Użytkownik udziela dostępu do swojej własnej skrzynki pocztowej.
Wysyłaj e-maile wychodzące z domen, które kontrolujesz. Używane do potwierdzeń, powiadomień, resetowania haseł. Brak dostępu do skrzynki odbiorczej.
Dlaczego programistyczne czytanie e-maili ma znaczenie
Możliwość odczytu wiadomości e-mail użytkowników za pośrednictwem API otwiera kategorię produktów, które były po prostu niemożliwe przy użyciu samego SMTP. Oto cztery główne przypadki użycia napędzające wdrożenia w 2026 roku.
Synchronizacja CRM i Sales Engagement
Narzędzia sprzedażowe potrzebują dostępu do każdej wymiany mailowej między przedstawicielem handlowym a potencjalnym klientem – automatycznie, bez ręcznego logowania. API do odczytu poczty elektronicznej pobiera rozmowy bezpośrednio z skrzynki odbiorczej przedstawiciela i synchronizuje je w czasie rzeczywistym z Twoim systemem CRM.
Agenty AI i Asystenci E-mail
Duże modele językowe potrzebują kontekstu. Dostarczając agentowi AI strumień e-maili przychodzących w czasie rzeczywistym, można tworzyć kopilotów, którzy automatycznie tworzą odpowiedzi, podsumowują wątki, wyodrębniają zadania do wykonania i ustalają priorytety rozmów.
Automatyzacja obsługi klienta
Zespoły wsparcia otrzymują tysiące e-maili dziennie. API do odczytu e-maili pozwala Twojej platformie klasyfikować przychodzące zgłoszenia, kierować je do odpowiedniej kolejki i uruchamiać zautomatyzowane odpowiedzi – wszystko to, zanim człowiek otworzy zgłoszenie.
Zgodność, Archiwizacja i eDiscovery
Regulowane branże muszą przechowywać i indeksować każdego e-maila. API do odczytu poczty e-mail zapewnia programistyczny dostęp niezbędny do ciągłego archiwizowania skrzynek odbiorczych, oznaczania naruszeń zasad i dostarczania zapisów e-mail na żądanie do celów przeglądu prawnego.
Natywne interfejsy API do odczytu wiadomości e-mail: Gmail, Outlook i IMAP
Każdy główny dostawca poczty e-mail udostępnia własne API odczytu z różnymi punktami końcowymi, modelami uwierzytelniania i możliwościami. Oto jak wyglądają one w praktyce.
Gmail API
OAuth 2.0API Gmail jest interfejsem API REST zbudowanym na infrastrukturze Google. Używa lista wiadomości użytkowników aby stronicować skrzynkę pocztową i użytkownicy.wiadomości.pobierz aby pobrać pełną wiadomość. Obsługuje powiadomienia push za pośrednictwem Google Pub/Sub, co umożliwia monitorowanie skrzynki odbiorczej w czasie rzeczywistym bez odpytywania. Limit: 250 jednostek limitu na użytkownika na sekundę. Uwaga: Gmail wymaga protokołu OAuth 2.0 — klucze API nie działają w przypadku dostępu do skrzynki pocztowej. Zobacz Dlaczego Gmail odrzuca klucze API.
# Wyświetl wiadomości w skrzynce odbiorczej (API Gmaila)
zwijać się -X POBIERZ \
"https://gmail.googleapis.com/gmail/v1/users/me/messages?labelIds=INBOX&maxResults=20" \
-H "Autoryzacja: Bearer ACCESS_TOKEN"
# Pobierz pojedynczy e-mail wraz z pełną treścią
zwijać się -X POBIERZ \
"Tutaj nie ma tekstu do przetłumaczenia. Jest to adres URL." \
-H "Autoryzacja: Bearer ACCESS_TOKEN"
Microsoft Graph (Outlook i Microsoft 365)
OAuth 2.0Microsoft Graph to ujednolicone API dla wszystkich usług Microsoft 365, w tym osobistych kont Outlook, Exchange Online i skrzynek pocztowych firmowych Microsoft 365. /ja/wiadomości endpoint zwraca wiadomości z pełną treścią w jednym żądaniu. Stronicowanie używa $pomiń oraz $góra Parametry OData. Zobacz pełny Przewodnik po integracji poczty e-mail w Microsoft Graph szczegóły.
# Wyświetlanie wiadomości w skrzynce odbiorczej (Microsoft Graph)
zwijać się -X POBIERZ \
"https://graph.microsoft.com/v1.0/me/messages?\$top=20&\$filter=parentFolderId eq 'inbox'' \
-H "Autoryzacja: Bearer ACCESS_TOKEN" \
-H "Typ-Zawartości: application/json"
# Pobierz pojedynczą wiadomość wraz z treścią
zwijać się -X POBIERZ \
"https://graph.microsoft.com/v1.0/me/messages/MESSAGE_ID?\$select=subject,body,from,receivedDateTime" \
-H "Autoryzacja: Bearer ACCESS_TOKEN"$wybierz oraz Akceptuj nagłówki.
IMAP
Protokół uniwersalnyIMAP (Internet Message Access Protocol) to uniwersalny protokół poczty e-mail obsługiwany przez praktycznie każdy serwer pocztowy. Nie jest to REST API, ale stanowe połączenie TCP przez port 993 (TLS). Wydajesz polecenia typu POBIERZ, SZUKAJoraz BEZCZYNNOŚĆ przez połączenie. Aby dowiedzieć się więcej, zobacz nasze Przewodnik po integracji API IMAP.
import imaplib, e-mail
# – Połącz się i uwierzytelnij
poczta = imaplib.IMAP4_SSL('imap.przykład.com')
poczta.zaloguj('user@example.com', 'app_password')
poczta.wybierz('SKRZYNKA')
# Szukaj ukrytych wiadomości
status, identyfikatory_wiadomości = poczta.wyszukiwanie(Żaden, 'NIEWIDZIANY')
dla identyfikator_wiadomości w message_ids[0].podzielić():
_, dane = poczta.fetch(id_wiadomości, '(RFC822)')
wiadomość = e-mail.wiadomość_z_bajtów(dane[0][1])
print(komunikat['temat'], komunikat['z'])BEZCZYNNOŚĆ komenda, która utrzymuje połączenie otwarte i czeka na powiadomienia od serwera. Nie skaluje się łatwo powyżej kilkuset jednoczesnych kont.Yahoo Mail, ProtonMail, Zoho i inni dostawcy obsługują IMAP jako uniwersalne rozwiązanie zapasowe, więc są objęci powyższym podejściem IMAP. Niektórzy (jak Yahoo) udostępniają również ograniczone, własne interfejsy API, ale żaden nie dorównuje możliwościom interfejsu API Gmaila ani Microsoft Graph. W przypadku większości produktów obejmujących wielu dostawców, IMAP jest uniwersalnym rozwiązaniem zapasowym dla każdej skrzynki pocztowej, która nie jest obsługiwana przez Gmaila ani Outlook OAuth. A ujednolicone API pocztowe automatycznie przeprowadza tę negocjację.
Ukryta złożoność czytania e-maili na dużą skalę
Stworzenie integracji API do odczytu poczty e-mail dla jednego dostawcy na potrzeby demonstracji zajmuje popołudnie. Stworzenie takiej, która będzie niezawodnie działać u wszystkich dostawców w skali produkcyjnej, to zupełnie inne wyzwanie. Oto, co faktycznie obejmuje inżynieria.
Przepływ OAuth na dostawcę
Każdy dostawca ma własną implementację OAuth 2.0, wymagania dotyczące ekranu zgody, zakresy i cykl życia tokenu. Obsługa Gmaila i Outlooka oznacza utrzymanie dwóch oddzielnych aplikacji OAuth, dwóch konsol deweloperskich, dwóch strategii odświeżania tokenów i dwóch zestawów wymogów zgodności (Google CASA Tier 2, Microsoft Publisher Verification).
Różnice w paginacji
Każdy dostawca stosuje inne metody paginacji. Gmail używa nieprzezroczystych tokenów stron. Microsoft Graph używa OData. $pomiń oraz następny link Kursor. IMAP używa numerycznych zakresów UID. Wdrożenie spójnej abstrakcji stronicowania we wszystkich trzech wymaga nietrywialnego kodu adaptera.
Parsowanie MIME
E-maile przychodzą jako surowe dokumenty MIME z zagnieżdżonymi granicami wieloczęściowymi, kodowaniem base64 lub quoted-printable, wieloma zestawami znaków i załącznikami w tekście. Gmail zwraca części zakodowane w base64url. IMAP zwraca surowe RFC 822. Żaden z nich nie dostarczy czystego, zwykłego tekstu bez parsowania całego drzewa MIME.
Limity żądań i wycofywanie
Gmail wymusza 250 jednostek limitu na użytkownika na sekundę (wystawienie kosztuje 5 jednostek, pobranie 5 jednostek). Microsoft Graph stosuje ograniczenia 10 000 żądań na 10 minut na aplikację na dzierżawcę. Oba zwracają błędy 429, które wymagają wykładniczego wycofywania z dodaniem losowości. Przy 1000 połączonych kontach zarządzanie limitami żądań staje się pełnoprawnym problemem inżynieryjnym.
Na żywo: Webhooki vs Polling vs IDLE
Otrzymywanie powiadomień o nowych wiadomościach e-mail wymaga zupełnie innych mechanizmów w zależności od dostawcy. Gmail używa subskrypcji push Google Pub/Sub, które muszą być odnawiane co 7 dni. Microsoft Graph używa subskrypcji powiadomień o zmianach z maksymalnym okresem ważności 4230 minut. IMAP używa polecenia IDLE, które utrzymuje stałe połączenie TCP na konto.
Niespójności wątków u różnych dostawców
Gmail domyślnie grupuje wiadomości w wątki. Microsoft Graph posiada pole conversationId, ale wątki działają inaczej niż w Gmailu. IMAP nie posiada natywnego wątkowania – należy ręcznie rekonstruować wątki, dopasowując nagłówki References i In-Reply-To. Budowanie ujednoliconego widoku wątków obejmującego różne dostawców wymaga znacznej logiki normalizacyjnej.
Architektura API do odczytu wiadomości e-mail: porównanie 3 podejść
Nie ma jednej "poprawnej" architektury do odczytu wiadomości e-mail. Właściwe podejście zależy od tego, ilu dostawców musisz obsługiwać, od posiadanych zasobów inżynierskich i wymagań skalowalności. Oto szczere porównanie.
| Podejście | Zalety | Kons | Kiedy używać |
|---|---|---|---|
| API bezpośrednich dostawców Gmail API, Microsoft Graph |
Poziom bezpłatny, pełny dostęp do funkcji, brak opóźnień pośrednich | Konfiguracja OAuth na dostawcę, parsowanie MIME, oddzielne zarządzanie limitami żądań, brak normalizacji między dostawcami | Tylko jeden dostawca |
| Samodzielny IMAP imaplib, node-imap |
Uniwersalny protokół, działa z każdą skrzynką pocztową, nie wymaga aplikacji OAuth | Połączenia TCP ze stanem, brak powiadomień push (polling lub IDLE), zarządzanie pulą połączeń, wolne w skali | Tylko starsze wersje / lokalnie |
| Zunifikowane API do odczytu poczty e-mail Unipile |
Jednolity endpoint dla wszystkich dostawców, znormalizowana odpowiedź JSON, zarządzany OAuth, ujednolicone webhooki, wbudowana logika ponawiania prób | Dodatkowy koszt wywołania API na połączone konto, zewnętrzne zależności | Produkty wielodostawcowe |
Jeśli każdy użytkownik Twojego produktu korzysta z Gmaila, zbuduj integrację bezpośrednio z interfejsem API Gmaila. Uzyskasz pełną funkcjonalność, brak dodatkowych kosztów oraz dostęp do specyficznych funkcji Gmaila, takich jak etykiety, wątki i powiadomienia z Pub/Sub.
Serwery poczty lokalnej, rozwiązania firmowe Exchange bez dostępu do interfejsu Graph API, lub dowolny scenariusz, w którym OAuth nie jest dostępny. Używaj IMAP jako metody awaryjnej, a nie podstawowej strategii dla nowych produktów.
Kiedy użytkownicy mają skrzynki pocztowe Gmail, Outlook i IMAP, a potrzebujesz jednolitego interfejsu API do odczytu poczty e-mail, zunifikowana warstwa, taka jak Unipile, całkowicie eliminuje problem integracji z wieloma dostawcami.
Czytanie e-maili za pomocą zunifikowanego API do odczytu e-maili Unipile
Unipile abstrakcjonizuje Gmail API, Microsoft Graph i IMAP za pomocą jednego API do odczytu poczty e-mail. Jeden przepływ OAuth, jeden punkt końcowy, jedna znormalizowana forma JSON - niezależnie od tego, u którego dostawcy znajduje się skrzynka pocztowa użytkownika. Oto jak odczytać pierwszą skrzynkę pocztową w mniej niż 5 minut.
Wygeneruj hostowany adres URL uwierzytelniania z pulpitu nawigacyjnego Unipile. Wyślij ten link do swojego użytkownika – on wykona przepływ zgody OAuth dla swojego dostawcy (dane logowania do Gmail, Outlook lub IMAP) na stronie hostowanej przez Unipile. Żadnej konfiguracji aplikacji OAuth, żadnego konfigurowania identyfikatora URI przekierowania po Twojej stronie. Zobacz Przewodnik po zunifikowanym API e-mail dla pełnego przepływu uwierzytelniania.
# Wygeneruj link do uwierzytelniania hostowanego dla swojego użytkownika
zwijać się -X POST \
"https://api3.unipile.com:PORT/api/v1/hosted/accounts/link" \
-H "X-API-KEY: TWÓJ_KLUCZ_API" \
-H "Typ-Zawartości: application/json" \
-d '{"type":"EMAIL","name":"user@example.com","success_redirect_url":"https://yourapp.com/connected"}'
Odpowiedź #: { "url": "https://auth.unipile.com/..." }
# Wyślij ten adres URL do użytkownika – użytkownik przeprowadzi proces OAuth u swojego dostawcyGdy użytkownik połączy swoje konto, wywołaj punkt końcowy poczty e-mail z jego account_id. Odpowiedź jest identyczna niezależnie od tego, czy podstawowa skrzynka pocztowa to Gmail, Outlook czy IMAP.
# Wyświetl listę wiadomości e-mail w skrzynce odbiorczej (działa w Gmailu, Outlooku i IMAP)
zwijać się -X POBIERZ \
"https://api3.unipile.com:PORT/api/v1/emails?account_id=ACCOUNT_ID&limit=50" \
-H "X-API-KEY: TWÓJ_KLUCZ_API"
# Filtruj według folderu
zwijać się "...?account_id=ACCOUNT_ID&folder=SKRZYNKA&limit=50" -H "X-API-KEY: TWÓJ_KLUCZ_API"
# – filtruj tylko nieprzeczytane
zwijać się "...?account_id=ACCOUNT_ID&unread=true" -H "X-API-KEY: TWÓJ_KLUCZ_API"Pobierz pełny e-mail według identyfikatora. Unipile zwraca zdekodowany, znormalizowany obiekt z treścią w postaci zwykłego tekstu, treścią HTML i metadanymi załączników - nie jest wymagane żadne parsowanie MIME po Twojej stronie.
# Pobierz pojedynczy e-mail wraz z pełną treścią i załącznikami
zwijać się -X POBIERZ \
"https://api3.unipile.com:PORT/api/v1/emails/EMAIL_ID" \
-H "X-API-KEY: TWÓJ_KLUCZ_API"
Pola odpowiedzi # (zawsze znormalizowane):
# { "id", "temat", "data", "od_uczestnika", "do_uczestników",
# "body", "body_plain", "attachments": [{ "id", "filename", "size" }] }Zarejestruj punkt końcowy webhooka na swoim pulpicie nawigacyjnym Unipile. Unipile abstrahuje Gmail Pub/Sub, powiadomienia o zmianach Microsoft Graph i IMAP IDLE w jedno email.received zdarzenie. Brak odnowienia subskrypcji, brak puli połączeń IDLE do zarządzania.
// Unipile wywołuje Twój punkt końcowy, gdy przychodzi nowy e-mail
// To samo zdarzenie dla użytkowników Gmail, Outlook i IMAP
aplikacja.stanowisko('/webhooks/email', (req, res) => {
const { zdarzenie, identyfikator_konta, identyfikator_e_mail } = req.body;
jeśli (zdarzenie === 'email.received') {
// Pobierz pełne szczegóły wiadomości e-mail
przetwarzajNowyEmail(id_konta, id_email);
}
rez.status(200);
});Pełny przewodnik po API poczty e-mail szczegółowo omawia uwierzytelnianie, wszystkie punkty końcowe, stronicowanie, pobieranie załączników, bezpieczeństwo i zgodność.
Czytanie e-maili: Przykłady kodu według języka
Gotowe do produkcji fragmenty kodu do odczytu wiadomości e-mail za pomocą ujednoliconego interfejsu API do odczytu wiadomości e-mail Unipile. Wszystkie przykłady odczytują z kont Gmail, Outlook i IMAP przy użyciu tego samego kodu.
import fetch z 'węzeł-pobieranie';
const BAZA = 'https://api3.unipile.com:PORT/api/v1';
const Klucz API = process.env.UNIPILE_API_KEY!;
interfejs E-mail {
id: łańcuch;
temat: łańcuch;
data: łańcuch;
od_uczestnika: { wyświetlana_nazwa: łańcuch; identyfikator: łańcuch };
body: łańcuch;
Treść: łańcuch;
załączniki: { id: łańcuch; nazwa pliku: łańcuch; rozmiar: liczba }[];
}
// Lista e-maili w skrzynce odbiorczej - działa dla Gmaila, Outlooka i IMAP
async function listaEmaili(numerKonta: łańcuch, limit = 50) {
const res = czekać fetch(
`${BASE}/emails?account_id=${accountId}&limit;=${limit}&folder;=INBOX`,
{ nagłówki: { 'Klucz API X': KLUCZ_API } }
);
const dane = czekać rez.json();
return elementy danych jako E-mail[];
}
// Pobierz pojedynczego e-maila z pełnym tekstem + załącznikami
async function PobierzEmail(idEメール: łańcuch) {
const res = czekać fetch(`${BASE}/emails/${emailId}`,
{ nagłówki: { 'Klucz API X': KLUCZ_API } }
);
return czekać rez.json() jako E-mail;
}
// Użycie
const e-maile = czekać listaEmaili('acc_01abc...');
e-maile.dla każdego(e => konsola.log(e.temat, e.od_uczestnika.identyfikator));import osi
import żądania
BAZA = "https://api3.unipile.com:PORT/api/v1"
NAGŁÓWKI = {"X-API-KEY": os.environ["UNIPILE_API_KEY"]}
def list_emails(identyfikator_konta: str, limit: int = 50) -> lista:
"Wyświetl e-maile w skrzynce odbiorczej — działa dla Gmaila, Outlooka i IMAP."
odpowiadaj = żądania.uzyskać(
f"{BAZA}/maile",
headers=HEADERS,
parametry={
"account_id": identyfikator_konta,
"limit"limit,
"folder": "SKRZYNKA ODBIORCZA",
},
)
lub.podnieś_status()
return lub.json()["przedmioty"]
def pobierz_email(email_id: str) -> dict:
"Pobierz pojedynczy e-mail wraz z treścią i załącznikami."
odpowiadaj = żądania.uzyskać(f"{BAZA}/emails/{email_id}", nagłówki=NAGŁÓWKI)
lub.podnieś_status()
return lub.json()
# Użycie
e-maile = list_emails("acc_01abc...")
dla e-mail w e-maile:
print(email"temat"], e-mail["od_uczestnika"]["identyfikator"])
# Pobierz treść pełną pierwszego e-maila
pełny = pobierz_emailE-maile0]["id"])
print(pełny"ciało_zwykłe"])opakowanie główny
import (
"kodowanie/json"
"fmt"
"net/http"
"os"
)
typ E-mail struktura {
ID łańcuch `json:"id"`
Temat łańcuch `json:"temat"`
Ciało łańcuch `json:"body_plain"`
}
typ ListaOdpowiedzi struktura {
Przedmioty []E-mail `json:"przedmioty"`
}
funkcja listaEmaili(accountID string) ([]E-mail, błąd) {
url := "https://api3.unipile.com:PORT/api/v1/emails?account_id=" + ID_konta
żądanie, _ := http.NoweŻądanie("POBIERZ", adres url, nie)
Nagłówek req.Zestaw("X-API-KEY", os.Getenv("UNIPILE_API_KEY"))
resp, err := http.DefaultClient.Dowymagaj
jeśli błąd != nie { return nie, błąd }
przełożyć resp.Body.Zamknij()
zmienna wynik ListaOdpowiedzi
json.Dekoder(resp.Ciało).Dekoduj(&wynik)
return result.Elementy, nie
}
funkcja główny() {
e-maile, _ := listaEmaili("acc_01abc...")
dla _, e := zakres e-maile {
fmt.Wydrukuj(Temat)
}
}Czytanie e-maili w czasie rzeczywistym: Webhooki a polling
Świadomość nadejścia nowego e-maila jest równie ważna jak możliwość jego odczytania. Dostępne są trzy mechanizmy, każdy z bardzo różnymi charakterystykami działania w szerokiej skali.
Sondaż
Twoja aplikacja wywołuje punkt końcowy listy e-maili w określonych odstępach czasu (co 30 sekund, co 5 minut). Proste do zaimplementowania, ale zużywa limit, wprowadza opóźnienia i nie skaluje się poza garstką kont.
Natywne Webhooky Dostawcy
Powiadomienia Gmail Pub/Sub i Microsoft Graph wypychają zdarzenia na twój serwer natychmiast. Szybkie i wydajne pod względem limitów – ale każde wymaga oddzielnej konfiguracji, oddzielnej logiki odnawiania i innych schematów zdarzeń.
Unipile Zunifikowane Webhooki
Unipile abstrahuje wszystkie mechanizmy push dostawców za jednym email.received zdarzenie. Jedno z punktów końcowych odbiera powiadomienia z kont Gmail, Outlook i IMAP, a automatyczne odnawianie subskrypcji jest obsługiwane wewnętrznie.
Pod maską, Unipile zarządza subskrypcjami Gmail Pub/Sub, subskrypcjami powiadomień o zmianach Microsoft Graph oraz połączeniami IMAP IDLE – dla każdego połączonego konta, automatycznie odnawianymi. Twoja aplikacja rejestruje jeden adres URL webhook i otrzymuje jedno znormalizowane zdarzenie, niezależnie od dostawcy.
Bezpieczeństwo i zgodność podczas czytania e-maili użytkowników
Dostęp do e-maili użytkowników wiąże się ze znacznymi obowiązkami w zakresie bezpieczeństwa i prawa. Oto cztery obszary, które musisz uwzględnić przed wdrożeniem integracji z interfejsem API odczytu poczty e-mail do produkcji.
Minimalizacja zakresu OAuth
Zawsze żądaj minimalnego wymaganego zakresu OAuth. Do odczytu wiadomości e-mail użyj zakresy tylko do odczytu - Nigdy nie proś o uprawnienia do wysyłania lub tworzenia, jeśli Twoja aplikacja potrzebuje tylko dostępu do skrzynki odbiorczej. Zakres tylko do odczytu dla Gmaila to gmail.tylko_do_odczytu. Odpowiednikiem Microsoft Graph jest Mail.Read. Żądanie szerokich zakresów inicjuje bardziej rygorystyczne procesy przeglądu w Google i Microsoft oraz zmniejsza zaufanie użytkowników na ekranie zgody.
Najlepsze praktyki przechowywania tokenów
Tokeny dostępu OAuth i tokeny odświeżania to poświadczenia. Przechowuj je zaszyfrowane podczas przechowywania Używaj AES-256 lub równoważnego, nigdy w postaci zwykłego tekstu w swojej bazie danych. Rotuj klucze szyfrowania cyklicznie. Nigdy nie loguj tokenów w logach aplikacji. Wdróż odwoływanie tokenów, gdy użytkownik rozłączy swoje konto – wywołaj punkt końcowy odwoływania dostawcy, nie usuwaj po prostu rekordu bazy danych.
RODO i rezydencja danych
Treść wiadomości e-mail często zawiera dane osobowe objęte RODO. Musisz udokumentować w swojej polityce prywatności dokładnie, jakie dane dotyczące poczty e-mail gromadzisz, przechowujesz, przetwarzasz i przez jaki czas. Wdróż proces usuwania danych, który usuwa treść wiadomości e-mail na żądanie użytkownika dotyczące usunięcia. Jeśli przechowujesz treść wiadomości e-mail we własnej infrastrukturze, rozważ wymogi dotyczące rezydencji danych dla klientów z UE.
Weryfikacja Google CASA i Microsoft Publisher
Aplikacje proszące o wrażliwe zakresy Gmail (w tym gmail.tylko_do_odczytu) musi ukończyć Google CASA Poziom 2 ocena bezpieczeństwa przed dopuszczeniem do testów powyżej limitu 100 użytkowników. Microsoft wymaga weryfikacji wydawcy dla aplikacji żądających określonych zakresów Graph. Oba procesy trwają tygodnie — zaplanuj je z uwzględnieniem daty premiery. Korzystanie z Unipile dziedziczy te certyfikaty z warstwy platformy.
Unipile obsługuje certyfikację Gmail CASA Tier 2, Microsoft Publisher Verification, audyt SOC 2 Type II i umowy o przetwarzaniu danych RODO na poziomie platformy. Produkty zbudowane na bazie Unipile dziedziczą te certyfikaty, zamiast przechodzić je niezależnie.
Cennik API do odczytu wiadomości e-mail: Poziomy darmowe i modele kosztów
Darmowe poziomy API natywnych dostawców są hojne przy niskim obciążeniu, ale ukryte koszty pojawiają się, gdy trzeba obsługiwać wielu dostawców, zarządzać odświeżaniem tokenów na dużą skalę lub osiągać limity żądań. Oto szczere podsumowanie.
| Dostawca | Darmowy poziom | Model kosztów | Limit żądanych danych | Ukryte koszty |
|---|---|---|---|---|
| Gmail API | Bezpłatnie z limitami | Liczba jednostek w ramach limitu na jedno zgłoszenie. Brak rozliczeń na konto | 250 jednostek/sek/użytkownika, 1 miliard jednostek/dzień | Recenzja CASA Tier 2, parsowanie MIME, logika odnowienia Pub/Sub |
| Microsoft Graph | Darmowe z ograniczoną prędkością | Dołączony do dzierżawy Microsoft 365. Brak opłaty za połączenie | 10 000 żądań na 10 minut na aplikację na dzierżawcę | Proces weryfikacji wydawcy, odnowienie subskrypcji, aplikacje OAuth na najemcę |
| IMAP (hostowany lokalnie) | Wolny protokół | Brak kosztów API. Koszty infrastruktury dla pul połączeń | Dostawca-specyficzne, ~10-20 połączeń/konto | Infrastruktura serwerowa, zarządzanie połączeniami IDLE, brak obsługi push |
| Unipile | 7-dniowy bezpłatny okres próbny | Za powiązane konto miesięcznie. Zobacz bezpłatna warstwa API poczty e-mail | Zarządzane wewnętrznie, wbudowana logika ponawiania prób | Koszt wywołania API na konto – skompensowany przez wyeliminowanie inżynierii OAuth/MIME |
Zacząć od darmowego API do wysyłania e-maili? Zarówno Gmail API, jak i Microsoft Graph oferują bezpłatny dostęp w ramach limitów kwotowych. Unipile oferuje 7-dniowy bezpłatny okres próbny bez konieczności podawania karty kredytowej, obejmujący konta Gmail, Outlook i IMAP.
Rozpocznij bezpłatny okres próbnyTypowe pułapki przy budowaniu integracji czytania e-maili
Oto błędy, które konsekwentnie powodują incydenty produkcyjne w zespołach wdrażających swoją pierwszą integrację z API do odczytu wiadomości e-mail. Poznaj je, zanim je napotkasz.
Limit Gmaila wynoszący 250 jednostek kwotowych na sekundę na użytkownika brzmi hojnie, dopóki nie masz 500 kont i nie musisz przeprowadzić początkowej synchronizacji skrzynki pocztowej. Wyświetlenie 500 wiadomości kosztuje 2500 jednostek; pobranie każdej pełnej wiadomości kosztuje kolejne 2500. Początkowe synchronizacje dużych skrzynek pocztowych mogą wyczerpać dzienne kwoty w ciągu kilku godzin.
Tokeny odświeżania OAuth wygasają w sposób niezauważalny - Google unieważnia je po 6 miesiącach nieaktywności, po zmianie hasła lub gdy użytkownik cofnie dostęp w ustawieniach swojego Konta Google. Jeśli logika odświeżania tokenów nie wykryje błędu 401 i nie wyświetli go użytkownikowi, aplikacja po prostu przestanie odczytywać e-maile bez widocznego błędu.
ostatnia_synchronizacja znacznik czasu oraz powiadomienie, gdy przekroczy on ustawiony interwał synchronizacji.Etykiety Gmail i foldery IMAP nie są koncepcjami równoważnymi. Gmail INBOX Etykieta nie obejmuje wiadomości, które zostały zarchiwizowane (usunięte ze skrzynki odbiorczej, ale nie skasowane). Folder skrzynki odbiorczej w usłudze Microsoft Graph nie uwzględnia skrzynki odbiorczej z priorytetami w porównaniu z innymi podziałami okien, chyba że wyszukuje się obie te pozycje. Użytkownicy aplikacji Teams często stwierdzają, że brakuje im 20–40% wiadomości z powodu błędnych założeń dotyczących folderów.
WSZYSTKO wiadomości (nie tylko SKRZYNKA ODBIORCZA) i filtrowanie według daty po twojej stronie.Treść wiadomości e-mail dociera w szerokim zakresie kodowań znaków: UTF-8, ISO-8859-1, Windows-1252, Shift-JIS. Gmail zwraca części zakodowane w base64url. IMAP zwraca części zakodowane w quoted-printable. Dekodowanie jednego kodowania jako innego powoduje uszkodzenie tekstu wiadomości, który jest niewidoczny w Twoim lokalnym środowisku testowym (które prawdopodobnie wysyła tylko e-maile w kodowaniu ASCII).
Content-Transfer-Encoding i przekoduj do UTF-8. Testuj szczególnie z treściami e-maili zawierających język japoński, arabski i emoji.Zbudowanie jednolitego widoku wątków obejmującego konta Gmail, Outlook i IMAP wymaga normalizacji trzech zupełnie różnych modeli wątków. Gmail posiada natywne identyfikatory wątków. Outlook ma identyfikatory konwersacji, które działają inaczej. IMAP nie ma natywnych wątków – wątki odtwarza się na podstawie Identyfikator wiadomości, Bibliografiaoraz Odpowiedź-Do nagłówki, które nie zawsze są obecne lub poprawne.
Przeczytaj Email API - Często zadawane pytania
Najczęściej zadawane pytania przez programistów tworzących swoją pierwszą integrację z API do odczytu wiadomości e-mail.
gmail.tylko_do_odczytu zakres, uzyskaj token dostępu za pośrednictwem zgody OAuth, a następnie wywołaj POBIERZ /gmail/v1/users/me/messages do wyświetlania wiadomości i GET /users/me/messages/{id}?format=full do pobrania poszczególnych wiadomości e-mail. Wiadomości są zwracane jako części MIME zakodowane w base64url, które należy zdekodować.POBIERZ /api/v1/emails) zwracający znormalizowane dane JSON dla kont Gmail, Outlook i IMAP. Użytkowników uwierzytelniasz jednokrotnie za pomocą hostowanego linku OAuth, a Unipile zajmuje się specyficznymi dla dostawcy przepływami OAuth, parsowaniem MIME i abstrakcją webhooków w czasie rzeczywistym za jednym spójnym interfejsem. Zobacz nasz Przewodnik po interfejsie API poczty e-mail do pełnego odniesienia./wiadomości/{id}/załączniki. IMAP wymaga parsowania drzewa MIME w celu identyfikacji części załączników. W przypadku Unipile metadane załączników (nazwa pliku, rozmiar, typ MIME) są zawarte w odpowiedzi e-mail, a zawartość załączników jest dostępna za pośrednictwem dedykowanego punktu końcowego – nie jest wymagane parsowanie MIME.email.received zdarzenie webhook aktywowane dla kont Gmail, Outlook i IMAP z automatycznym zarządzaniem subskrypcjami obsługiwanym wewnętrznie.Ponów-Po Nagłówek. Wprowadź wykładnicze wycofywanie z losowością (jitter) dla niezawodności produkcyjnej. Limity IMAP są specyficzne dla dostawcy, zazwyczaj 10-20 jednoczesnych połączeń na konto.