From b584c82647e988933652425c09dfc944d6b566cf Mon Sep 17 00:00:00 2001 From: Danny Roosevelt Date: Thu, 26 Sep 2024 12:00:04 -0700 Subject: [PATCH] readme updates --- components/gmail/README.md | 140 +++++++++++++++++- .../sources/new-email-received/README.md | 138 ----------------- .../new-email-received/new-email-received.mjs | 6 +- 3 files changed, 137 insertions(+), 147 deletions(-) diff --git a/components/gmail/README.md b/components/gmail/README.md index 8b3f60086aa77..f198f4fdaaefd 100644 --- a/components/gmail/README.md +++ b/components/gmail/README.md @@ -1,16 +1,144 @@ # Overview + 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. # Getting Started -To connect your Gmail account to Pipedream, just accept the prompt when connecting your Gmail account. +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. + +## Configuring a Gmail OAuth client in Google Cloud Platform + +To get started, you'll need the following: + +- A Google Cloud account +- Basic familiarity with Google Cloud Console + +## Quickstart + +1. Create a custom Gmail client in Google Cloud Console +2. Enable Gmail API and Pub/Sub API +3. Create OAuth credentials and a service account +4. Set up a custom OAuth client in Pipedream +5. Connect your Gmail account using the custom client and service account + +For detailed instructions, follow the steps below. + +## Detailed Setup Instructions + +### 1. Create a Gmail app + +1. Sign in to the [Google Cloud Console](https://console.cloud.google.com/welcome) +2. Select an existing project, or create a new one + + ![Select an existing project or create a new one in the Google Cloud Console](https://res.cloudinary.com/pipedreamin/image/upload/v1663268100/docs/components/CleanShot_2022-09-15_at_14.54.34_vajyds.png) + +3. Select **APIs & Services** +4. Click **Enable APIs & Services** + + ![Select "Enable APIs & Services to open a menu to enable the Gmail API for Pipedream to connect to](https://res.cloudinary.com/pipedreamin/image/upload/v1663268316/docs/components/CleanShot_2022-09-15_at_14.58.06_jshirk.png) + +5. Search for and select **[Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)** +6. Click **Enable** + + ![Search for and select the Gmail Enterprise API](https://res.cloudinary.com/pipedreamin/image/upload/v1663268442/docs/components/CleanShot_2022-09-15_at_15.00.22_skvwei.gif) + +7. Search for and select **[Cloud Pub/Sub API](https://console.cloud.google.com/apis/library/pubsub.googleapis.com)** +8. Click **Enable** + + ![Search for and select the Cloud Pub/Sub API](https://res.cloudinary.com/dpenc2lit/image/upload/v1724881089/Screenshot_2024-08-28_at_2.36.59_PM_ds4knm.png) + +> **Note:** If you encounter issues with API enablement, ensure you have the necessary permissions in your Google Cloud project. + +### 2. Set up the OAuth consent screen + +1. Click **OAuth consent screen** on the left side + + ![Click "OAuth consent screen" in the left navigation menu](https://res.cloudinary.com/pipedreamin/image/upload/v1663268506/docs/components/CleanShot_2022-09-15_at_15.01.24_wravfb.png) + +2. Set up the OAuth consent screen: + + - Select User Type (Internal for Google Workspace users, External for others) + - Fill in required fields + - Add scopes: `email`, `profile`, `https://www.googleapis.com/auth/gmail.modify`, `https://www.googleapis.com/auth/gmail.settings.basic` + - Add your email as a test user + - Review and complete the setup + + ![Select "External" in the OAuth Consent Screen](https://res.cloudinary.com/pipedreamin/image/upload/v1663268545/docs/components/CleanShot_2022-09-15_at_15.02.22_fiekq1.png) + +### 3. Create OAuth Credentials in Google and Custom OAuth Client in Pipedream + +1. Navigate to the **Credentials** section on the left side. + + ![Open the Credentials menu in the left hand nav bar](https://res.cloudinary.com/pipedreamin/image/upload/v1663269973/docs/components/CleanShot_2022-09-15_at_15.13.52_yvllxi.png) + +2. Click **Create Credentials** at the top and select **OAuth client ID** + + ![Click create credentials to start the process](https://res.cloudinary.com/pipedreamin/image/upload/v1663270014/docs/components/CleanShot_2022-09-15_at_15.14.15_hjulis.png) + + ![Select the OAuth Client ID option](https://res.cloudinary.com/pipedreamin/image/upload/v1663270093/docs/components/CleanShot_2022-09-15_at_15.14.39_juqtnm.png) + +3. Select **Web application** for **Application type** + + ![Web application is the type of OAuth credential we're generating](https://res.cloudinary.com/pipedreamin/image/upload/v1663270117/docs/components/CleanShot_2022-09-15_at_15.14.56_hlseq6.png) + +4. Name the app, e.g. "Pipedream". +5. In a new window, navigate to the [Accounts](https://pipedream.com/accounts) page in **Pipedream**, and click **OAuth Clients**. + + ![Custom OAuth Client creation on Pipedream](https://res.cloudinary.com/dpenc2lit/image/upload/v1724882777/Screenshot_2024-08-28_at_2.53.15_PM_rxtusm.png) + +6. Click **New OAuth Client**, and search for Gmail. +7. Name your OAuth Client, and click **Continue**. +8. Copy the **Redirect URI**, and return to your previous window. +9. On your Google Cloud app configuration page, click **Add URI** and paste the Redirect URI from the previous step. + + ![Add the Pipedream URL to the Callback Redirect URL option](https://res.cloudinary.com/pipedreamin/image/upload/v1663270187/docs/components/CleanShot_2022-09-15_at_15.16.10_hvbocb.png) + +10. Click **Create** to create your new OAuth keys. + + ![Store the Client ID and Client Secret keys](https://res.cloudinary.com/pipedreamin/image/upload/v1663270250/docs/components/CleanShot_2022-09-15_at_15.16.29_hvxnkx.png) + +11. Copy the Client ID and Client Secret, and paste them in your OAuth Client configuration on Pipedream. + + ![Custom OAuth Client creation on Pipedream](https://res.cloudinary.com/dpenc2lit/image/upload/v1724956524/Screenshot_2024-08-29_at_11.34.55_AM_t7tjkh.png) + +> **Important:** When creating the OAuth client ID, make sure to copy the Redirect URI from Pipedream exactly as shown to avoid authentication errors. + +### 4. Create service account + +1. Navigate to **[Credentials](https://console.cloud.google.com/apis/credentials?)** under APIs & Services, and click **Create Credentials** > **Service Account**. + + ![Service Account Creation](https://res.cloudinary.com/dpenc2lit/image/upload/v1724964633/Screenshot_2024-08-29_at_1.44.04_PM_om14xp.png) + +2. Add a name and description for your service account, and grant the service account the role **Pub/Sub Admin**, and click **Done**. + + ![Role administering](https://res.cloudinary.com/dpenc2lit/image/upload/v1724964633/Screenshot_2024-08-29_at_1.47.02_PM_chdjkl.png) + +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. + + ![Create private key](https://res.cloudinary.com/dpenc2lit/image/upload/v1724964634/Screenshot_2024-08-29_at_1.47.34_PM_tmalc7.png) + +### 5. Connect your Gmail account in Pipedream + +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. +2. While configuring the New Email Received trigger, you should be prompted to input your Service Account Key JSON. + +### 6. Publish your custom Gmail app (required for External app type only) + +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. + +1. Navigate to your application, and click **OAuth Consent Screen** on the lefthand sidebar. +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**. +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. +4. The publishing status should be set to **In production**, and your account should maintain its connection without an expiration window. -## What's the difference between the **Gmail** app and the **Gmail Developer App**? +![Publish your application](https://res.cloudinary.com/dpenc2lit/image/upload/v1698166716/Screenshot_2023-10-24_at_9.50.06_AM_lve7wq.png) -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. +![Confirmation of changes](https://res.cloudinary.com/dpenc2lit/image/upload/v1698166716/Screenshot_2023-10-24_at_9.50.18_AM_mndtyc.png) -Currently, the **Gmail** app on Pipedream is limited to only sending emails on behalf of your Gmail email address associated with this app. +# Troubleshooting -However, the **Gmail Developer App** is unrestricted because you have the ability to control the scopes through creating your own Google Cloud Project. +- **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. +- **API Not Enabled**: Ensure both Gmail API and Pub/Sub API are enabled in your Google Cloud project. +- **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. -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). +If you continue to experience issues, please contact Pipedream support for further assistance. diff --git a/components/gmail/sources/new-email-received/README.md b/components/gmail/sources/new-email-received/README.md index 9d96578cc00cf..9e2ae651691ed 100644 --- a/components/gmail/sources/new-email-received/README.md +++ b/components/gmail/sources/new-email-received/README.md @@ -1,141 +1,3 @@ # Overview The Gmail - New Email Received (Instant) source enables you to trigger Pipedream workflows based on real-time changes to your Gmail inbox. - -# Getting Started - -## Prerequisites - -- A Google Cloud account -- A Pipedream account on the Advanced plan or higher -- Basic familiarity with Google Cloud Console - -## Quickstart - -1. Create a custom Gmail client in Google Cloud Console -2. Enable Gmail API and Pub/Sub API -3. Create OAuth credentials and a service account -4. Set up a custom OAuth client in Pipedream -5. Connect your Gmail account using the custom client and service account - -For detailed instructions, follow the steps below. - -## Detailed Setup Instructions - -### 1. Create a Gmail app - -1. Sign in to the [Google Cloud Console](https://console.cloud.google.com/welcome) -2. Select an existing project, or create a new one - - ![Select an existing project or create a new one in the Google Cloud Console](https://res.cloudinary.com/pipedreamin/image/upload/v1663268100/docs/components/CleanShot_2022-09-15_at_14.54.34_vajyds.png) - -3. Select **APIs & Services** -4. Click **Enable APIs & Services** - - ![Select "Enable APIs & Services to open a menu to enable the Gmail API for Pipedream to connect to](https://res.cloudinary.com/pipedreamin/image/upload/v1663268316/docs/components/CleanShot_2022-09-15_at_14.58.06_jshirk.png) - -5. Search for and select **[Gmail API](https://console.cloud.google.com/apis/library/gmail.googleapis.com)** -6. Click **Enable** - - ![Search for and select the Gmail Enterprise API](https://res.cloudinary.com/pipedreamin/image/upload/v1663268442/docs/components/CleanShot_2022-09-15_at_15.00.22_skvwei.gif) - -7. Search for and select **[Cloud Pub/Sub API](https://console.cloud.google.com/apis/library/pubsub.googleapis.com)** -8. Click **Enable** - - ![Search for and select the Cloud Pub/Sub API](https://res.cloudinary.com/dpenc2lit/image/upload/v1724881089/Screenshot_2024-08-28_at_2.36.59_PM_ds4knm.png) - -> **Note:** If you encounter issues with API enablement, ensure you have the necessary permissions in your Google Cloud project. - -### 2. Set up the OAuth consent screen - -1. Click **OAuth consent screen** on the left side - - ![Click "OAuth consent screen" in the left navigation menu](https://res.cloudinary.com/pipedreamin/image/upload/v1663268506/docs/components/CleanShot_2022-09-15_at_15.01.24_wravfb.png) - -2. Set up the OAuth consent screen: - - - Select User Type (Internal for Google Workspace users, External for others) - - Fill in required fields - - Add scopes: `email`, `profile`, `https://www.googleapis.com/auth/gmail.modify`, `https://www.googleapis.com/auth/gmail.settings.basic` - - Add your email as a test user - - Review and complete the setup - - ![Select "External" in the OAuth Consent Screen](https://res.cloudinary.com/pipedreamin/image/upload/v1663268545/docs/components/CleanShot_2022-09-15_at_15.02.22_fiekq1.png) - -### 3. Create OAuth Credentials in Google and Custom OAuth Client in Pipedream - -1. Navigate to the **Credentials** section on the left side. - - ![Open the Credentials menu in the left hand nav bar](https://res.cloudinary.com/pipedreamin/image/upload/v1663269973/docs/components/CleanShot_2022-09-15_at_15.13.52_yvllxi.png) - -2. Click **Create Credentials** at the top and select **OAuth client ID** - - ![Click create credentials to start the process](https://res.cloudinary.com/pipedreamin/image/upload/v1663270014/docs/components/CleanShot_2022-09-15_at_15.14.15_hjulis.png) - - ![Select the OAuth Client ID option](https://res.cloudinary.com/pipedreamin/image/upload/v1663270093/docs/components/CleanShot_2022-09-15_at_15.14.39_juqtnm.png) - -3. Select **Web application** for **Application type** - - ![Web application is the type of OAuth credential we're generating](https://res.cloudinary.com/pipedreamin/image/upload/v1663270117/docs/components/CleanShot_2022-09-15_at_15.14.56_hlseq6.png) - -4. Name the app, e.g. "Pipedream". -5. In a new window, navigate to the [Accounts](https://pipedream.com/accounts) page in **Pipedream**, and click **OAuth Clients**. - - ![Custom OAuth Client creation on Pipedream](https://res.cloudinary.com/dpenc2lit/image/upload/v1724882777/Screenshot_2024-08-28_at_2.53.15_PM_rxtusm.png) - -6. Click **New OAuth Client**, and search for Gmail. -7. Name your OAuth Client, and click **Continue**. -8. Copy the **Redirect URI**, and return to your previous window. -9. On your Google Cloud app configuration page, click **Add URI** and paste the Redirect URI from the previous step. - - ![Add the Pipedream URL to the Callback Redirect URL option](https://res.cloudinary.com/pipedreamin/image/upload/v1663270187/docs/components/CleanShot_2022-09-15_at_15.16.10_hvbocb.png) - -10. Click **Create** to create your new OAuth keys. - - ![Store the Client ID and Client Secret keys](https://res.cloudinary.com/pipedreamin/image/upload/v1663270250/docs/components/CleanShot_2022-09-15_at_15.16.29_hvxnkx.png) - -11. Copy the Client ID and Client Secret, and paste them in your OAuth Client configuration on Pipedream. - - ![Custom OAuth Client creation on Pipedream](https://res.cloudinary.com/dpenc2lit/image/upload/v1724956524/Screenshot_2024-08-29_at_11.34.55_AM_t7tjkh.png) - -> **Important:** When creating the OAuth client ID, make sure to copy the Redirect URI from Pipedream exactly as shown to avoid authentication errors. - -### 4. Create service account - -1. Navigate to **[Credentials](https://console.cloud.google.com/apis/credentials?)** under APIs & Services, and click **Create Credentials** > **Service Account**. - - ![Service Account Creation](https://res.cloudinary.com/dpenc2lit/image/upload/v1724964633/Screenshot_2024-08-29_at_1.44.04_PM_om14xp.png) - -2. Add a name and description for your service account, and grant the service account the role **Pub/Sub Admin**, and click **Done**. - - ![Role administering](https://res.cloudinary.com/dpenc2lit/image/upload/v1724964633/Screenshot_2024-08-29_at_1.47.02_PM_chdjkl.png) - -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. - - ![Create private key](https://res.cloudinary.com/dpenc2lit/image/upload/v1724964634/Screenshot_2024-08-29_at_1.47.34_PM_tmalc7.png) - -### 5. Connect your Gmail account in Pipedream - -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. -2. While configuring the New Email Received trigger, you should be prompted to input your Service Account Key JSON. - -### 6. Publish your custom Gmail app (required for External app type only) - -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. - -1. Navigate to your application, and click **OAuth Consent Screen** on the lefthand sidebar. -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**. -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. -4. The publishing status should be set to **In production**, and your account should maintain its connection without an expiration window. - -![Publish your application](https://res.cloudinary.com/dpenc2lit/image/upload/v1698166716/Screenshot_2023-10-24_at_9.50.06_AM_lve7wq.png) - -![Confirmation of changes](https://res.cloudinary.com/dpenc2lit/image/upload/v1698166716/Screenshot_2023-10-24_at_9.50.18_AM_mndtyc.png) - -# Troubleshooting - -- **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. -- **API Not Enabled**: Ensure both Gmail API and Pub/Sub API are enabled in your Google Cloud project. -- **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. - -If you continue to experience issues, please contact Pipedream support for further assistance. diff --git a/components/gmail/sources/new-email-received/new-email-received.mjs b/components/gmail/sources/new-email-received/new-email-received.mjs index f422dce4c5d6f..bf7aa815181cf 100644 --- a/components/gmail/sources/new-email-received/new-email-received.mjs +++ b/components/gmail/sources/new-email-received/new-email-received.mjs @@ -15,7 +15,7 @@ export default { name: "New Email Received", description: "Emit new event when a new email is received.", type: "source", - version: "0.1.3", + version: "0.1.4", dedupe: "unique", props: { gmail, @@ -28,7 +28,7 @@ export default { "polling", ], description: - "Configuring this source as a `webhook` (instant) trigger requires a custom OAuth client. [Refer to the guide here to get started](https://pipedream.com/apps/gmail/triggers/new-email-received#getting-started).", + "Configuring this source as a `webhook` (instant) trigger requires a custom OAuth client. [Refer to the guide here to get started](https://pipedream.com/apps/gmail/#getting-started).", reloadProps: true, }, serviceAccountKeyJson: { @@ -117,7 +117,7 @@ export default { const isValidClientId = await this.checkClientId(); if (!isValidClientId) { throw new ConfigurationError( - "Configuring this source as a `webhook` (instant) trigger requires a custom OAuth client. [Refer to the guide here to get started](https://pipedream.com/apps/gmail/triggers/new-email-received#getting-started).", + "Configuring this source as a `webhook` (instant) trigger requires a custom OAuth client. [Refer to the guide here to get started](https://pipedream.com/apps/gmail/#getting-started).", ); }