# E-mail Integracja e-mail z Ritevo: podłączenie skrzynki IMAP/SMTP, hasło aplikacji, pobieranie maili jako wątków i odpowiadanie klientom z Ritevo. Integracja e-mail podłącza do Ritevo zwykłą skrzynkę pocztową - firmową, Gmail, Outlook albo dowolną inną, która obsługuje IMAP i SMTP. Maile od klientów trafiają do wspólnej skrzynki **Wiadomości** obok rozmów z marketplace'ów i sklepów, a odpowiadasz na nie z Ritevo. Przez e-mail obsłużysz też kanały sprzedaży, które nie mają własnej skrzynki wiadomości - na stronie takiej integracji jest to zaznaczone. > **Wymagana integracja:** Potrzebujesz adresu e-mail, hasła do skrzynki (albo hasła aplikacji) i skrzynki, która pozwala łączyć się przez IMAP i SMTP. Jedną skrzynkę podłączasz raz; jeśli obsługujesz kilka adresów, każdy dodajesz jako osobną integrację. W ramach jednego konta firmowego dany adres podłączysz tylko raz: gdy Ty albo ktoś z Twoich współpracowników doda go ponownie, odświeży się istniejąca integracja - także wtedy, gdy wcześniej została usunięta - a druga nie powstanie. Nowe hasło i ustawienia serwera zastąpią poprzednie. Unikalność: integracja jest unikalna w ramach firmy po `email` i typie `EMAIL`. Ponowne utworzenie odświeża istniejącą integrację zamiast tworzyć nową: od razu ustawia `authError=false`, a jeśli integracja była nieaktywna - także `active=true`. Nowe dane podasz też przez `PATCH /integrations/email/{integrationId}/credentials` - w każdym stanie integracji, także gdy `authError=false` i `active=true`; ustawia `authError=false` i `active=true`. ## Hasło aplikacji Część dostawców poczty nie wpuszcza programów zewnętrznych na zwykłe hasło do logowania. Wtedy w ustawieniach konta pocztowego generujesz **hasło aplikacji** i to ono trafia do Ritevo: - **Gmail** - hasło aplikacji tworzysz w ustawieniach konta Google, w sekcji bezpieczeństwa. Wymaga włączonej weryfikacji dwuetapowej. - **Outlook, Yahoo, iCloud** - podobnie: hasło aplikacji w ustawieniach bezpieczeństwa konta. - **Poczta firmowa u hostingu** - zwykle wystarczy zwykłe hasło do skrzynki. ## Podłączenie konta Zacznij w Ritevo: 1. Wejdź w **Integracje** w lewym panelu i kliknij **Dodaj integrację** w prawym górnym rogu. 2. W sekcji **Poczta e-mail** wybierz kafelek **Email**. 3. W polu **Nazwa konta** wpisz własną nazwę integracji, na przykład „Obsługa klienta". 4. W polu **Adres e-mail** wpisz adres skrzynki. Ritevo od razu uzupełni dane serwera na podstawie tego adresu - opis niżej. 5. W polu **Hasło** wpisz hasło do skrzynki albo hasło aplikacji. 6. Kliknij **Dodaj integrację**. Ritevo od razu łączy się z serwerem poczty - osobno z odbieraniem (IMAP) i wysyłaniem (SMTP). Jeśli oba połączenia się udadzą, integracja zostaje dodana i otworzą się jej ustawienia. Jeśli nie - zobaczysz błąd zwrócony przez serwer i nic nie zostanie zapisane. ![Lista integracji w Ritevo z zaznaczonym przyciskiem Dodaj integrację w prawym górnym rogu](https://ritevo.com/docs/integrations/pl-integrations-list.webp) ![Ekran Dodaj integrację z wybranym filtrem Poczta e-mail i zaznaczonym kafelkiem Email](https://ritevo.com/docs/integrations/email/pl-catalogue.webp) ![Ekran dodawania integracji e-mail z polami Nazwa konta, Adres e-mail i Hasło, informacją o haśle aplikacji i przyciskiem Pokaż ustawienia zaawansowane](https://ritevo.com/docs/integrations/email/pl-add.webp) ## Ustawienia serwera (IMAP / SMTP) Ustawienia serwera są schowane pod **Pokaż ustawienia zaawansowane**. Zwykle nie musisz ich ruszać - rozwiń je, gdy dodanie integracji się nie powiedzie: - **Login (opcjonalnie)** - zostaw puste, jeśli logujesz się adresem e-mail. Uzupełnij tylko wtedy, gdy serwer wymaga innego loginu. - **Serwer IMAP (odbieranie)** i **Port IMAP** - skąd Ritevo pobiera maile. - **Serwer SMTP (wysyłanie)** i **Port SMTP** - przez który serwer Ritevo wysyła Twoje odpowiedzi. - **Szyfrowanie** - **SSL/TLS** albo **STARTTLS**. Najczęściej: port 993 dla IMAP, port 465 z SSL/TLS albo 587 ze STARTTLS dla SMTP. ![Rozwinięta karta Ustawienia serwera (IMAP / SMTP) z polami Login, Serwer IMAP, Port IMAP, Serwer SMTP, Port SMTP i Szyfrowanie](https://ritevo.com/docs/integrations/email/pl-advanced.webp) Dane serwera Ritevo podpowiada na podstawie adresu: - **Gmail** - serwery Google, porty 993 i 465, SSL/TLS. - **Outlook, Hotmail, Live** - serwery Microsoft, porty 993 i 587, STARTTLS. - **Każdy inny adres** - `imap.` i `smtp.` z domeny adresu (dla `kontakt@mojsklep.pl` to `imap.mojsklep.pl` i `smtp.mojsklep.pl`), porty 993 i 465, SSL/TLS. > **Warto wiedzieć:** Jeśli Twoja poczta ma inne serwery niż podpowiedź (częste przy hostingu), właściwe dane znajdziesz w panelu hostingu albo w instrukcji dostawcy, w części o konfiguracji programu pocztowego. ## Ustawienia integracji Po podłączeniu integracja jest **Aktywna**, ale pobieranie wiadomości jest **wyłączone** - włączasz je sam. Na stronie integracji znajdziesz: - **Nazwa konta** - Twoja własna nazwa integracji. Możesz ją zmienić w każdej chwili. - **Adres e-mail** - adres podany przy dodawaniu. Nie da się go zmienić; inny adres dodajesz jako nową integrację. - **Pobieranie wiadomości** - po włączeniu Ritevo sprawdza skrzynkę mniej więcej co 10 minut, przy pierwszym pobraniu sięgając 7 dni wstecz. Zasady wspólne: [Pobieranie wiadomości](https://ritevo.com/pl/docs/messages/fetching-messages). - **Ustawienia serwera (IMAP / SMTP)** - te same pola co przy dodawaniu, opisane wyżej. ![Szczegóły integracji e-mail: nazwa konta, adres e-mail, przełącznik Pobieranie wiadomości, ustawienia serwera oraz przyciski Zaktualizuj dane logowania i Zaktualizuj integrację](https://ritevo.com/docs/integrations/email/pl-details.webp) > **Warto wiedzieć:** Zmianę ustawień serwera zapisujesz przyciskiem **Zaktualizuj integrację** - Ritevo najpierw sprawdza nowe dane na serwerze i zapisuje je tylko wtedy, gdy połączenie się uda. Hasło zmieniasz osobno, przyciskiem **Zaktualizuj dane logowania**. ## Jakie maile trafiają do Ritevo Ritevo czyta dwa foldery skrzynki: **odebrane** i **wysłane**. Maile z tej samej korespondencji łączy w jeden wątek, tak jak robi to program pocztowy: - **Wątki** - odpowiedzi są dopinane do rozmowy, której dotyczą. Gdy program pocztowy klienta tego nie oznaczył, Ritevo łączy maile po temacie. - **Wysłane z innych programów** - odpowiedź napisana na przykład z telefonu też pojawi się w wątku, bo trafia do folderu wysłanych. - **Pozostałe foldery** - spam, archiwum i własne foldery nie są pobierane. Mail przeniesiony tam przez regułę pocztową nie trafi do Ritevo. - **Typ wątku** - każdy wątek z e-maila jest **Wiadomością**; poczta nie ma dyskusji ani reklamacji. - **Zamówienia** - wątki z e-maila nie są automatycznie łączone z zamówieniami, nawet jeśli klient podał w treści numer zamówienia. - **Załączniki** - załączniki od klienta widzisz w wątku i pobierasz je z Ritevo. ## Odpowiadanie z Ritevo - **Nadawca** - odpowiedź wychodzi z adresu podłączonej skrzynki, przez jej serwer SMTP. Klient widzi zwykły mail od Ciebie. - **Wątek u klienta** - odpowiedź trafia do tej samej rozmowy w skrzynce klienta, nie jako nowy mail. - **Folder wysłanych** - odpowiedź zapisuje się w folderze wysłanych Twojej skrzynki, więc widzisz ją też w swoim programie pocztowym. ## Wymaga ponownego połączenia Ten stan pojawia się, gdy serwer poczty odrzucił login albo hasło - najczęściej po zmianie hasła do skrzynki albo po usunięciu hasła aplikacji. Na liście integracji taka skrzynka ma czerwoną ramkę i napis **Wymaga ponownego połączenia**. Do czasu podania nowego hasła Ritevo nie pobiera maili i nie wysyła odpowiedzi z tej skrzynki. ![Dwie skrzynki na liście integracji: jedna z czerwoną ramką i napisem Wymaga ponownego połączenia, druga ze statusem Aktywna](https://ritevo.com/docs/integrations/email/pl-status.webp) 1. Jeśli używasz hasła aplikacji, wygeneruj nowe w ustawieniach konta pocztowego. 2. Na stronie integracji w Ritevo kliknij **Zaktualizuj dane logowania**, wpisz hasło i zatwierdź. Ritevo sprawdza je na serwerze tak samo jak przy dodawaniu - złe hasło zwróci błąd, poprawne odświeży połączenie. Ustawienia pobierania i historia zostają bez zmian. > **Warto wiedzieć:** Ponowne połączenie od razu zdejmuje stan **Wymaga ponownego połączenia** i włącza integrację - także wtedy, gdy wcześniej została usunięta. Nie musisz jej osobno przywracać. W API ponowne połączenie ustawia na integracji `authError=false` i `active=true`, także gdy integracja była usunięta (`active=false`). Jaki endpoint to robi w danej integracji, opisuje notatka o unikalności na początku strony. ## Usunięcie integracji **Usuń integrację** wyłącza integrację w Ritevo: przestaje pobierać i wysyłać dane, ale to, co pobrała wcześniej, zostaje. **Przywróć integrację** włącza ją z powrotem. ## Czego integracja nie robi - Nie wysyła nowych maili do klientów z własnej inicjatywy - odpowiadasz w istniejących wątkach. - Nie pobiera maili ze spamu, archiwum ani własnych folderów. - Nie przenosi, nie oznacza i nie usuwa maili w Twojej skrzynce - skrzynka zostaje taka, jaka była. ## Integracja e-mail przez API (dla AI i integratorów) Ta sekcja istnieje tylko w wersji Markdown. Integracja e-mail ma typ `EMAIL` i własny zestaw endpointów pod `/integrations/email`. Każdy zapis, który zmienia dane serwera albo hasło, najpierw łączy się z serwerem poczty (IMAP i SMTP) i przy błędzie zwraca `424`. - `POST /integrations/email` - dodanie skrzynki. Pola: `accountName` (wymagane, do 255 znaków), `email` (wymagane, adres), `username` (opcjonalne - login, gdy inny niż adres), `password` (wymagane, do 1000 znaków), `imapHost`, `imapPort`, `smtpHost`, `smtpPort` (porty 1-65535), `security` (`SSL_TLS` albo `STARTTLS`). `409`, gdy ten adres jest już podłączony. - `GET /integrations/email` i `GET /integrations/email/{integrationId}` - lista i jedna skrzynka. Odpowiedź nie zawiera hasła; ma `active`, `authError` (true = **Wymaga ponownego połączenia**) i `messageConfig.fetchMessages`. - `PATCH /integrations/email/{integrationId}` - zmiana `accountName`, `username` i ustawień serwera (te same pola co przy dodawaniu, bez `email` i `password`). - `PATCH /integrations/email/{integrationId}/credentials` - nowe hasło: `{ "password": "..." }`. Czyści `authError`. - `PATCH /integrations/email/{integrationId}/fetch-messages` - włączenie lub wyłączenie pobierania: `{ "fetchMessages": true }`. - `DELETE /integrations/email/{integrationId}` - **Usuń integrację** (ustawia `active=false`), `PATCH /integrations/email/{integrationId}/restore` - **Przywróć integrację**. - Wątki z e-maila mają `threadType` = `MESSAGE` i nie mają powiązanego zamówienia. Endpointy tej integracji są pod `/integrations/email`. Aktualne ścieżki, pola, typy i kody odpowiedzi są zawsze w Swaggerze: https://api.ritevo.com/api/v1/api-docs. ```json { "accountName": "Sklep - obsługa klienta", "email": "kontakt@mojsklep.pl", "username": null, "password": "haslo-aplikacji", "imapHost": "imap.mojsklep.pl", "imapPort": 993, "smtpHost": "smtp.mojsklep.pl", "smtpPort": 465, "security": "SSL_TLS" } ``` --- Cała pomoc w jednym pliku: https://ritevo.com/llms-full.txt. Mapa pomocy z linkami do wszystkich stron: https://ritevo.com/llms.txt.