Gmail API

Gmail API to interfejs programistyczny umożliwiający integrację aplikacji zewnętrznych z tą usługą pocztową.

Model działania Gmail API i zakres operacji

Gmail API jest internetowym interfejsem REST udostępnianym przez Google do programowej obsługi skrzynek Gmail i Google Workspace. Aplikacja komunikuje się z usługą przez żądania HTTPS, a dane wejściowe i wyniki są przekazywane głównie w formacie JSON. Interfejs pozwala między innymi odczytywać wiadomości, wyszukiwać je według składni używanej przez Gmail, pobierać wątki, sprawdzać etykiety, tworzyć wersje robocze oraz wysyłać i modyfikować pocztę.

W Gmail API wiadomość i wątek są odrębnymi zasobami. Wiadomość ma własny identyfikator, nagłówki, treść oraz informacje o załącznikach, natomiast wątek grupuje korespondencję należącą do jednej rozmowy. Etykiety, takie jak Inbox, Sent, Trash czy Spam, są osobnymi zasobami i mogą być nakładane na wiadomości lub usuwane z nich za pomocą odpowiednich operacji. Takie rozdzielenie ma znaczenie podczas synchronizacji, ponieważ zmiana etykiety nie musi oznaczać zmiany treści wiadomości.

Autoryzacja, zakresy uprawnień i format poczty

Dostęp do Gmail API wymaga uwierzytelnienia oraz zgody na określone zakresy OAuth 2.0. Zakres uprawnienia, czyli scope, określa, jakie operacje aplikacja może wykonywać. Można przyznać dostęp tylko do odczytu, do zarządzania etykietami albo do szerszej obsługi skrzynki. Token dostępu jest używany przy żądaniach do API, a token odświeżania pozwala uzyskać kolejny token po wygaśnięciu bieżącego dostępu. Zakresy Gmail są wrażliwe, dlatego aplikacja korzystająca z szerszych uprawnień może wymagać dodatkowej weryfikacji po stronie Google.

Treść poczty jest oparta na formacie MIME i nagłówkach wiadomości internetowych. Przy pobieraniu wiadomości API może zwrócić samą metadane, pełną strukturę MIME albo surowy komunikat. W operacjach wykorzystujących pole raw komunikat jest kodowany algorytmem base64url, a nie zwykłym kodowaniem base64 z końcowymi znakami dopełnienia. Przy wysyłaniu wiadomości aplikacja przygotowuje poprawny komunikat z nagłówkami From, To, Subject i MIME, następnie koduje go w wymagany sposób i przekazuje do metody wysyłania lub do wersji roboczej. Załącznik musi być częścią poprawnej struktury MIME; sam plik przesłany jako niezależne pole nie staje się automatycznie załącznikiem pocztowym.

Odczyt, wysyłanie i synchronizacja skrzynki

Typowy odczyt wiadomości składa się z pobrania listy identyfikatorów, a następnie wywołania operacji pobierającej szczegóły wybranych wiadomości. Parametr formatu może ograniczyć odpowiedź do nagłówków albo metadanych, co zmniejsza ilość przesyłanych danych. Wyszukiwanie może korzystać z zapytań Gmail, na przykład filtrów dotyczących nadawcy, odbiorcy, tematu, etykiety lub zakresu dat. Do oznaczania wiadomości jako przeczytanych, przenoszenia ich między kategoriami czy usuwania etykiet służy operacja modyfikacji, która przyjmuje identyfikatory etykiet do dodania i usunięcia.

Gmail API obsługuje również tworzenie wersji roboczych i wysyłanie poczty. Wersja robocza zawiera przygotowaną wiadomość, którą można później zaktualizować albo wysłać. Wysłanie wiadomości przez API nie jest tym samym co połączenie z serwerem SMTP z użyciem programu pocztowego, chociaż rezultat dla odbiorcy jest podobny. Aplikacja musi obsłużyć odpowiedzi HTTP, stronicowanie wyników oraz błędy autoryzacji, braku uprawnień, przekroczenia limitów i nieprawidłowych parametrów. Kod integracji powinien też unikać wielokrotnego wysyłania tego samego żądania po błędzie sieciowym, ponieważ nie zawsze da się od razu ustalić, czy operacja po stronie Google została już wykonana.

Do wykrywania zmian Gmail API udostępnia mechanizm historii skrzynki. Aplikacja może zapamiętać wartość historyId, a następnie pobierać zmiany od tego punktu zamiast ponownie analizować całą skrzynkę. Przy powiadomieniach usługi można użyć metody watch, która przekazuje informację o zmianie do usługi Google Cloud Pub/Sub. Powiadomienie nie zawiera pełnej wiadomości; informuje o dostępności zmiany, którą trzeba później odczytać przez mechanizm historii. Subskrypcja ma ograniczony czas ważności i wymaga odnowienia. Jeżeli wskazany punkt historii jest już niedostępny, aplikacja musi wykonać pełną synchronizację, aby odbudować lokalny stan.

Gmail API w naprawie aplikacji pocztowych i komputerów

Błąd działania integracji z Gmail API może wynikać z kilku różnych warstw: nieaktywnego projektu Google Cloud, niepoprawnego identyfikatora klienta OAuth, braku zgody na wymagany scope, wygasłego tokenu, błędnego adresu przekierowania albo nieprawidłowo przygotowanej wiadomości MIME. Sama możliwość zalogowania się do Gmaila w przeglądarce nie potwierdza poprawności integracji, ponieważ aplikacja korzysta z osobnego klienta OAuth i osobnego zestawu uprawnień. Podczas diagnostyki warto sprawdzić kod odpowiedzi HTTP, treść komunikatu błędu, użyty scope, identyfikator użytkownika oraz to, czy żądanie jest wysyłane do właściwego środowiska.

Na komputerze użytkownika można także sprawdzić, czy aplikacja ma stabilne połączenie HTTPS, poprawny czas systemowy i dostęp do sieci bez blokowania domen Google przez zaporę lub filtr DNS. Zła data i godzina mogą powodować odrzucanie tokenów oraz błędy weryfikacji certyfikatów. Jeżeli problem dotyczy tylko wysyłania, należy dodatkowo przeanalizować strukturę MIME, kodowanie base64url, nagłówki adresowe i rozmiar wiadomości. Jeżeli problem dotyczy synchronizacji, trzeba porównać zapisany historyId z odpowiedzią usługi oraz sprawdzić, czy aplikacja prawidłowo odnawia subskrypcję watch i obsługuje odpowiedzi 429 związane z ograniczeniem liczby żądań.

Warszawskie Pogotowie Komputerowe zajmuje się profesjonalną naprawą laptopów i komputerów PC, dlatego w przypadku problemu z programem pocztowym może sprawdzić konfigurację systemu, połączenie sieciowe, działanie przeglądarki lub klienta poczty oraz objawy występujące podczas korzystania z integracji Gmail API. Sama zmiana hasła do Gmaila nie naprawia błędnej konfiguracji OAuth ani uszkodzonego mechanizmu synchronizacji; konieczne jest ustalenie, czy usterka występuje w aplikacji, systemie lokalnym, sieci czy po stronie konfiguracji usługi Google.