# E-mail E-mail integration with Ritevo: connecting an IMAP/SMTP mailbox, app passwords, fetching emails as threads and replying to customers from Ritevo. The e-mail integration connects an ordinary mailbox to Ritevo - a company mailbox, Gmail, Outlook or any other that supports IMAP and SMTP. Customer emails land in the shared **Messages** inbox next to marketplace and store conversations, and you reply to them from Ritevo. Through e-mail you also cover sales channels with no inbox of their own - such an integration's page says so. > **Required integration:** You need an e-mail address, the mailbox password (or an app password) and a mailbox that allows IMAP and SMTP connections. One mailbox is connected once; if you handle several addresses, add each one as a separate integration. Within one company account a given address can be connected only once: when you or a colleague add it again, the existing integration is refreshed - even if it was deleted before - and no second one is created. The new password and server settings replace the previous ones. Uniqueness: the integration is unique within the company by `email` and the type `EMAIL`. Creating it again refreshes the existing integration instead of adding a new one: it sets `authError=false` right away, and `active=true` if the integration was inactive. You can also send new credentials with `PATCH /integrations/email/{integrationId}/credentials` - in any state of the integration, also when `authError=false` and `active=true`; it sets `authError=false` and `active=true`. ## App password Some mail providers do not let external programs in with your ordinary sign-in password. You then generate an **app password** in the mail account settings and give that one to Ritevo: - **Gmail** - you create an app password in your Google account settings, under security. It requires 2-step verification. - **Outlook, Yahoo, iCloud** - the same idea: an app password in the account's security settings. - **Company mail at a hosting provider** - the ordinary mailbox password usually works. ## Connecting the account Start in Ritevo: 1. Go to **Integrations** in the left panel and click **Add integration** in the top right corner. 2. In the **E-mail** section pick the **Email** tile. 3. In the **Account name** field enter your own name for the integration, for example "Customer service". 4. In the **E-mail address** field enter the mailbox address. Ritevo fills in the server details from it right away - see below. 5. In the **Password** field enter the mailbox password or an app password. 6. Click **Add integration**. Ritevo connects to the mail server right away - separately for receiving (IMAP) and sending (SMTP). If both connections work, the integration is added and its settings open. If not - you will see the error returned by the server and nothing is saved. ![The integrations list in Ritevo with the Add integration button in the top right corner framed](https://ritevo.com/docs/integrations/en-integrations-list.webp) ![The Add integration screen with the E-mail filter selected and the Email tile framed](https://ritevo.com/docs/integrations/email/en-catalogue.webp) ![The e-mail add-integration screen with the Account name, E-mail address and Password fields, the app password note and the Show advanced settings button](https://ritevo.com/docs/integrations/email/en-add.webp) ## Server settings (IMAP / SMTP) The server settings sit under **Show advanced settings**. Usually you leave them alone - open them when adding the integration fails: - **Login (optional)** - leave it empty if you sign in with the e-mail address. Fill it in only when the server needs a different login. - **IMAP server (receiving)** and **IMAP port** - where Ritevo fetches emails from. - **SMTP server (sending)** and **SMTP port** - the server Ritevo sends your replies through. - **Encryption** - **SSL/TLS** or **STARTTLS**. Most often: port 993 for IMAP, port 465 with SSL/TLS or 587 with STARTTLS for SMTP. ![The expanded Server settings (IMAP / SMTP) card with the Login, IMAP server, IMAP port, SMTP server, SMTP port and Encryption fields](https://ritevo.com/docs/integrations/email/en-advanced.webp) Ritevo suggests the server details from the address: - **Gmail** - Google's servers, ports 993 and 465, SSL/TLS. - **Outlook, Hotmail, Live** - Microsoft's servers, ports 993 and 587, STARTTLS. - **Any other address** - `imap.` and `smtp.` on the address's domain (for `contact@mystore.com` that is `imap.mystore.com` and `smtp.mystore.com`), ports 993 and 465, SSL/TLS. > **Good to know:** If your mail uses different servers than suggested (common with hosting), you will find the right details in the hosting panel or in the provider's guide, in the part about setting up a mail client. ## Integration settings After connecting, the integration is **Active**, but message fetching is **off** - you turn it on yourself. On the integration page you will find: - **Account name** - your own name for the integration. You can change it at any time. - **E-mail address** - the address given when adding. It cannot be changed; a different address is added as a new integration. - **Fetch messages** - once on, Ritevo checks the mailbox about every 10 minutes, reaching 7 days back on the first fetch. Shared rules: [Fetching messages](https://ritevo.com/en/docs/messages/fetching-messages). - **Server settings (IMAP / SMTP)** - the same fields as when adding, described above. ![E-mail integration details: the account name, e-mail address, the Fetch messages switch, the server settings and the Update credentials and Update integration buttons](https://ritevo.com/docs/integrations/email/en-details.webp) > **Good to know:** You save server setting changes with **Update integration** - Ritevo first checks the new details with the server and saves them only if the connection works. You change the password separately, with **Update credentials**. ## Which emails land in Ritevo Ritevo reads two folders of the mailbox: **inbox** and **sent**. Emails from the same correspondence are joined into one thread, the way a mail client does it: - **Threads** - replies are attached to the conversation they belong to. When the customer's mail client did not mark that, Ritevo joins emails by subject. - **Sent from other programs** - a reply written, say, on your phone shows up in the thread too, because it lands in the sent folder. - **Other folders** - spam, archive and your own folders are not fetched. An email moved there by a mail rule will not reach Ritevo. - **Thread type** - every e-mail thread is a **Message**; e-mail has no disputes or claims. - **Orders** - e-mail threads are not linked to orders automatically, even if the customer wrote the order number in the text. - **Attachments** - you see the customer's attachments in the thread and download them from Ritevo. ## Replying from Ritevo - **Sender** - the reply goes out from the connected mailbox's address, through its SMTP server. The customer sees an ordinary email from you. - **Thread on the customer's side** - the reply lands in the same conversation in the customer's mailbox, not as a new email. - **Sent folder** - the reply is saved to your mailbox's sent folder, so you also see it in your mail client. ## Reconnection required This state appears when the mail server rejected the login or password - most often after the mailbox password changed or an app password was removed. On the integrations list such a mailbox has a red frame and **Reconnection required**. Until you provide a new password, Ritevo neither fetches emails nor sends replies from that mailbox. ![Two mailboxes on the integrations list: one with a red frame and Reconnection required, the other with the Active status](https://ritevo.com/docs/integrations/email/en-status.webp) 1. If you use an app password, generate a new one in the mail account settings. 2. On the integration page in Ritevo click **Update credentials**, enter the password and confirm. Ritevo checks it with the server just like when adding - a wrong password returns an error, a valid one refreshes the connection. The fetching settings and history stay unchanged. > **Good to know:** Reconnecting clears the **Reconnection required** state straight away and turns the integration on - also when it was deleted earlier. You do not need to restore it separately. In the API, reconnecting sets `authError=false` and `active=true` on the integration, also when it was deleted (`active=false`). Which endpoint does it for a given integration is described in the uniqueness note at the top of the page. ## Deleting the integration **Delete integration** turns the integration off in Ritevo: it stops fetching and sending data, but what it fetched earlier stays. **Restore integration** turns it back on. ## What the integration does not do - It does not send new emails to customers on its own - you reply in existing threads. - It does not fetch emails from spam, archive or your own folders. - It does not move, flag or delete emails in your mailbox - the mailbox stays as it was. ## The e-mail integration through the API (for AI and integrators) This section exists only in the Markdown version. The e-mail integration has the type `EMAIL` and its own endpoints under `/integrations/email`. Every write that changes the server details or the password first connects to the mail server (IMAP and SMTP) and returns `424` on failure. - `POST /integrations/email` - adds a mailbox. Fields: `accountName` (required, up to 255 characters), `email` (required, an address), `username` (optional - the login when it differs from the address), `password` (required, up to 1000 characters), `imapHost`, `imapPort`, `smtpHost`, `smtpPort` (ports 1-65535), `security` (`SSL_TLS` or `STARTTLS`). `409` when this address is already connected. - `GET /integrations/email` and `GET /integrations/email/{integrationId}` - the list and one mailbox. The response has no password; it has `active`, `authError` (true = **Reconnection required**) and `messageConfig.fetchMessages`. - `PATCH /integrations/email/{integrationId}` - changes `accountName`, `username` and the server settings (the same fields as when adding, without `email` and `password`). - `PATCH /integrations/email/{integrationId}/credentials` - a new password: `{ "password": "..." }`. Clears `authError`. - `PATCH /integrations/email/{integrationId}/fetch-messages` - turns fetching on or off: `{ "fetchMessages": true }`. - `DELETE /integrations/email/{integrationId}` - **Delete integration** (sets `active=false`), `PATCH /integrations/email/{integrationId}/restore` - **Restore integration**. - E-mail threads have `threadType` = `MESSAGE` and no linked order. This integration's endpoints are under `/integrations/email`. The current paths, fields, types and response codes are always in Swagger: 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" } ``` --- All help in one file: https://ritevo.com/llms-full.txt. Help map with links to every page: https://ritevo.com/llms.txt.