|
1 | 1 | # Overview |
| 2 | + |
2 | 3 | By connecting your personal Gmail account to Pipedream, you'll be able to incorporate email into whatever you're building with any of the thousands of apps that are available on Pipedream. |
3 | 4 |
|
4 | 5 | # Getting Started |
5 | 6 |
|
6 | | -To connect your Gmail account to Pipedream, just accept the prompt when connecting your Gmail account. |
| 7 | +To connect your Gmail account to Pipedream, just accept the prompt when connecting your Gmail account. To connect your account with your own OAuth client, see below. |
| 8 | + |
| 9 | +## Configuring a Gmail OAuth client in Google Cloud Platform |
| 10 | + |
| 11 | +To get started, you'll need the following: |
| 12 | + |
| 13 | +- A Google Cloud account |
| 14 | +- Basic familiarity with Google Cloud Console |
| 15 | + |
| 16 | +## Quickstart |
| 17 | + |
| 18 | +1. Create a custom Gmail client in Google Cloud Console |
| 19 | +2. Enable Gmail API and Pub/Sub API |
| 20 | +3. Create OAuth credentials and a service account |
| 21 | +4. Set up a custom OAuth client in Pipedream |
| 22 | +5. Connect your Gmail account using the custom client and service account |
| 23 | + |
| 24 | +For detailed instructions, follow the steps below. |
| 25 | + |
| 26 | +## Detailed Setup Instructions |
| 27 | + |
| 28 | +### 1. Create a Gmail app |
| 29 | + |
| 30 | +1. Sign in to the [Google Cloud Console](https://console.cloud.google.com/welcome) |
| 31 | +2. Select an existing project, or create a new one |
| 32 | + |
| 33 | +  |
| 34 | + |
| 35 | +3. Select **APIs & Services** |
| 36 | +4. Click **Enable APIs & Services** |
| 37 | + |
| 38 | +  |
| 39 | + |
| 40 | +5. Search for and select **[Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)** |
| 41 | +6. Click **Enable** |
| 42 | + |
| 43 | +  |
| 44 | + |
| 45 | +7. Search for and select **[Cloud Pub/Sub API](https://console.cloud.google.com/apis/library/pubsub.googleapis.com)** |
| 46 | +8. Click **Enable** |
| 47 | + |
| 48 | +  |
| 49 | + |
| 50 | +> **Note:** If you encounter issues with API enablement, ensure you have the necessary permissions in your Google Cloud project. |
| 51 | +
|
| 52 | +### 2. Set up the OAuth consent screen |
| 53 | + |
| 54 | +1. Click **OAuth consent screen** on the left side |
| 55 | + |
| 56 | +  |
| 57 | + |
| 58 | +2. Set up the OAuth consent screen: |
| 59 | + |
| 60 | + - Select User Type (Internal for Google Workspace users, External for others) |
| 61 | + - Fill in required fields |
| 62 | + - Add scopes: `email`, `profile`, `https://www.googleapis.com/auth/gmail.modify`, `https://www.googleapis.com/auth/gmail.settings.basic` |
| 63 | + - Add your email as a test user |
| 64 | + - Review and complete the setup |
| 65 | + |
| 66 | +  |
| 67 | + |
| 68 | +### 3. Create OAuth Credentials in Google and Custom OAuth Client in Pipedream |
| 69 | + |
| 70 | +1. Navigate to the **Credentials** section on the left side. |
| 71 | + |
| 72 | +  |
| 73 | + |
| 74 | +2. Click **Create Credentials** at the top and select **OAuth client ID** |
| 75 | + |
| 76 | +  |
| 77 | + |
| 78 | +  |
| 79 | + |
| 80 | +3. Select **Web application** for **Application type** |
| 81 | + |
| 82 | +  |
| 83 | + |
| 84 | +4. Name the app, e.g. "Pipedream". |
| 85 | +5. In a new window, navigate to the [Accounts](https://pipedream.com/accounts) page in **Pipedream**, and click **OAuth Clients**. |
| 86 | + |
| 87 | +  |
| 88 | + |
| 89 | +6. Click **New OAuth Client**, and search for Gmail. |
| 90 | +7. Name your OAuth Client, and click **Continue**. |
| 91 | +8. Copy the **Redirect URI**, and return to your previous window. |
| 92 | +9. On your Google Cloud app configuration page, click **Add URI** and paste the Redirect URI from the previous step. |
| 93 | + |
| 94 | +  |
| 95 | + |
| 96 | +10. Click **Create** to create your new OAuth keys. |
| 97 | + |
| 98 | +  |
| 99 | + |
| 100 | +11. Copy the Client ID and Client Secret, and paste them in your OAuth Client configuration on Pipedream. |
| 101 | + |
| 102 | +  |
| 103 | + |
| 104 | +> **Important:** When creating the OAuth client ID, make sure to copy the Redirect URI from Pipedream exactly as shown to avoid authentication errors. |
| 105 | +
|
| 106 | +### 4. Create service account |
| 107 | + |
| 108 | +1. Navigate to **[Credentials](https://console.cloud.google.com/apis/credentials?)** under APIs & Services, and click **Create Credentials** > **Service Account**. |
| 109 | + |
| 110 | +  |
| 111 | + |
| 112 | +2. Add a name and description for your service account, and grant the service account the role **Pub/Sub Admin**, and click **Done**. |
| 113 | + |
| 114 | +  |
| 115 | + |
| 116 | +3. Click on the service account that you created, and click **Keys** > **Add Key** > **Create New Key** > **JSON**. This will download the service account JSON credentials to your computer. Be sure to save this securely. |
| 117 | + |
| 118 | +  |
| 119 | + |
| 120 | +### 5. Connect your Gmail account in Pipedream |
| 121 | + |
| 122 | +1. From the Pipedream Accounts page, click **OAuth Clients**. Next to your newly created Gmail client, click the three-dot menu on the righthand side and click **Connect Account**. Or you can also connect your account from the workflow builder, when configuring the Gmail trigger. |
| 123 | +2. While configuring the New Email Received trigger, you should be prompted to input your Service Account Key JSON. |
| 124 | + |
| 125 | +### 6. Publish your custom Gmail app (required for External app type only) |
| 126 | + |
| 127 | +Google has a [7 day expiration window](https://developers.google.com/identity/protocols/oauth2#:~:text=A%20Google%20Cloud,Connect%20equivalents) on refresh tokens for **External** applications with a publishing status of "Testing", so you will need to **Publish** your application in order to maintain your account connection. |
| 128 | + |
| 129 | +1. Navigate to your application, and click **OAuth Consent Screen** on the lefthand sidebar. |
| 130 | +2. Under **Publishing status**, click **Publish App**. If you included any sensitive or restricted scopes in your app, there will be a disclosure stating that you will need to go through the process of verification. Click **Confirm**. |
| 131 | +3. Your application will not be available externally unless you share your **client_id** with others, and you will not have to go through the verification process unless you intend to onboard over 100 users. |
| 132 | +4. The publishing status should be set to **In production**, and your account should maintain its connection without an expiration window. |
7 | 133 |
|
8 | | -## What's the difference between the **Gmail** app and the **Gmail Developer App**? |
| 134 | + |
9 | 135 |
|
10 | | -Google requires integration platforms such as Pipedream, to restrict the scopes users can enable for Gmail, in order to regulate the ability of users to build workflows and connect applications. |
| 136 | + |
11 | 137 |
|
12 | | -Currently, the **Gmail** app on Pipedream is limited to only sending emails on behalf of your Gmail email address associated with this app. |
| 138 | +# Troubleshooting |
13 | 139 |
|
14 | | -However, the **Gmail Developer App** is unrestricted because you have the ability to control the scopes through creating your own Google Cloud Project. |
| 140 | +- **Authentication Failed**: Double-check that your Redirect URI is correct and that you've added your email as a test user in the OAuth consent screen. |
| 141 | +- **API Not Enabled**: Ensure both Gmail API and Pub/Sub API are enabled in your Google Cloud project. |
| 142 | +- **Service Account Issues**: Verify that your service account has the "Pub/Sub Admin" role and that you've correctly pasted the JSON key into Pipedream. |
15 | 143 |
|
16 | | -Because you can define your own scopes, you can read and write emails with your own Google Cloud Project. To learn how to create and authenticate a **Gmail Developer App** read [our setup guide](https://pipedream.com/apps/gmail-custom-oauth). |
| 144 | +If you continue to experience issues, please contact Pipedream support for further assistance. |
0 commit comments