API pocztowe: Kompletny przewodnik dla deweloperów (2026)

Integracja API poczty e-mail: od OAuth do synchronizacji w czasie rzeczywistym

Integracja z rzeczywistym API poczty e-mail obejmuje cztery fazy, niezależnie od tego, z którego dostawcy chcesz skorzystać. Przeczytaj tę sekcję jako listę kontrolną przed rozpoczęciem implementacji: pominięcie któregokolwiek z tych kroków jest najczęstszym powodem, dla którego integracje działają w środowisku deweloperskim, a psują się w środowisku produkcyjnym.

Uwierzytelnianie OAuth 2.0

Zarówno Gmail, jak i Microsoft Graph używają standardowego Przepływ kodu autoryzacji OAuth 2.0. Mechanika jest identyczna: przekieruj użytkownika do dostawcy, odbierz jednorazowy kod na swoim adresie URL zwrotny, wymień go na długoterminowy token odświeżania po stronie serwera, a następnie użyj tego tokena odświeżania do generowania krótkoterminowych tokenów dostępu dla każdego kolejnego wywołania API.

• Przekieruj użytkownika do punktu autoryzacji dostawcy z Twoim client_id, przekierowanie_uri, i żądana zakres.
• Użytkownik udziela uprawnień, dostawca przekierowuje do Twojego adresu URL zwrotnego z jednorazowym kod parametr.
• Twój serwer wymienia to kod dla token_dostępu (czas życia 1 godzina) i token_odświeżający przez tylne połączenie POST.
• Przechowywać token_odświeżający bezpiecznie po stronie serwera, szyfrowany podczas przechowywania. Jest to długoterminowy poświadczenie używane do automatycznego generowania nowych tokenów dostępu.

Wysyłaj i odbieraj e-maile

Po uwierzytelnieniu dwie kolejne operacje obejmują 80% typowego użycia API poczty e-mail: pobieranie skrzynki odbiorczej oraz wysyłanie wiadomości. Dzięki ujednoliconemu API Unipile, oba działają identycznie w Gmailu, Outlooku i IMAP poprzez jeden zestaw punktów końcowych.

# Pobierz 50 najnowszych wiadomości e-mail z połączonej skrzynki odbiorczej
curl --request GET \
  --url 'https://api.unipile.com/api/v1/emails?limit=50&folder=inbox' \
  --header 'X-API-KEY: YOUR_API_KEY'

# Wyślij zwykły e-mail tekstowy
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "YOUR_ACCOUNT_ID",
    "subject": "Witaj z Unipile",
    "body": "Cześć, to jest zwykły e-mail tekstowy",
    "to": [{"display_name":"John Doe","identifier":"john@example.com"}]
  }'

Unipile obsługuje również typowe zaawansowane funkcje wysyłania, których oczekują programiści: załączniki (multipart form-data z wieloma plikami), niestandardowe nagłówki przekazywanie tablic X- nagłówki z prefiksem), odpowiedz-w-wątku (używając oryginalnej wiadomości provider_id), nadpisanie nazwy wyświetlanej, dozwolone aliasy nadawcy, oraz śledzenie otwarć / linków z zdarzeniami webhook w czasie rzeczywistym. Każde z nich odpowiada pojedynczemu polu w treści żądania, negocjacja protokołu nie jest wymagana.

# Wyślij z załącznikami + niestandardowymi nagłówkami + śledzeniem
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --form 'account_id=YOUR_ACCOUNT_ID' \
  --form 'subject=Draft umowy' \
  --form 'body=Proszę znaleźć załączony dokument w wersji 3.' \
  --form 'to=[{"identifier":"sarah@acme.com"}]' \
  --form 'attachments=@/path/to/contract.pdf' \
  --form 'attachments=@/path/to/appendix.png' \
  --form 'custom_headers=[{"name":"X-Campaign-ID","value":"q1-outreach"}]' \
  --form 'tracking_options={"opens":true,"links":true,"label":"q1-outreach"}'

Aby uzyskać pełne odniesienie dla deweloperów obejmujące wszystkie opcje wysyłki i zachowania specyficzne dla dostawcy, zobacz nasze Przewodnik po API do wysyłania e-maili.

Synchronizacja poczty e-mail w czasie rzeczywistym

Synchronizacja skrzynki odbiorczej jest najtrudniejszą częścią każdej integracji poczty e-mail i często jest najmniej zrozumiała. Solidna synchronizacja poczty wdrożenie ma trzy odrębne fazy: synchronizacja początkowa, synchronizacja przyrostowa i powiadomienia webhook w czasie rzeczywistym. Pominięcie któregokolwiek z nich skutkuje integracją, która działa od pierwszego dnia i rozpada się przy skalowaniu.

Plan odnowień od pierwszego dnia: subskrypcje obserwowania Gmail Pub/Sub wygasają po 7 dniach i muszą zostać odnowione. Subskrypcje Microsoft Graph dotyczące zasobów poczty wygasają po maksymalnie około 3 dniach. Wbuduj odnawianie subskrypcji w swoją infrastrukturę zadań w tle przed wprowadzenie na produkcję, w przeciwnym razie Twoja integracja przestanie cicho odbierać zdarzenia.

Webhooki i zdarzenia

Webhooki to sposób, w jaki nowoczesne API pocztowe informuje Twój backend o tym, co się wydarzyło, w czasie rzeczywistym, bez konieczności pytania. Zamiast odpytywania /komunikaty co 30 sekund (drogo i wolno), subskrybujesz raz, a dostawca popycha ładunek JSON do Twojego punktu końcowego za każdym razem, gdy przychodzi nowy e-mail, gdy jest odczytywany, gdy jest na niego odpowiadane lub gdy jest usuwany.

Zwykle subskrybujesz następujące wydarzenia: mail_received (nowa wiadomość przyszła do skrzynki odbiorczej), mail_sent (wiadomość wychodząca została pomyślnie dostarczona), mail_opened (odbiorca otworzył, jeśli śledzenie jest włączone), kliknięty_link_mail (odbiorca kliknął śledzony link), i status_konta (Połączona skrzynka pocztowa wymaga ponownego uwierzytelnienia, np. po zmianie hasła). Każde zdarzenie niesie ze sobą wystarczający kontekst, aby systemy poniżej mogły zareagować bez konieczności wykonywania dodatkowych wywołań API.