LinkedIn
Instagram
WhatsApp
Telegram
Kalendarz Google
Dołącz do społeczności SlackE-mail Interfejs API synchronizacji: Jak synchronizacja poczty e-mail działa w produktach SaaS
Zbuduj funkcje SaaS, które synchronizują skrzynki odbiorcze użytkowników w czasie rzeczywistym. Połącz Gmail, Outlook i IMAP przez jedno API do synchronizacji poczty e-mail, z webhookami, przepływami OAuth i pełnym dostępem do folderów.
const UnipileClient = require('@unipile/node-sdk');
const klient = nowy UnipileClient({
dsn: process.env.UNIPILE_DSN,
token: process.env.UNIPILE_TOKEN
});
// Pobierz zsynchronizowane wiadomości e-mail z połączonego konta
const e-maile = czekać client.email.listaEmaili({
account_id: 'acc_gmail_xyz',
folder: 'SKRZYNKA',
limit: 50
});
// Czas rzeczywisty: zarejestruj webhook
czekać client.webhook.create({
adres url 'https://yourapp.com/webhooks/email',
wydarzenia: ['email.nowy', 'email.read']
});
Czym jest interfejs API synchronizacji poczty e-mail?
An synchronizacja poczty API programistyczny interfejs, który pozwala aplikacji na ciągłe lustrzane odbicie skrzynki pocztowej użytkownika – odczytywanie nowych wiadomości, śledzenie zmian statusu (odczytane/nieodczytane, przeniesione, usunięte) oraz odzwierciedlanie struktury folderów – bez ręcznego eksportowania danych przez użytkownika. W przeciwieństwie do interfejsu API służącego wyłącznie do wysyłania, interfejs synchronizacja poczty e-mail API utrzymuje na żywo, dwukierunkową replikę skrzynki odbiorczej w Twoim produkcie.
Na poziomie protokołu każdy dostawca udostępnia własny prymityw synchronizacji: Gmail używa historia.lista with a Identyfikator Historii kursor, Microsoft Graph używa zapytań przyrostkowych (delta queries) na /wiadomości/delta punkt końcowy i standardowe serwery IMAP obsługują BEZCZYNNOŚĆ polecenie powiadomień typu push. A ujednolicony interfejs API synchronizacji poczty e-mail tak jak Unipile abstrahuje te trzy protokoły za pomocą jednego punktu końcowego, dzięki czemu twój zespół pisze logikę synchronizacji raz i wdraża ją dla wszystkich dostawców.
Jeśli budujesz CRM, narzędzie do angażowania sprzedaży, asystenta poczty e-mail AI lub dowolne oprogramowanie SaaS, które potrzebuje danych z skrzynki odbiorczej na żywo, API do synchronizacji poczty e-mail jest fundamentem. Do wysyłania e-maili transakcyjnych (resetowanie haseł, paragony) jest to inna kategoria — zobacz nasz pełny przewodnik po API email dla naszej dedykowanej Porównanie synchronizacji i transakcji.
Synchronizacja poczty e-mail vs wysyłanie poczty e-mail: Dlaczego rozróżnienie ma znaczenie
Deweloperzy często mylą API synchronizacji poczty e-mail z API poczty transakcyjnej. Służą one przeciwstawnym celom. Wybór niewłaściwej kategorii może opóźnić architekturę o kilka tygodni.
Odczytuje i kopiuje istniejącą skrzynkę pocztową użytkownika do Twojej aplikacji. Wymaga od użytkownika autoryzacji dostępu do jego konta (OAuth lub dane logowania IMAP). Twoja aplikacja staje się wtórnym czytnikiem jego skrzynki odbiorczej.
Używane przez: systemy CRM, narzędzia do angażowania sprzedaży, asystentów e-mailowych AI, systemy helpdesk, archiwizację poczty e-mail, analitykę skrzynki odbiorczej.
Wysyłaj wiadomości e-mail generowane przez system z własnej domeny. Nie jest wymagana autoryzacja użytkownika. Uwierzytelniasz się jako nadawca (klucz API), a nie jako użytkownik. Przykłady: SendGrid, Mailgun, Resend, Amazon SES.
Unipile NIE należy do tej kategorii. Unipile to strona synchronizacji – odczytywanie i lustrzane odbicie skrzynek odbiorczych użytkowników za pomocą OAuth.
Kto potrzebuje API do synchronizacji poczty e-mail?
Każdy produkt SaaS, który musi wyświetlać, analizować lub działać na podstawie przychodzącej poczty e-mail użytkownika, opiera się na interfejsie API synchronizacji poczty e-mail. Oto pięć najczęstszych przypadków użycia, które obserwujemy w produkcji.
Automatyczne logowanie każdej otrzymanej i wysłanej wiadomości e-mail do odpowiedniego rekordu kontaktu. Przedstawiciele handlowi przestają kopiować i wklejać wiadomości e-mail; CRM staje się systemem zapisu w czasie rzeczywistym. Nie jest wymagane ręczne przekierowywanie BCC.
Przewodnik po API poczty elektronicznejŚledź wskaźniki odpowiedzi, wykrywaj automatyczne odpowiedzi typu "poza biurem" i uruchamiaj sekwencje działań następczych na podstawie zdarzeń w skrzynce odbiorczej. API synchronizacji poczty e-mail zapewnia realne odzwierciedlenie tego, co dzieje się w skrzynce odbiorczej potencjalnego klienta.
Wyślij e-mail programowoZasil agenta LLM strumieniem poczty e-mail na żywo, który tworzy szkice odpowiedzi, kategoryzuje przychodzące wiadomości, wyodrębnia elementy do zrobienia lub przekierowuje zgłoszenia. Agent potrzebuje ciągłego strumienia synchronizacji, a nie jednorazowego eksportu. Niezbędne jest API synchronizacji poczty e-mail w czasie rzeczywistym.
czytać maile programowoAutomatycznie konwertuj e-maile klientów na zgłoszenia serwisowe, uwzględniając cały kontekst wątku i załączniki. Synchronizuj status zgłoszenia z powrotem po odpowiedzi agenta, aby skrzynka odbiorcza klienta odzwierciedlała wątek rozwiązanego problemu.
Porównaj dostawców interfejsu API poczty e-mailPrzechwytuj wszystkie przychodzące i wychodzące e-maile w celu zapewnienia zgodności z przepisami, postępowań prawnych lub analiz. API synchronizacji poczty e-mail pozwala na zbudowanie archiwum wszystkich firmowych komunikatów, które można przeszukiwać, dzięki czemu można uniknąć bezpośredniego dostępu do serwera poczty.
Darmowy poziom API emailAnalizuj wolumen wiadomości e-mail, czas odpowiedzi, wzorce konwersacji i nastroje w połączonych kontach zespołu. Zespoły marketingowe, operacyjne i finansowe wykorzystują analizę skrzynki odbiorczej do mierzenia jakości komunikacji i identyfikacji wąskich gardeł.
Pełny przewodnik po płatnych APIJak działa synchronizacja poczty e-mail: OAuth, synchronizacja delta i webhooki
API synchronizacji poczty e-mail to coś więcej niż punkt końcowy odczytu. Jest to stanowy potok, który uwierzytelnia użytkowników, utrzymuje aktualność tokenów, śledzi stan skrzynki pocztowej i dostarcza zmiany w czasie zbliżonym do rzeczywistego. Oto, co dzieje się na każdym poziomie.
Użytkownik klika w Twojej aplikacji "Połącz skrzynkę odbiorczą". Zostaje przekierowany na ekran zgody Google lub Microsoft, gdzie zatwierdza zakresy żądane przez Twoją aplikację. W przypadku Gmail oznacza to gmail.tylko_do_odczytu lub gmail.zmodyfikuj; dla programu Outlook oznacza Mail.Read lub Mail.ReadWrite. Po uzyskaniu zgody Twoja aplikacja otrzymuje token dostępu (ważne przez 1 godzinę dla Google, 1 godzinę dla Microsoftu) i a token odświeżający (długotrwały). Konta IMAP używają nazwy użytkownika i hasła lub OAuth, w zależności od konfiguracji dostawcy.
Podczas pierwszej synchronizacji API synchronizacji poczty e-mail wykonuje pełne uzupełnianie: pobiera listę folderów (INBOX, Wysłany, Wersje robocze, etykiety niestandardowe) i pobiera najnowsze wiadomości do konfigurowalnej głębokości historii. W przypadku Gmaila służy do tego lista wiadomości użytkowników z paginacją. Dla Microsoft Graph używa GET /ja/wiadomości. Dla IMAP wydaje WYBIERZ SKRZYNKĘ następnie a POBIERZ zakres. Migawka nadaje twojej bazie danych jej stan bazowy, w tym identyfikatory wiadomości i grupy wątków.
Po początkowym zrzucie (snapshot), wielokrotne odpytywanie całej skrzynki pocztowej marnowałoby limit miejsca i spowalniało aplikację. Synchronizacja przyrostowa (delta sync) jest rozwiązaniem. Gmail oferuje Identyfikator Historii kursor: wołasz użytkownicy.historia.lista z ostatnim znanym Identyfikator Historii i otrzymywać tylko zmiany (nowe wiadomości, zmiany etykiet, usunięcia) od tego momentu. Microsoft Graph używa GET /ja/wiadomości/delta with a $token delty. IMAP używa ID POBIERZ with a ZMIENIONO OD modyfikator (rozszerzenie CONDSTORE). Tak synchroniczna delta wzorzec utrzymuje minimalną liczbę wywołań API nawet w przypadku skrzynek pocztowych o dużej objętości.
Tokeny dostępu wygasają. Twoja infrastruktura synchronizacji poczty e-mail musi wykrywać 401 Nieautoryzowany odpowiedzi, użyj tokena odświeżania, aby uzyskać nowy token dostępu od Google lub Microsoft, i ponów nieudaną próbę żądania. Musi się to odbywać w sposób przejrzysty, bez przerywania sesji użytkownika. Tokeny odświeżania mogą zostać unieważnione – przez użytkownika, przez politykę administratora lub po 6 miesiącach braku aktywności (Google) – dlatego Twój system musi wykrywać unieważnienie i prosić użytkownika o ponowne uwierzytelnienie.
Sondowanie według harmonogramu wprowadza opóźnienie – sondowanie co 30 sekund oznacza, że e-maile mogą być nieaktualne nawet o 30 sekund. W przypadku funkcji skrzynki pocztowej w czasie rzeczywistym interfejs API synchronizacji poczty e-mail musi obsługiwać powiadomienia push. Gmail korzysta z Google Cloud Pub/Sub: rejestrujesz temat, a Gmail publikuje powiadomienie za każdym razem, gdy Identyfikator Historii postępy. Microsoft Graph korzysta z powiadomień o zmianach w /me/mailFolders/inbox/messages resource. Zunifikowane API synchronizacji poczty e-mail (takie jak Unipile) normalizuje je do pojedynczego zdarzenia webhooka – email.nowy - dostarczony do Twojego punktu końcowego niezależnie od dostawcy.
Natywne API synchronizacji wiadomości e-mail: Gmail, Microsoft Graph i IMAP
Każdy z trzech dostawców poczty e-mail udostępnia inny mechanizm synchronizacji. Zrozumienie różnic wyjaśnia, dlaczego stworzenie interfejsu API do synchronizacji poczty e-mail obejmującego wielu dostawców od zera zajmuje miesiące, a nie dni.
Gmail – historia.lista + Pub/Sub
Konta Google Workspace i konta osobiste
Model synchronizacji Gmaila opiera się na Identyfikator Historii kursor. Po początkowej synchronizacji, każde kolejne wywołanie użytkownicy.historia.lista zwraca tylko zmiany od twojej ostatniej znanej Identyfikator Historii - nowe wiadomości, dodanie etykiet, usunięcie etykiet i usunięcia.
Dla push w czasie rzeczywistym, Gmail wymaga od Ciebie skonfigurowania tematu Google Cloud Pub/Sub i wywołania użytkownicy.oglądaj aby go zarejestrować. Gmail następnie publikuje powiadomienie (zawierające nową Identyfikator Historii) do Twojego tematu za każdym razem, gdy zmieni się skrzynka pocztowa. Twój pracownik subskrybuje temat i wywołuje historia.lista aby pobrać faktyczne zmiany.
Limity stawek: 1 miliard jednostek kwoty dziennie na projekt, z limitami dla poszczególnych użytkowników. użytkownicy.wiadomości.pobierz kosztuje 5 jednostek; użytkownicy.historia.lista kosztuje 2 jednostki. W przypadku aplikacji wielodostępnej zarządzanie limitami staje się problemem na pełny etat. Zobacz Przewodnik po API poczty e-mail więcej.
z googleapiclient.discovery import budować
Synchronizacja # Delta z wykorzystaniem kursora historyId
def pobierz_zmiany(usługa, id_historii):
wynik = usługi.użytkownicy().historia().list(
identyfikatorUżytkownika='ja',
startIdHistorii=id_historii,
typy historii=[
'wiadomośćDodana',
'wiadomość usunięta',
'etykietaDodana'
]
).wykonaj()
return wynik.pobierz('historia', [])
Zapytania przyrostowe Outlook / Microsoft 365
Outlook Osobisty i Exchange Online / M365
Microsoft Graph używa zapytania delta na /ja/wiadomości/delta Punkt końcowy. Pierwsze wywołanie zwraca pełną stronę wiadomości plus @odata.deltaLink. Kolejne wywołania tego linku delta zwracają tylko zmienione wiadomości od poprzedniego wywołania — nowe, zmodyfikowane i usunięte elementy.
Dla push w czasie rzeczywistym, Microsoft Graph obsługuje powiadomienia o zmianach za pośrednictwem webhooków. Rejestrujesz subskrypcję na /me/mailFolders/inbox/messages with a notificationUrl. Microsoft wysyła POST do Twojego adresu URL, gdy wiadomości się zmieniają. Subskrypcje muszą być odnawiane co 4230 minut (około 3 dni) lub wygasają.
Uwaga: Obejmuje to zarówno osobiste konta Outlook, jak i Microsoft 365 / Exchange Online – używają one tego samego interfejsu API Graph. Zobacz Przewodnik po integracji poczty e-mail w Microsoft Graph po szczegóły dotyczące rejestracji aplikacji i zgody administratora.
// Synchronizacja przyrostowa w usłudze Microsoft Graph
async function pobierzWiadomościZmian(klient, deltaLink) {
const url = łącze delta
|| '/ja/wiadomości/delta';
const res = czekać klient
.API(url)
.wybierz('identyfikator,temat,od,dataOtrzymania')
.uzyskać();
return {
wiadomości: res.value,
nextDelta: res['@odata.deltaLink']
};
}
IMAP - polecenie IDLE + UID FETCH
Uniwersalny mechanizm zapasowy dla dowolnego serwera poczty
IMAP (RFC 3501) poprzedza nowoczesne API synchronizacji o dekady. Udostępnia on zawartość per-folder numery kolejności oraz UIDy. Dla synchronizacji przyrostowej, CONDSTORE rozszerzenie (RFC 7162) dodaje MODSEQ wartość do każdej wiadomości, pozwalając na pobranie tylko wiadomości z MODSEQ wyżej niż ostatnia znana wartość przez UID FETCH * (FLAGS) (CHANGEDSINCE modseq).
Dla push w czasie rzeczywistym, IMAP obsługuje BEZCZYNNOŚĆ polecenie (RFC 2177). Twój klient wysyła BEZCZYNNOŚĆ a serwer przepycha ISTNIEJE lub Wycofać odpowiedzi po zmianie folderu - nie jest wymagane sondowanie. Większość serwerów IMAP obsługuje IDLE; połączenia muszą być odświeżane co 29 minut, aby zapobiec przekroczeniu limitu czasu.
Protokół IMAP jest kluczowy, ponieważ obejmuje każdy serwer poczty e-mail, który nie jest zarządzany przez Google ani Microsoft: firmowe serwery Exchange (lokalne), ProtonMail, Zoho, Fastmail oraz domeny niestandardowe. Zobacz Przewodnik integracji IMAP aby uzyskać pełny opis implementacji.
const imap = require('imap');
const imap = nowy imap({ host, port: 993, tls: true });
imap.raz('gotowy', () => {
imap.openBox('SKRZYNKA', true, () => {
imap.on('przesyłka', (numNowych) => {
// IDLE push: nadeszła nowa poczta
pobierzNoweWiadomości(liczbaNowych);
});
});
});Pokrycie funkcji API poczty e-mail według dostawcy
Jedna integracja Unipile zapewnia dostęp do wszystkich operacji e-mail w usługach Gmail, Outlook i IMAP. Kliknij nagłówek dowolnego dostawcy, aby zapoznać się z pełnym przewodnikiem integracji.
| Cecha | Gmail | Outlook / M365 | IMAP / SMTP |
|---|---|---|---|
| Uwierzytelnianie | |||
| OAuth2 (bez przechowywania haseł) | ✓ | ✓ | Hasło aplikacji |
| Autoryzacja / przepływ zgody hostowany | ✓ | ✓ | ✓ |
| Automatyczne odświeżanie tokenu | ✓ | ✓ | ✓ |
| Operacje e-mail | |||
| Wyślij e-mail z konta użytkownika | ✓ | ✓ | ✓ |
| Czytaj i wypisz e-maile | ✓ | ✓ | ✓ |
| Wyślij z załącznikami | ✓ | ✓ | ✓ |
| Odpowiedz w istniejącym wątku | ✓ | ✓ | ✓ |
| Zarządzanie wersjami roboczymi | ✓ | ✓ | ✓ |
| Etykiety / Foldery | ✓Etykiety | ✓Foldery | ✓Foldery |
| Dzienne ograniczenie wysyłki (orientacyjnie) | ~500 dziennie | ~10 000 / dzień | Zależny od serwera |
| Synchronizacja i zdarzenia | |||
| Webhooki działające w czasie rzeczywistym | ✓ | ✓ | ✓ |
| Przyrostowa synchronizacja różnicowa | ✓ | ✓ | ✓ |
| Grupowanie wątków | ✓ | ✓ | ✓ |
| SOC 2 Typ II / CASA Poziom 2 | ✓ | ✓ | ✓ |
GmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPGmailOutlook / M365IMAP / SMTPPomiń boilerplate Gmail + Graph + IMAP. Jedno API synchronizacji poczty e-mail obejmuje wszystkie trzy.
Zunifikowane API synchronizacji poczty e-mail od Unipile łączy się z Gmail, Outlook i IMAP za pośrednictwem jednego punktu końcowego. Przepływy OAuth, odświeżanie tokenów, synchronizacja przyrostowa i webhooki - wszystko jest obsługiwane za Ciebie. Zacznij za darmo, bez konieczności podawania karty kredytowej.
Ukryta złożoność synchronizacji poczty e-mail na dużą skalę
Stworzenie API do synchronizacji poczty e-mail na zasadzie proof-of-concept zajmuje weekend. Stworzenie niezawodnego w produkcji z 1000 połączonych kont zajmuje miesiące. Oto, czego nikt ci z góry nie mówi.
Gmail wymusza limity na użytkownika (250 jednostek limitu/sekundę) i dzienne limity na projekt. Microsoft Graph przetwarza ograniczoną liczbę żądań (10 000 żądań/10 minut na aplikację). Mając 500 połączonych kont synchronizujących się zgodnie z harmonogramem, potrzebujesz rozproszonego ogranicznika szybkości z wykładniczym wycofywaniem, jitterem i izolacją kolejek na konto. Pojedynczy skok z jednego konta może wyczerpać limit dla wszystkich pozostałych.
Każde połączone konto posiada token dostępu, który wygasa. Przy 1000 kont możesz spodziewać się kilkudziesięciu jednoczesnych odświeżeń tokenów w godzinach szczytu synchronizacji. Jedno nieudane odświeżenie powoduje pominięcie cykli synchronizacji. Potrzebujesz dedykowanej usługi zarządzania cyklem życia tokenów z logiką ponawiania prób, wykrywaniem unieważnienia i potokiem powiadomień, aby zachęcić użytkowników do ponownej autoryzacji, gdy tokeny odświeżania wygasną.
Gmail używa etykiet (jedna wiadomość może mieć jednocześnie wiele etykiet). Outlook używa folderów (hierarchicznych, z operacjami przenoszenia). IMAP również używa folderów, ale z przestrzenie nazw które różnią się w zależności od dostawcy serwera. Normalizacja tych danych do spójnego modelu folderów dla Twojej aplikacji wymaga logiki mapowania specyficznej dla dostawcy. Przypadki brzegowe obejmują skrzynki współdzielone, dostęp delegowany oraz rozróżnienie w Gmailu między "Wszystkie e-maile" a "Skrzynką odbiorczą".
Załączniki do wiadomości e-mail mogą być duże. Pobieranie i przechowywanie załączników dla każdego zsynchronizowanego e-maila na tysiącach kont szybko zwiększa koszty przepustowości i przechowywania. Potrzebujesz strumieniowego potoku, który pobiera załączniki tylko na żądanie, z deduplikowanym przechowywaniem i warstwą CDN do serwowania ich z Twojego produktu. Samo parsowanie MIME wprowadza błędy - wieloczęściowe wiadomości e-mail, kodowanie quoted-printable i załączniki inline wymagają indywidualnej obsługi.
Wątki Gmaila według threadId - koncepcja po stronie serwera. IMAP nie ma natywnego wątkowania; wątki odtwarzasz przy użyciu Bibliografia oraz Odpowiedź-Do nagłówki (RFC 5322). Outlook ma ID konwersacji. Normalizacja wątków między dostawcami - szczególnie w przypadku odpowiedzi między dostawcami - wymaga heurystyk rezerwowych opartych na normalizacji tematu i łańcuchach identyfikatorów wiadomości.
Powiadomienia Gmail Pub/Sub nie są gwarantowane – pominięte wiadomości podczas przestoju nie są wysyłane ponownie. Subskrypcje sieci webhook Microsoft Graph wygasają i muszą być odnawiane. Jeśli odbiornik sieci webhook jest niedostępny podczas powiadomienia push, pominięto zdarzenie i następuje powrót do pobierania próbkującego (polling). Produkcyjne API synchronizacji poczty e-mail wymaga pętli rekonsyliacji, która okresowo nadrobi pominięte zdarzenia przy użyciu wskaźnika synchronizacji delta, niezależnie od dostępności sieci webhook.
Porównanie 3 architektur synchronizacji poczty e-mail
Zespoły tworzące funkcje synchronizacji poczty e-mail zazwyczaj oceniają trzy wzorce implementacji. Oto szczera analiza każdego z nich, od nakładu pracy przy budowie po bieżące koszty utrzymania.
Synchronizuj e-maile za pomocą API Unipile Unified Email Sync
API synchronizacji poczty e-mail Unipile obsługuje Gmail, Outlook i IMAP za pośrednictwem jednego ujednoliconego interfejsu. Przepływy OAuth, odświeżanie tokenów, synchronizacja przyrostowa i dostarczanie webhooków są zarządzane za Ciebie – Twój zespół wdraża funkcję, a nie infrastrukturę.
Zapisz się na dashboard.unipile.com. Darmowy poziom API e-mail zapewnia dostęp do wszystkich dostawców bez konieczności podawania danych karty kredytowej. Nazwę źródła danych (DSN) i token API otrzymasz natychmiast.
Użyj przepływu OAuth hostowanego przez Unipile'a, aby zezwolić użytkownikowi na dostęp do jego konta Gmail lub Outlook. W przypadku IMAP, zbierz ich dane uwierzytelniające i przekaż je do POST /accounts. Unipile obsługuje przekierowania OAuth, wymianę tokenów i bezpiecznie przechowuje token odświeżania.
Zadzwoń GET /emails z account_id połączonego konta. Unipile przeprowadza synchronizację przyrostową z Gmail historia.lista, punktu Delta Microsoft Graph lub IMAP CONDSTORE - zawsze otrzymujesz tę samą znormalizowaną odpowiedź JSON, niezależnie od dostawcy.
Opublikuj swój adres URL punktu końcowego w interfejsie API webhook Unipile. Po otrzymaniu nowej wiadomości e-mail na dowolnym połączonym koncie - czy to Gmail, Outlook, czy IMAP - Unipile dostarcza znormalizowany email.nowy zdarzenie do Twojego adresu URL. Bez konfiguracji Pub/Sub, bez odnawiania subskrypcji grafu, bez zarządzania połączeniem IDLE. Zobacz Przewodnik po API poczty e-mail do pełnego odniesienia wydarzenia.
Zadzwoń GET /emails/{id} aby pobrać pełne ciało wiadomości (HTML i zwykły tekst), nagłówki, części MIME i odniesienia do załączników. Załączniki są udostępniane za pomocą podpisanych adresów URL – nigdy nie musisz samodzielnie przechowywać surowych danych MIME. Zobacz odczytywać e-maile programowo na przykład.
const axios = require('axios');
const DSN = process.env.UNIPILE_DSN;
const ŻETON = process.env.UNIPILE_TOKEN;
const API = axios.create({
baseURL: `https://${DSN}/api/v1`,
nagłówki: { 'Klucz API X': TOKEN }
});
// Krok 3 - Lista zsynchronizowanych wiadomości e-mail
async function listaEmaili(accountId) {
const { dane } = czekać api.uzyskać('/wiadomosci', {
params: {
identyfikator_konta: accountid,
folder: 'SKRZYNKA',
limit: 20
}
});
return dane.elementy;
}
// Krok 4 - Zarejestruj webhook
async function zarejestrujWebhook() {
czekać api.stanowisko('/webhooks', {
adres url 'https://yourapp.com/api/email-events',
wydarzenia: ['email.nowy', 'email.updated']
});
}
// Krok 5 - Pobierz pełną treść wiadomości e-mail
async function PobierzEmail(emailId) {
const { dane } = czekać api.uzyskać(`/emails/${emailId}`);
return dane;
}Przestańcie odbudowywać ten sam potok synchronizacji poczty dla każdego dostawcy.
Połącz Gmail, Outlook i IMAP za pomocą jednego API do synchronizacji poczty e-mail. Obsługujemy webhooky w czasie rzeczywistym, synchronizację przyrostową i zarządzanie tokenami OAuth. Twój zespół może skupić się na produkcie, a nie na technicznych szczegółach.
Synchronizacja e-maili w czasie rzeczywistym: Webhooki vs. Polling vs. IMAP IDLE
Wybór niewłaściwego mechanizmu czasu rzeczywistego dla Twojego API synchronizacji poczty e-mail wprowadza opóźnienia, zużywa kwotę lub pozostawia aplikację bez nadzoru podczas awarii. Oto bezpośrednie porównanie trzech podejść.
| Podejście | Jak to działa | Opóźnienie | Najlepszy dla | Złożoność |
|---|---|---|---|---|
| Webhooks (push) | Dostawca wysyła żądanie HTTP POST do Twojego punktu końcowego, gdy skrzynka pocztowa ulegnie zmianie. Gmail używa Pub/Sub; Microsoft Graph używa powiadomień o zmianach. | Dzieci poniżej 5 lat | Gmail, Outlook, zunifikowane interfejsy API, takie jak Unipile | Średni zarządzanie subskrypcjami wymagane |
| Ankieta (zaplanowana) | Twój pracownik cyklicznie (co 30 sekund, 1 minutę, 5 minut) wywołuje API dostawcy i pobiera zmiany za pomocą kursora delta. | 30s-5min | Wszyscy dostawcy, proste konfiguracje | Niski - ale zasado-intensywne na dużą skalę |
| IMAP IDLE (długie zapytania) | Klient wysyła IDLE do serwera; serwer wysyła powiadomienia EXISTS, gdy przychodzi nowa poczta. Połączenie utrzymywane jest do 29 min. | Poniżej 1 roku | Tylko serwery IMAP | Wysoki - jedno połączenie TCP na skrzynkę pocztową |
Rekomendacja produkcyjna: Użyj webhooków jako podstawowego mechanizmu w czasie rzeczywistym i skonfiguruj zapasowe odpytywanie typu delta-sync (co 5 minut), aby przechwytywać pominięte zdarzenia podczas przestojów. Dzięki API synchronizacji poczty e-mail Unipile, oba są konfigurowane raz - zunifikowany email.nowy webhook uruchamia się niezależnie od tego, czy konto jest Gmail, Outlook, czy IMAP, a pętla rekonsiliacji w tle automatycznie obsługuje pominięte zdarzenia.
Bezpieczeństwo i zgodność dla interfejsów API synchronizacji poczty e-mail
Dostęp do skrzynek pocztowych użytkowników tworzy znaczące obowiązki związane z bezpieczeństwem i zgodnością z przepisami. Oto, co implementacja Twojego API do synchronizacji poczty e-mail musi uwzględnić przed wdrożeniem produkcyjnym.
Żądaj tylko tych zakresów, których potrzebuje Twoja aplikacja. W przypadku synchronizacji poczty e-mail tylko do odczytu, żądaj gmail.tylko_do_odczytu zamiast gmail.zmodyfikuj. Dla Microsoft Graph, żądanie Mail.Read zamiast Mail.ReadWrite. Weryfikacja CASA Google (wymagana w przypadku aplikacji z ponad 100 użytkownikami) dokładnie analizuje żądane przez Ciebie zakresy uprawnień – nadmierne zakresy opóźniają zatwierdzenie.
Tokeny odświeżające OAuth to długożyjące dane uwierzytelniające, które udzielają pełnego dostępu do skrzynki pocztowej. Muszą być przechowywane zaszyfrowane w spoczynku (minimum AES-256) i nigdy nie powinny być logowane. Regularnie rotuj klucze szyfrowania tokenów. Kompromitacja tokena odświeżającego jest równoznaczna z kompromitacją hasła do połączonego konta e-mail.
Treści e-mail synchronizowane od użytkowników z UE są danymi osobowymi w rozumieniu RODO. Potrzebujesz podstawy prawnej do przetwarzania (zazwyczaj wyraźnej zgody użytkownika za pośrednictwem OAuth), umowy o przetwarzaniu danych z dostawcą interfejsu API do synchronizacji poczty e-mail oraz jasnej polityki retencji danych. Jeśli Twoja infrastruktura znajduje się w USA, upewnij się, że posiadasz klauzule standardowe lub równoważny mechanizm transferu danych z UE.
Każda aplikacja korzystająca z zakresów OAuth Gmail z ponad 100 użytkownikami musi ukończyć proces Google Ocena Bezpieczeństwa Aplikacji w Chmurze (CASA). Jest to przegląd bezpieczeństwa Państwa aplikacji, obejmujący kod, infrastrukturę oraz uzasadnienie zakresu OAuth. Proces trwa od 4 do 8 tygodni. Zacznijcie Państwo wcześnie – niezaliczenie CASA oznacza utratę dostępu do Gmaila dla wszystkich użytkowników, dopóki nie zostanie on pomyślnie przeprowadzony.
Zawsze weryfikuj podpis na przychodzących ładunkach webhook z Twojego API synchronizacji poczty e-mail. Niepodpisany lub nieprawidłowo zweryfikowany webhook może zostać spreparowany w celu wstrzyknięcia fałszywych zdarzeń e-mail do Twojej aplikacji. Unipile podpisuje wszystkie dostarczane webhooki za pomocą HMAC-SHA256. Zweryfikuj X-Unipile-Signature nagłówek przed przetworzeniem dowolnego zdarzenia.
Rejestruj każdą czynność wykonywaną przez Twoją aplikację na zsynchronizowanych danych poczty e-mail: kto uzyskał dostęp do których wiadomości, kiedy i co zostało z danymi zrobione. Logi audytu są wymagane do zgodności z SOC 2 Type II i są często pierwszą rzeczą, o którą pytają klienci korporacyjni podczas przeglądów bezpieczeństwa. Przechowuj logi przez minimum 90 dni, optymalnie 1 rok.
Częste pułapki podczas tworzenia API do synchronizacji poczty e-mail
Oto najczęściej spotykane błędy i wady architektoniczne w implementacjach API synchronizacji poczty e-mail. Wszystkim można zapobiec dzięki odpowiednim decyzjom projektowym na początku.
Gdy token odświeżania wygaśnie lub zostanie unieważniony, naiwna implementacja zgłasza błąd i zatrzymuje synchronizację – po cichu. Użytkownik nie wie, że jego skrzynka pocztowa przestała się synchronizować, dopóki nie zauważy nieaktualnych danych. Napraw implementuj warstwę wykrywania odwołania, która wyłapuje nieprawidłowe_poświadczenie błędy, oznacza połączone konto jako wymagające ponownej autoryzacji i powiadamia użytkownika za pośrednictwem systemu powiadomień Twojego produktu.
Okresowe sprawdzanie co 10 sekund w 200 połączonych kontach wyczerpuje limit przydziału Gmail na projekt w ciągu kilku godzin. Microsoft Graph zaczyna zwracać 429 Zbyt wiele żądań. Wynikiem są ciche błędy synchronizacji dla wszystkich kont - nie tylko tych, które wywołały ograniczenie przepustowości. Napraw Użyj webhooków jako głównego mechanizmu z 5-minutowym cyklicznym sprawdzaniem jako zapasowym, i wdróż ograniczanie żądań na konto z wykładniczym wycofywaniem się dla wszystkich elementów 429 odpowiedzi.
Surowy format MIME jest obszerny, trudny do przeszukiwania i kosztowny w parsowaniu podczas odczytu. Pojedyncza wiadomość e-mail z załącznikami może mieć setki kilobajtów. Napraw przetwarzaj dane MIME podczas pobierania: wyodrębnij osobno treść HTML, tekst zwykły (jako rozwiązanie awaryjne), nagłówki oraz metadane załączników. Przechowuj pliki binarne załączników w pamięci obiektowej (S3 lub jej odpowiedniku), a nie w głównej bazie danych. Już samo to pozwala obniżyć koszty przechowywania danych o 60–80% w przypadku typowych skrzynek pocztowych w firmach.
Gmail threadId działa tylko w Gmailu. Jeśli Twoja aplikacja wyświetla wątek obejmujący konto Gmail i konto Outlook (np. odpowiedź wysłaną z innej skrzynki pocztowej), natywne identyfikatory wątków są bezużyteczne. Napraw zbuduj silnik wątków między dostawcami oparty na Identyfikator wiadomości, Odpowiedź-Dooraz Bibliografia nagłówki. Znormalizuj tematy wiadomości (usuń prefiksy Re:/Fwd:) jako rozwiązanie awaryjne dla wiadomości, którym brakuje tych nagłówków.
Synchronizacja delty opiera się na przechowywanym kursorze: Gmaila Identyfikator Historii, Microsoft Graph łącze delta, IMAP MODSEQ. Jeśli twój pracownik synchronizacji zostanie zrestartowany, a kursor jest przechowywany tylko w pamięci, tracisz swoją pozycję w strumieniu zmian. Kolejna synchronizacja rozpocznie się od nowa, duplikując wszystkie historyczne wiadomości lub pomijając lukę. Napraw trwale przechowuj kursor w swojej bazie danych po każdym pomyślnym cyklu synchronizacji, atomowo z ostatnią partią przetworzonych zmian.
Do zastosowań CRM potrzebne są zarówno wiadomości przychodzące (otrzymane), jak i wychodzące (wysłane) e-maile, aby zbudować pełną oś czasu komunikacji. Etykieta SKRZYNKA POCZTOWA w Gmailu obejmuje tylko otrzymane wiadomości; potrzebujesz również WYSŁANE. Microsoft Graph wymaga wykonania zapytań do Wysłane folder osobno. IMAP wymaga wybrania Wysłany folder jawnie. Napraw synchronizuj wszystkie istotne foldery podczas konfiguracji konta, nie tylko SKRZYNKĘ ODBIORCZĄ i mapuj nazwy folderów specyficzne dla dostawcy na znormalizowane typy w swoim modelu danych.
Najczęściej zadawane pytania dotyczące interfejsów API synchronizacji poczty e-mail
Najczęstsze pytania, które programiści zadają podczas pierwszej implementacji interfejsu API synchronizacji poczty e-mail.
Identyfikator Historii kursor z użytkownicy.historia.lista endpoint. Microsoft Graph używa łącze delta zwrócone przez /wiadomości/delta endpoint. IMAP używa MODSEQ wartość z rozszerzenia CONDSTORE. Zunifikowany interfejs API synchronizacji poczty e-mail normalizuje te trzy różne mechanizmy za jednym spójnym interfejsem.GET /emails z account_id aby pobrać zsynchronizowane wiadomości i zarejestrować punkt końcowy webhook do odbierania w czasie rzeczywistym email.nowy Zdarzenia. Unipile automatycznie obsługuje OAuth, odświeżanie tokenów, synchronizację przyrostową i dostarczanie webhooków.gmail.tylko_do_odczytu. Jeśli musisz oznaczyć wiadomości jako przeczytane lub przenieść je, poproś gmail.zmodyfikuj. Dla Microsoft Graph, żądanie Mail.Read do dostępu tylko do odczytu lub Mail.ReadWrite aby uzyskać pełny dostęp. Zawsze żądaj minimalnych zakresów, których Twoja aplikacja faktycznie potrzebuje – weryfikacja CASA Google (wymagana w przypadku aplikacji z ponad 100 użytkownikami) dokładnie analizuje uzasadnienie zakresów, a nadmierne zakresy mogą opóźnić zatwierdzenie.401 Nieautoryzowany odpowiedzi, użyj zapisanego tokenu odświeżania, aby uzyskać nowy token dostępu i przezroczysto ponów nieudaną próbę żądania. Tokeny odświeżania same mogą zostać unieważnione. Po wykryciu unieważnienia (nieprawidłowe_poświadczenie error), oznacz konto jako wymagające ponownej autoryzacji i powiadom użytkownika. Unipile automatycznie zarządza całym cyklem życia tokenów dla połączonych kont.ISTNIEJE powiadomienia o nowych wiadomościach. Umożliwia to synchronizację skrzynki odbiorczej w niemal czasie rzeczywistym (opóźnienie poniżej 1 sekundy) bez ciągłego odpytywania. Połączenia IDLE muszą być odświeżane co 29 minut, aby zapobiec przekroczeniu czasu połączenia przez serwer. IDLE działa z każdym serwerem IMAP, który go obsługuje, w tym z większością nowoczesnych serwerów pocztowych, takich jak firmowy Exchange, Gmail przez IMAP i Outlook przez IMAP.