Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | ## How do I set up custom Google OAuth credentials for Gmail? |
| 2 | |
| 3 | Use your own Google OAuth app when you want your app's name on Google's consent screen, a dedicated API quota, or scopes that Composio's managed app doesn't cover. |
| 4 | |
| 5 | ### Create the Google OAuth app |
| 6 | |
| 7 | 1. Open the [Google Cloud console](https://console.cloud.google.com/) and select the project that will own the OAuth app, or create one. |
| 8 | |
| 9 |  |
| 10 | |
| 11 | 2. Go to **APIs & Services** → **Library**, search for **Gmail API**, and click **Enable**. If the API page shows **Manage**, the API is already enabled. Enabling an API needs project permissions; ask your project admin if you can't. |
| 12 | |
| 13 |  |
| 14 | |
| 15 | 3. Go to **Google Auth Platform** → **Branding**. If you see **Get started**, enter the app name, user support email, and developer contact email, then save. |
| 16 | |
| 17 |  |
| 18 | |
| 19 | 4. Under **Audience**, choose the user type. **Internal** limits sign-in to accounts in your Google Workspace organization. **External** allows any Google account. An External app starts in **Testing**; add every account that will connect under **Test users**. |
| 20 | |
| 21 |  |
| 22 | |
| 23 | 5. Under **Data Access**, click **Add or remove scopes** and add the scopes your auth config will request (see **Scopes** below). Paste any scope missing from the list under **Manually add scopes** and click **Add to table**. Click **Update**, then **Save**. |
| 24 | |
| 25 |  |
| 26 | |
| 27 | 6. Under **Clients**, click **Create client**. Set **Application type** to **Web application**, name the client, and add this URI under **Authorized redirect URIs**: |
| 28 | |
| 29 | ``` |
| 30 | https://backend.composio.dev/api/v1/auth-apps/add |
| 31 | ``` |
| 32 | |
| 33 | It must exactly match the `oauth_redirect_uri` field of your Composio auth config. |
| 34 | |
| 35 |  |
| 36 | |
| 37 |  |
| 38 | |
| 39 | 7. Click **Create**. Copy the **Client ID** and **Client secret** before you close the dialog, and store the secret privately. |
| 40 | |
| 41 |  |
| 42 | |
| 43 | ### Create the auth config in Composio |
| 44 | |
| 45 | 1. In the [Composio dashboard](https://dashboard.composio.dev/~/project/auth-configs?utm_source=docs&utm_medium=content&utm_campaign=toolkits-gmail), go to **Auth Configs** → **Create** and select **Gmail**. Enter a config name and click **Next**. |
| 46 | |
| 47 |  |
| 48 | |
| 49 |  |
| 50 | |
| 51 |  |
| 52 | |
| 53 | 2. Choose **OAuth 2.0** and **Your Own Credentials**. Paste the **Client ID** and **Client secret**, and leave **Redirect URI** set to `https://backend.composio.dev/api/v1/auth-apps/add`. |
| 54 | |
| 55 |  |
| 56 | |
| 57 | 3. Choose the scopes your tools need, matching the ones you added under **Data Access**, then click **Create Auth Config**. |
| 58 | 4. Click **Connect Account**, sign in with a Google account that can use the app (a test user while the app is in **Testing**), and approve the consent screen. Under **Accounts**, confirm the connection shows **Active**. |
| 59 | |
| 60 |  |
| 61 | |
| 62 |  |
| 63 | |
| 64 |  |
| 65 | |
| 66 | For the general flow, see [custom auth configs](/docs/auth-configuration/custom-auth-configs). |
| 67 | |
| 68 | ### Scopes |
| 69 | |
| 70 | The default Gmail auth config requests `https://mail.google.com/` (full mailbox access), `userinfo.email`, `userinfo.profile`, and People API read scopes such as `contacts.readonly`, `contacts.other.readonly`, and `user.emails.read`. Request only what your tools need. For example, `gmail.readonly` reads messages and settings but can't send or modify mail. See Google's [Gmail scope reference](https://developers.google.com/workspace/gmail/api/auth/scopes). |
| 71 | |
| 72 | Short scope names on this page leave out the `https://www.googleapis.com/auth/` prefix. When you paste a scope under **Manually add scopes**, use the full URL, for example `https://www.googleapis.com/auth/userinfo.email`. Scopes already written as a full URL, such as `https://mail.google.com/`, go in as shown. |
| 73 | |
| 74 | If you change the scopes later, reconnect the account so the user grants the new access. |
| 75 | |
| 76 | ### Testing, publishing, and verification |
| 77 | |
| 78 | - While an External app is in **Testing**, only test users can connect, and Google can show them an unverified-app notice. Google generally expires their authorizations after seven days, so they need to reconnect. |
| 79 | - To let any Google account connect, publish the app under **Audience**. Publishing doesn't verify the app. |
| 80 | - Public apps that request sensitive or restricted scopes generally need Google's OAuth verification. Check **Google Auth Platform** → **Verification Center**. Internal apps and apps in Testing can be exempt. See Google's [verification requirements](https://developers.google.com/identity/protocols/oauth2/production-readiness/overview). |
| 81 | - `https://mail.google.com/` and `gmail.readonly` are restricted scopes. A public app that requests them needs restricted-scope verification, which can include a security assessment if your servers store or transmit Gmail data. |
| 82 | - If Google blocks sign-in, check the app's audience, the test user list, the requested scopes, and your Workspace admin's app access policy. |
| 83 | |
| 84 | ## Why am I seeing "App is blocked" when connecting Gmail? |
| 85 | |
| 86 | Google can block consent when the OAuth client requests scopes that Google hasn't approved for that client. This can happen after you add scopes beyond the defaults. |
| 87 | |
| 88 | Follow [Google scope approvals and blocked-app troubleshooting](/docs/authentication/controlling-scopes#google-scope-approvals). Toolkit defaults and scope recommendations don't establish the managed app's approved scopes. If you need your own OAuth app, see [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) and the setup steps above. |
| 89 | |
| 90 | ## Why am I getting "Gmail API has not been used in project" error? |
| 91 | |
| 92 | When using custom OAuth credentials, the Gmail API must be enabled in the Google Cloud project that owns those credentials. Enable it in Google Cloud Console under APIs & Services, wait a few minutes, and retry. |
| 93 | |
| 94 | ## Why am I getting "Error 400: invalid_scope"? |
| 95 | |
| 96 | The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs). |
| 97 | |
| 98 | ## Why does the OAuth consent screen show "Composio" instead of my app? |
| 99 | |
| 100 | By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps). |
| 101 | |
| 102 | ## Why am I getting 401 errors on tool calls? |
| 103 | |
| 104 | The user's access token is no longer valid. Common causes: the user revoked access, changed their password or 2FA, a Workspace admin policy changed, or Google's refresh token limit (~50 per account) was exceeded. Re-authenticating the user typically resolves this. |
| 105 | |
| 106 | ## Why is my Gmail trigger slow? |
| 107 | |
| 108 | Your trigger is probably polling. Gmail triggers use webhooks on Composio-managed auth, so events arrive in seconds, but a trigger polls when: |
| 109 | |
| 110 | - It was created as a polling trigger. Composio doesn't move existing triggers to webhooks; delete the trigger and create it again. |
| 111 | - You passed `type: "poll"` when you created it. |
| 112 | - Your own OAuth app has no complete Gmail webhook endpoint yet. See the next question. |
| 113 | |
| 114 | A polling trigger waits up to its `polling_interval` between checks. [List the trigger](/docs/setting-up-triggers/managing-triggers#listing-active-triggers) and read its `type` and `fallback_reason` to see which case applies. |
| 115 | |
| 116 | ## How do I set up Gmail webhooks with my own OAuth app? |
| 117 | |
| 118 | Gmail delivers mailbox changes through Google Cloud Pub/Sub. Set it up once per OAuth app, in the Google Cloud project that owns your OAuth client: |
| 119 | |
| 120 | 1. Enable the Gmail API and the Cloud Pub/Sub API. |
| 121 | 2. Create a Pub/Sub topic. Its full name is `projects/<project-id>/topics/<topic-id>`. On the topic, grant `gmail-api-push@system.gserviceaccount.com` the Pub/Sub Publisher role (`roles/pubsub.publisher`). |
| 122 | 3. Create a service account only for push deliveries, for example `composio-gmail-push`. Give it no roles and create no keys: Pub/Sub uses it only to sign each push. |
| 123 | 4. [Create a Gmail webhook endpoint](/docs/setting-up-triggers/custom-oauth-webhooks) with your OAuth client ID, and note its `webhook_url`. |
| 124 | 5. Create a push subscription on the topic. Set its endpoint URL to the `webhook_url`, turn on authentication with the service account, and set the audience to the same `webhook_url`. Leave payload unwrapping off, and set the subscription to never expire. |
| 125 | 6. Share your Pub/Sub details with Composio by [updating the endpoint](/docs/setting-up-triggers/custom-oauth-webhooks#updating-an-endpoint), a `PATCH` or `composio.webhooks.endpoints.update()` in the SDKs. Set `topic_name` to the topic's full name, `push_service_account_email` to the service account's email, and `push_audience` to the `webhook_url`. |
| 126 | |
| 127 | Until the endpoint has all three fields, new Gmail triggers poll, and their `fallback_reason` says what's missing. Once it does, new triggers you create without `type` use the webhook straight away. That's why the fields come last, after the push subscription is delivering. |
| 128 | |
| 129 | If pushes don't arrive, check that Pub/Sub's service agent, `service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com`, can sign tokens for the service account. If it can't, grant it the Service Account Token Creator role on that account. Google documents its side in [Gmail push notifications](https://developers.google.com/workspace/gmail/api/guides/push). |
| 130 | |
| 131 | ## Why am I getting "Quota Exhausted" or "rate limit exhausted"? |
| 132 | |
| 133 | Google enforces per-minute and daily request quotas. If you're using Composio's default OAuth app, you share that quota with other users, which can cause limits to be hit faster. Use your own OAuth app credentials to get a dedicated quota, and add exponential backoff and retries to handle transient rate limits. |
| 134 | |
| 135 | ## How do I send an email with an attachment? |
| 136 | |
| 137 | Use a [session](/docs/quickstart) so your agent discovers the email tool at runtime instead of hard-coding an action slug. |
| 138 | |
| 139 | 1. [Connect Gmail for your user](/docs/authentication/manually-authenticating), then create a session for the same user and give your agent the session tools. |
| 140 | 2. Upload `./report.pdf` to that session with the experimental `session.experimental.files` API. See [sandbox files and mounts](/docs/sandbox/remote#files-and-mounts) for Python, TypeScript, and API examples. The agent can read the uploaded file in the remote sandbox, not from your application's local filesystem. |
| 141 | 3. Ask the agent to send the email with your recipient, subject, body, and the uploaded file's sandbox path. For a file mounted at `/mnt/files/report.pdf`, instruct it to use the sandbox's `get_mount_file_s3_key("report.pdf")` helper and pass the returned key to the discovered email tool in a file object with `name`, `mimetype`, and `s3key`. A sandbox path is not a storage key. See [session files and toolkit attachments](/kb/guide/mcp-tool-router-files). |
| 142 | 4. Check the tool result before reporting that the email was sent. If the tool fails, report the error. |
| 143 | |
| 144 | Automatic file upload is off by default. This workflow uploads the file explicitly and does not require enabling automatic file handling. The session files API is experimental and may change. |
| 145 | |
| 146 | ## Why can Gmail filter setup show an app-blocked error? |
| 147 | |
| 148 | If a user on Composio-managed Gmail auth hits Google's "app is blocked" / unverified-app screen after adding `gmail.settings.basic`, use your own Google OAuth app verified for `https://www.googleapis.com/auth/gmail.settings.basic`, then reconnect. |
| 149 | |
| 150 | ## When should I avoid `gmail.metadata` when fetching full Gmail email content? |
| 151 | |
| 152 | Use `https://www.googleapis.com/auth/gmail.metadata` only when the app needs message metadata such as labels and headers, not message bodies or payload content. Gmail treats `gmail.metadata` as a restricted metadata-only scope, and it is not compatible with broader content-access scopes such as `gmail.readonly`, `gmail.modify`, or `mail.google.com` in the same OAuth request. |
| 153 | |
| 154 | If a tool needs full email content, remove `gmail.metadata` from the auth config and request a Gmail scope that allows message content access. Then reconnect the account so the new scope set is granted. |