Gmail Getting Started: API Access and First Request (2026)

Getting started overview

Integrating with Gmail programmatically primarily involves using the Gmail API, which offers functionalities for managing messages, drafts, labels, and settings. Access to the Gmail API is secured through OAuth 2.0, requiring developers to set up a project within the Google Cloud Console to obtain necessary credentials. This process ensures that applications can access user data only with explicit consent and defined scopes.

The core steps for getting started include establishing a Google Account, enabling the Gmail API for a specific Google Cloud project, configuring OAuth 2.0 client IDs, and implementing an authentication flow within your application. Once authenticated, client libraries or direct RESTful API calls can be used to interact with Gmail services. The API supports various programming languages through official client libraries, streamlining development efforts.

This guide focuses on the initial setup and making a first authenticated API call using Python, a commonly supported language with a well-maintained Google API Client Library. The principles, however, are transferable to other supported languages and SDKs.

Quick reference table

Create an account and get keys

1. Create a Google Account

If you do not already have one, a Google Account is required to access Gmail and the Google Cloud Platform. You can create a new account by following the instructions on the Google Account creation page. This account will serve as your primary identity for Google services.

2. Set up a Google Cloud Project

All interactions with Google APIs, including the Gmail API, are managed through projects in the Google Cloud Console. To create a new project:

1. Navigate to the Google Cloud Console.
2. From the project selector dropdown at the top, select New Project.
3. Enter a project name and click Create.

3. Enable the Gmail API

Once your project is created, you must explicitly enable the Gmail API:

1. In the Google Cloud Console, navigate to the APIs & Services > Library.
2. Search for Gmail API.
3. Select the Gmail API from the results and click Enable.

4. Configure OAuth 2.0 Consent Screen

The OAuth consent screen informs users about your application requesting access to their data. This is a mandatory step before creating OAuth credentials:

1. In the Google Cloud Console, go to APIs & Services > OAuth consent screen.
2. Choose the User Type (e.g., External for most public-facing applications or Internal for Google Workspace organizations).
3. Click Create.
4. Fill in the required fields: App name, User support email, and optionally, Authorized domains.
5. Add any necessary Scopes that your application will require. For a basic read-only access to messages, https://www.googleapis.com/auth/gmail.readonly is a common starting point.
6. Save your changes.

5. Create OAuth 2.0 Credentials

You need to generate a client ID and client secret to allow your application to authenticate with Google's services:

1. In the Google Cloud Console, go to APIs & Services > Credentials.
2. Click Create Credentials > OAuth client ID.
3. Select the Application type that best fits your use case (e.g., Web application or Desktop app).
4. Provide a name for your OAuth client.
5. For web applications, specify Authorized JavaScript origins and Authorized redirect URIs. For desktop applications, no additional URIs are needed.
6. Click Create.
7. Your client ID and client secret will be displayed. Download the JSON file containing these credentials (often named client_secret_YOUR_CLIENT_ID.json) or copy the values. Keep these credentials secure.

Your first request

This section outlines how to make a basic API call using Python. The Google API Client Library for Python simplifies authentication and interaction with the Gmail API. Ensure Python 3 and pip are installed on your system.

1. Install the Google Client Library for Python

Open your terminal or command prompt and run:

pip install google-api-python-client google-auth-oauthlib google-auth-httplib2

2. Save your credentials

Rename the downloaded JSON file containing your client ID and client secret to credentials.json and place it in the same directory as your Python script.

3. Write the Python script

Create a Python file (e.g., gmail_quickstart.py) with the following content. This script will authenticate, request read-only access to your Gmail messages, and then list the labels in your Gmail account.

import os

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError

# If modifying these scopes, delete the file token.json.
SCOPES = ["https://www.googleapis.com/auth/gmail.readonly"]

def main():
    """Shows basic usage of the Gmail API.
    Lists the user's Gmail labels.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists("token.json"):
        creds = Credentials.from_authorized_user_file("token.json", SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                "credentials.json", SCOPES
            )
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open("token.json", "w") as token:
            token.write(creds.to_json())

    try:
        service = build("gmail", "v1", credentials=creds)

        # Call the Gmail API
        results = service.users().labels().list(userId="me").execute()
        labels = results.get("labels", [])

        if not labels:
            print("No labels found.")
            return
        print("Labels:")
        for label in labels:
            print(f"- {label['name']}")

    except HttpError as error:
        # TODO(developer) - Handle errors from gmail API.
        print(f"An error occurred: {error}")


if __name__ == "__main__":
    main()

4. Run the script

Execute the Python script from your terminal:

python gmail_quickstart.py

Upon initial execution, a browser window will open, prompting you to log in with your Google Account and grant permission to your application. After successfully authorizing, the browser will redirect, and the script will automatically retrieve and display your Gmail labels in the console. Subsequent runs will use the saved token.json file for authentication, avoiding the need for re-authorization until the refresh token expires or is revoked.

Common next steps

After successfully making your first API call, consider these next steps to further develop your integration:

• Explore additional API methods: The Gmail API reference documentation details all available endpoints for messages, drafts, attachments, and more.
• Implement message management: Learn to send emails, manage drafts, mark messages as read/unread, and move them between labels or the trash.
• Handle attachments: The API supports downloading and uploading attachments, which is crucial for many email-related applications.
• Manage labels and filters: Programmatically create, modify, or delete labels and apply filters to incoming mail.
• Advanced authentication and authorization: Explore service accounts for server-to-server interactions, or implement incremental authorization for requesting additional scopes as needed. Refer to Google's OAuth 2.0 documentation for advanced patterns.
• Error handling and logging: Implement robust error handling (beyond basic try-except blocks) and logging to monitor your application's interaction with the API.
• Rate limits and quotas: Be aware of the Gmail API usage limits to ensure your application scales correctly and avoids exceeding query per second (QPS) quotas.

Troubleshooting the first call

Encountering issues during the initial setup or API call is common. Here are some troubleshooting tips:

• credentials.json not found: Ensure the credentials.json file downloaded from Google Cloud Console is in the same directory as your Python script and correctly named.
• Invalid credentials or unauthorized client: Double-check that your OAuth 2.0 client ID and secret are correctly copied into the credentials.json file. Verify that the Application type selected when creating credentials matches your use case (e.g., Web application for web apps, Desktop app for local scripts).
• Insufficient scopes: If you receive a 403 Forbidden error, your application might not have the necessary permissions. Review the scopes defined in your script (SCOPES variable) and ensure they are added to your OAuth consent screen in the Google Cloud Console. For example, to send emails, you'd need a scope like https://www.googleapis.com/auth/gmail.send, not just gmail.readonly.
• Redirect URI mismatch: For web applications, ensure that the Authorized redirect URIs configured in your OAuth client ID in the Google Cloud Console exactly match the redirect URI your application uses. Even a trailing slash can cause issues. For desktop apps, the script uses a local server flow, which handles redirects automatically.
• API not enabled: Verify that the Gmail API is enabled for your specific Google Cloud project in the Google Cloud API Library.
• Firewall or network issues: If the browser doesn't open or the script hangs during authentication, check for local firewall rules or network proxies that might be blocking access to Google's authentication servers.
• Expired token.json: If you're encountering issues after repeated runs, delete the token.json file to force a fresh authentication flow. This is especially useful if you changed scopes or credentials.
• Check Google Cloud Logs: For more detailed error information, consult the Cloud Logging section of your Google Cloud project. API errors and authentication failures are often logged there, providing specific error codes and messages.