# SMTP Google Mail Integration

#### Google Mail Integration

---

#### 1. Google App Passwords

**⚠️ Constraints**: **It is only supported for accounts with 2-Step Verification enabled.**

Google App Passwords are intended to provide limited access to less secure apps or legacy systems that cannot use OAuth 2.0 — primarily for Google services that use basic username/password authentication.\
**⚠️ Note**: Google strongly recommends using OAuth 2.0 for authentication instead of App Passwords. Some access types (e.g., less secure apps) are already blocked unless explicitly allowed.

Service can use **App Passwords**:\
**SMTP**: smtp.gmail.com\
**IMAP**: imap.gmail.com\
**POP3**: pop.gmail.com

Create an app password: [Google App Password Link](https://myaccount.google.com/apppasswords)

```
Username: your_email@gmail.com
Password: [your generated app password]
```

---

#### 2. Google Mail OAuth 2.0

**Google Mail** through **SMTP**/**IMAP** requires **OAuth 2.0** ([OAuth Wikipedia Link](https://en.wikipedia.org/wiki/OAuth)) for authentication. This is part of Google’s effort to enhance security by deprecating less secure app access (basic authentication using just a username and password). OAuth 2.0 offers a more secure, token-based system that supports modern features like multi-factor authentication, granular permission scopes, and token expiration for better protection against credential theft. For technical implementation details, see Google’s documentation here : [Google IMAP-SMTP Link](https://developers.google.com/gmail/imap/imap-smtp).

---

**⚠️ Proxy Configuration:** If your server accesses the internet through a proxy, make sure to whitelist the following domains for Google Mail Authentication: **oauth2.googleapis.com**

---

Start by navigating to Google APIs & Services: [Google APIs & Services Link](https://console.developers.google.com/projectselector/apis/credentials)\
**⚠️ Important:** Ensure sure the **GMAIL API** is enabled at **Enabled APIs & services**. [Google API Library Link](https://console.cloud.google.com/apis/library)

![G api services](SMTP-Google-Mail-Integration/g_api_services.png)

![Gmail api enabled](SMTP-Google-Mail-Integration/gmail_api_enabled.png)

Go to the **Credentials** menu, click on **Create Credentials**, and select **OAuth client ID**:

![Create credentials](SMTP-Google-Mail-Integration/create_credentials.png)

• Select the application type: **Web application**.\
• Provide a unique name to identify your OAuth client (e.g., CrushFTP Integration).\
Then configure the following:\
• **Authorized JavaScript origins**: Add the base URL of your CrushFTP server (e.g., https<!-- -->://your-domain.com).\
• **Authorized redirect URIs**: This is the URL Google will redirect to after successful authorization. The Redirect URL must end with: **?command=register_google_mail_api**

```
http://127.0.0.1:9090/?command=register_google_mail_api
or
https://your.crushftp.domain.com/?command=register_google_mail_api
```

Finally, click the **Create** button.

![Credential config](SMTP-Google-Mail-Integration/credential_config.png)

After the credentials are created, copy the **Client ID** and **Client Secret**.

![Client id secret](SMTP-Google-Mail-Integration/client_id_secret.png)

**⚠️ Note:** You can configure the **OAuth consent screen** by clicking the link above the **Authorized JavaScript origins** section:\
"The domains you enter in the fields below will be automatically added to your **OAuth consent screen** as **authorized domains**."\
Click the link to open the **OAuth consent screen** settings, complete the configuration, and authorize your **CrushFTP domain.**\
**Important**: After configuration, don’t forget to click **Publish App** at **Audience** page to make it active. Without publishing, the app will remain in **Testing** mode, which restricts access to authorized test users only.

---

#### 3. SMTP Settings

Navigate to **Server Admin** -> **Preferences** -> [General Settings](General-Settings.md) -> **SMTP Settings**:

![Smtp config](SMTP-Google-Mail-Integration/smtp_config.png)

**SMTP Server Used for Emailing**: Enter the SMTP server address used for sending emails, such as **smtp.gmail.com**, using the default port **587**.

```
    smtp.gmail.com:587
```

**SMTP Server Username, Password**:

---

**a.)** App passwords: [1. Google App Passwords Link](SMTP-Google-Mail-Integration.md#section-SMTP+Google+Mail+Integration-1.GoogleAppPasswords)

```
SMTP Server Username: your_email@gmail.com
SMTP Server Password: [your generated app password]
```

---

**b.)** OAtuth 2.0: [2. Google Mail OAuth 2.0 Link](SMTP-Google-Mail-Integration.md#section-SMTP+Google+Mail+Integration-2.GoogleMailOAuth2.0) If the SMTP server address ends with **gmail.com**, the corresponding **Get Refresh Token** button will appear. Click that button to proceed.\
**⚠️ Important**: To obtain the **Refresh Token**, the CrushFTP WebInterface’s host and port must match the **Redirect URL** specified in the **Google APIs & Services**-> **Credentials** -> **OAuth 2.0 Client IDs**. In our example, it was: http<!-- -->://127.0.0.1:9090 or https<!-- -->://your.crushftp.domain.com/

Enter the **Client ID** , **Client Secret**. Proceed with the authentication and authorization process.\
**⚠️ Important**: Be sure to sign in with the **Google Account** that has the **necessary permissions**, as configured in the **Google APIs & Services**-> **Credentials** -> **OAuth 2.0 Client IDs**. This will automatically configure the **SMTP Server Username** and **SMTP Server Password**.

![Oauth form](SMTP-Google-Mail-Integration/oauth_form.png)

If the domain is unverified, a warning message may appear. Click **Advanced** and choose to proceed:

![Not verified domain](SMTP-Google-Mail-Integration/not_verified_domain.png)

Click on the **Allow** button:

![Allow form](SMTP-Google-Mail-Integration/allow_form.png)

**From email address**: You must also specify the **From** email address.\
**⚠️ Imnportant** The **From** address must exactly match **the signed-in Google user’s email address** (i.e., the account used to obtain the refresh token) or the account associated with the App Password. Otherwise, SMTP authentication will fail.

Make sure to enable the **SSL/TLS** flag to ensure a secure connection.

---

#### 4. PopImapTask

Select the **IMAPS** protocol.\
See the description: [Google IMAP-SMTP Link](https://developers.google.com/gmail/imap/imap-smtp)

![Pop imap task](SMTP-Google-Mail-Integration/pop_imap_task.png)

**Host:**

```
    imap.gmail.com
```

**Port**: **993**\
If the **Host** contains **gmail.com**, the corresponding **Get Refresh Token** button will appear.

**Mail Username, Password**:

---

**a.)** App passwords: ⚠️ Constraints: It is only supported for accounts with 2-Step Verification enabled. [1. Google App Passwords Link](SMTP-Google-Mail-Integration.md#section-SMTP+Google+Mail+Integration-1.GoogleAppPasswords)

```
Mail Username: your_email@gmail.com
Mail Password: [your generated app password]
```

---

**b.)** OAtuth 2.0: Configure the [2. Google Mail OAuth 2.0 Link](SMTP-Google-Mail-Integration.md#section-SMTP+Google+Mail+Integration-2.GoogleMailOAuth2.0)\
**⚠️ Important**: To obtain the Refresh Token, the CrushFTP WebInterface’s host and port must match the **Redirect URL** specified in the **Google APIs & Services**-> **Credentials** -> **OAuth 2.0 Client IDs**. In our example, it was: http<!-- -->://127.0.0.1:9090 or https<!-- -->://your.crushftp.domain.com/

Enter the **Client ID** , **Client Secret**. Proceed with the authentication and authorization process.\
**⚠️ Important**: Be sure to sign in with the **Google Account** that has the **necessary permissions**, as configured in the **Google APIs & Services**-> **Credentials** -> **OAuth 2.0 Client IDs**. This will automatically configure the PopImapTask's **Mail Username** and **Mail Password**.

![Oauth form](SMTP-Google-Mail-Integration/oauth_form.png)

If the domain is unverified, a warning message may appear. Click **Advanced** and choose to proceed:

![Not verified domain](SMTP-Google-Mail-Integration/not_verified_domain.png)

Click on the **Allow** button:

![Allow form](SMTP-Google-Mail-Integration/allow_form.png)

**⚠️ Important:** Since the email address is required after obtaining the refresh token, the Mail Username field must be adjusted.\
Enter your email address followed by a tilde (~) at the beginning of the Mail Username field.

```
Mail Username : <<your email address>>~<<what was before>> 
```

---

For more information, see the general POP/IMAP Task description: [POP/IMAP Task – CrushFTP Documentation Link](CrushTask.md#section-CrushTask-POP3IMAP)

---
