Connect FreeScout to Google Workspace

Make sure that your FreeScout uses HTTPS protocol, otherwise you may be unable to connect it to Google Workspace as it requires Authorized redirect URI. You can change protocol in your FreeScout via APP_URL parameter in the .env file and after that configure HTTPS on your server (see Installation Guide).

Sending and fetching emails works via the same Google Cloud Console OAuth client (you don't need to create two different OAuth clients). Instructions on how to create and configure the OAuth client are provided below in "Fetching Emails" section.

Keep in mind that invitations to users are sent not on behalf of some mailbox but using global "System Emails" settings under "Manage > Mail Settings". And System Emails can't be sent via OAuth - use some SMTP server with login/password authentication.

Here are "Sending Emails" connection details:

• Protocol: SMTP
• Server: smtp.gmail.com
• Port: 465
• Encryption: SSL

1. Enable IMAP in Google Workspace.

   • Login to Google Admin Console under any of your Google Workspace administrators.
   • Navigate to Apps > Google Workspace > Gmail.
   • On the End User Access page, ensure that the option Enable IMAP access for all users is set to On. If it is set to Off, you can select the Edit button on the right side and change the value. Note: If you don't want to enable IMAP for everyone for security reasons, you can utilize Organizational Units (OU) to apply different policy settings to different groups of users. For example, you can create an OU called IMAP Users, place users there, then select this OU on the left side of the configuration page to override the global policy

2. Create a Project in Google Cloud Console.

   • Go to the Google Cloud Console.

   • Sign in with the Google Workspace account that will own the project. It can be any of your Google Workspace administrators.

   • Click "Select a project" button at the top of the page and select "New Project" . Give it a name and click "Create".

   • Again click "Select a project" button at the top of the page, select the Organization (if not selected) and select newly created project.

3. Configure the OAuth Consent Screen.

   • In your new project, navigate to APIs & Services > OAuth consent screen using the left-hand menu.
   • Click Get started button, enter App Information and click Next button:
   • Select "Internal" on the "Audience" step.
   • Enter email address on "Contact Information" step and finish the process.

4. Configure OAuth client in Google Workspace.

   • Click Create OAuth client button on "OAuth Overview" page and enter the following data:
   • In Authorized redirect URIs click "ADD URI" and enter https://yourdomain.com/mailbox/oauth (make sure to change the domain to yours).
   • In the "OAuth client created" window copy "Client ID" and paste in FreeScout into Username field in "Fetching Emails" for the mailbox. Copy "Client secret" and paste into the Password field in FreeScout.

Client Secret can be also found in the newly created OAuth Client in "Client secrets" section.

5. Add Required Scopes.

   • Go the "Data Access" in the left menu and click Add or remove scopes
   • In the "Manually add scopes" field at the bottom enter https://mail.google.com/ and click "Add to table". This scope is required for full IMAP, POP, and SMTP access to a user's mailbox.
   • Click "Update", then "Save".

6. Enable the Gmail API (to use OAuth with IMAP, the Gmail API must be enabled for your project).

   • Go to the Welcome page of Google Cloud (https://console.cloud.google.com/welcome) and make sure you are logged in as Google Workspace administrator.
   • Go to APIs & Services > Library.
   • Search for "Gmail API" and select it.
   • Click the Enable button.

7. In "Fetching Emails" section in FreeScout enter connection details and save settings:

• Protocol: IMAP
• Server: imap.gmail.com
• Port: 993
• Encryption: SSL

8. Click "Connect" next to "Google Workspace" in FreeScout and authenticate under the user corresponding to the email address your are using for the mailbox in FreeScout ("Connect" button appears only after you enter Username and Password). Make sure to authenticate in Google Workspace under mailbox user! Otherwise you will be getting "Invalid credentials (Failure) / status:400" error

If needed you can specify email address in the Username fields for Fetching and Sending like this:

test@example.org:123-456-789 (where 123-456-789 - OAuth Client ID)

If you need to debug the process of fetching emails via IMAP & OAuth, add APP_DEBUG=true to the .env file and clear cache. After that run the following console command which will show the process of interaction between FreeScout and MS365 IMAP server:

php artisan freescout:fetch-emails

After that you can also connect via console directly to the Google Workspace IMAP server and pass obtained from php artisan freescout:fetch-emails instructions:

openssl s_client -crlf -connect imap.gmail.com:993

It means you've connected to Google Workspace OAuth via Google Workspace user whose email is different from mailbox's email address.

Sometimes Google can ban your server's IP address - see this issue. In this case contact Google support.