gmail-api-client 0.1.0__py3-none-any.whl

gmail_api_client/__init__.py

@@ -0,0 +1,15 @@
+from .client import GmailClient
+from .exceptions import (
+    GmailAPIError,
+    GmailAuthenticationError,
+    GmailDraftError,
+    GmailSendError,
+)
+
+__all__ = [
+    "GmailClient",
+    "GmailAPIError",
+    "GmailAuthenticationError",
+    "GmailDraftError",
+    "GmailSendError",
+]

gmail_api_client/client.py

@@ -0,0 +1,176 @@
+import base64
+import os
+from email.message import EmailMessage
+from typing import Optional
+
+from google.auth.transport.requests import Request
+from google.oauth2.credentials import Credentials
+from google_auth_oauthlib.flow import InstalledAppFlow
+from googleapiclient.discovery import Resource, build
+from googleapiclient.errors import HttpError
+
+from .exceptions import (
+    GmailAuthenticationError,
+    GmailDraftError,
+    GmailSendError,
+)
+
+
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.compose"
+]
+
+
+class GmailClient:
+    """Client for interacting with the Gmail API."""
+
+    def __init__(
+        self,
+        credentials_path: str = "credentials.json",
+        token_path: str = "token.json",
+    ):
+        self.credentials_path = credentials_path
+        self.token_path = token_path
+        self.service = self._authenticate()
+
+    def _authenticate(self) -> Resource:
+        """Authenticate the user and create Gmail API service."""
+
+        creds: Optional[Credentials] = None
+
+        try:
+            if os.path.exists(self.token_path):
+                creds = Credentials.from_authorized_user_file(
+                    self.token_path,
+                    SCOPES,
+                )
+
+            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(
+                        self.credentials_path,
+                        SCOPES,
+                    )
+
+                    creds = flow.run_local_server(port=0)
+
+                with open(self.token_path, "w") as token:
+                    token.write(creds.to_json())
+
+            return build(
+                "gmail",
+                "v1",
+                credentials=creds,
+            )
+
+        except Exception as error:
+            raise GmailAuthenticationError(
+                f"Failed to authenticate with Gmail: {error}"
+            ) from error
+
+    @staticmethod
+    def _create_message(
+        to: str,
+        subject: str,
+        body: str,
+        sender: Optional[str] = None,
+    ) -> EmailMessage:
+        """Create an email message."""
+
+        message = EmailMessage()
+
+        message.set_content(body)
+
+        if sender:
+            message["From"] = sender
+
+        message["To"] = to
+        message["Subject"] = subject
+
+        return message
+
+    @staticmethod
+    def _encode_message(message: EmailMessage) -> str:
+        """Encode an email for the Gmail API."""
+
+        return base64.urlsafe_b64encode(
+            message.as_bytes()
+        ).decode()
+
+    def create_draft(
+        self,
+        to: str,
+        subject: str,
+        body: str,
+        sender: Optional[str] = None,
+    ):
+        """Create a Gmail draft."""
+
+        try:
+            message = self._create_message(
+                to=to,
+                subject=subject,
+                body=body,
+                sender=sender,
+            )
+
+            encoded_message = self._encode_message(message)
+
+            return (
+                self.service.users()
+                .drafts()
+                .create(
+                    userId="me",
+                    body={
+                        "message": {
+                            "raw": encoded_message,
+                        }
+                    },
+                )
+                .execute()
+            )
+
+        except HttpError as error:
+            raise GmailDraftError(
+                f"Failed to create Gmail draft: {error}"
+            ) from error
+
+    def send_mail(
+        self,
+        to: str,
+        subject: str,
+        body: str,
+        sender: Optional[str] = None,
+    ):
+        """Send an email through Gmail."""
+
+        try:
+            message = self._create_message(
+                to=to,
+                subject=subject,
+                body=body,
+                sender=sender,
+            )
+
+            encoded_message = self._encode_message(message)
+
+            return (
+                self.service.users()
+                .messages()
+                .send(
+                    userId="me",
+                    body={
+                        "raw": encoded_message,
+                    },
+                )
+                .execute()
+            )
+
+        except HttpError as error:
+            raise GmailSendError(
+                f"Failed to send Gmail message: {error}"
+            ) from error

gmail_api_client/exceptions.py

@@ -0,0 +1,14 @@
+class GmailAPIError(Exception):
+    """Base exception for all Gmail API client errors."""
+
+
+class GmailAuthenticationError(GmailAPIError):
+    """Raised when Gmail authentication fails."""
+
+
+class GmailDraftError(GmailAPIError):
+    """Raised when creating a Gmail draft fails."""
+
+
+class GmailSendError(GmailAPIError):
+    """Raised when sending an email fails."""

gmail_api_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,523 @@
+Metadata-Version: 2.4
+Name: gmail-api-client
+Version: 0.1.0
+Summary: A simple Python client for Gmail API automation
+Author: Asheesh Singh
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: google-api-python-client>=2.0.0
+Requires-Dist: google-auth-httplib2>=0.2.0
+Requires-Dist: google-auth-oauthlib>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+
+# Gmail API Automation
+
+A simple Python project for interacting with Gmail using the **Gmail API** and **OAuth 2.0**.
+
+This project supports:
+
+* Creating Gmail drafts
+* Sending emails
+* OAuth 2.0 authentication
+* Reusing authenticated credentials through `token.json`
+* Programmatic email composition using Python's `EmailMessage`
+
+---
+
+## Features
+
+### Create Drafts
+
+Create a Gmail draft programmatically:
+
+```python
+gmail_create_draft(
+    to="recipient@example.com",
+    subject="Automated draft",
+    body="This is an automated draft."
+)
+```
+
+### Send Emails
+
+Send an email directly through Gmail:
+
+```python
+gmail_send_mail(
+    to="recipient@example.com",
+    subject="Automated email",
+    body="This email was sent using the Gmail API."
+)
+```
+
+---
+
+## Architecture
+
+```text
+Python Application
+       │
+       ▼
+OAuth 2.0 Authentication
+       │
+       ▼
+   Gmail API
+       │
+       ├── Create Draft
+       │
+       └── Send Email
+```
+
+The application uses Google's OAuth 2.0 flow for a local desktop application.
+
+```text
+credentials.json
+       │
+       ▼
+Google OAuth Login
+       │
+       ▼
+   token.json
+       │
+       ▼
+Gmail API Client
+```
+
+---
+
+## Tech Stack
+
+* Python 3
+* Gmail API
+* Google OAuth 2.0
+* `google-api-python-client`
+* `google-auth`
+* `google-auth-oauthlib`
+
+---
+
+## Project Structure
+
+```text
+gmail/
+│
+├── main.py
+├── credentials.json
+├── token.json
+├── .gitignore
+└── README.md
+```
+
+### Files
+
+| File               | Description                                           |
+| ------------------ | ----------------------------------------------------- |
+| `main.py`          | Gmail API implementation                              |
+| `credentials.json` | OAuth client credentials downloaded from Google Cloud |
+| `token.json`       | Generated OAuth access/refresh token                  |
+| `.gitignore`       | Prevents credentials from being committed             |
+| `README.md`        | Project documentation                                 |
+
+---
+
+# Setup
+
+## 1. Create a Google Cloud Project
+
+Go to the [Google Cloud Console](https://console.cloud.google.com/).
+
+Create a new project or use an existing project.
+
+---
+
+## 2. Enable Gmail API
+
+Open the API Library and enable:
+
+**Gmail API**
+
+You can also enable it using the Google Cloud CLI:
+
+```bash
+gcloud services enable gmail.googleapis.com
+```
+
+---
+
+## 3. Configure OAuth Consent Screen
+
+In Google Cloud Console:
+
+```text
+Google Auth Platform
+        ↓
+Branding
+        ↓
+Configure OAuth consent screen
+```
+
+Configure the application information.
+
+For a personal/local application, you can use the appropriate testing configuration.
+
+Add your Gmail account as a test user if the application is in testing mode.
+
+---
+
+## 4. Create OAuth Client
+
+Go to:
+
+```text
+Google Auth Platform
+        ↓
+Clients
+        ↓
+Create Client
+```
+
+Select:
+
+```text
+Application type: Desktop app
+```
+
+Download the generated credentials file.
+
+Rename it:
+
+```text
+credentials.json
+```
+
+Place it in the project root:
+
+```text
+gmail/
+├── main.py
+├── credentials.json
+└── README.md
+```
+
+---
+
+# Installation
+
+Create a virtual environment:
+
+```bash
+python -m venv .venv
+```
+
+Activate it.
+
+### macOS / Linux
+
+```bash
+source .venv/bin/activate
+```
+
+### Windows
+
+```bash
+.venv\Scripts\activate
+```
+
+Install dependencies:
+
+```bash
+pip install -U \
+    google-api-python-client \
+    google-auth-httplib2 \
+    google-auth-oauthlib
+```
+
+---
+
+# Gmail OAuth Scope
+
+The application uses:
+
+```python
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.compose"
+]
+```
+
+The `gmail.compose` scope allows the application to:
+
+* Create drafts
+* Read/write draft content
+* Send messages
+
+The application does not request full Gmail access when it isn't required.
+
+---
+
+# Authentication
+
+The first time you run:
+
+```bash
+python main.py
+```
+
+Google will open a browser window.
+
+Sign in with the Gmail account you want the application to use and grant the requested Gmail permissions.
+
+After successful authentication, the application creates:
+
+```text
+token.json
+```
+
+The token is reused on subsequent executions.
+
+You normally won't need to authenticate again unless the token is revoked or the requested scopes change.
+
+---
+
+# Important: Changing OAuth Scopes
+
+If you change:
+
+```python
+SCOPES = [...]
+```
+
+delete the existing token:
+
+```bash
+rm token.json
+```
+
+Then run:
+
+```bash
+python main.py
+```
+
+Google will request authorization again with the new scopes.
+
+---
+
+# Creating a Draft
+
+Example:
+
+```python
+gmail_create_draft(
+    to="recipient@example.com",
+    subject="Automated Draft",
+    body="This is an automated draft."
+)
+```
+
+The Gmail API returns a draft object containing the draft ID and associated message information.
+
+Example output:
+
+```text
+Draft created successfully.
+Draft ID: r123456789
+```
+
+The draft will appear in the Gmail **Drafts** folder.
+
+---
+
+# Sending an Email
+
+Example:
+
+```python
+gmail_send_mail(
+    to="recipient@example.com",
+    subject="Automated Email",
+    body="This email was sent using the Gmail API."
+)
+```
+
+Example output:
+
+```text
+Email sent successfully.
+Message ID: 18abc123456
+```
+
+The message will be sent directly through the authenticated Gmail account.
+
+---
+
+# Example
+
+```python
+from main import gmail_create_draft, gmail_send_mail
+
+
+# Create a draft
+gmail_create_draft(
+    to="recipient@example.com",
+    subject="Test Draft",
+    body="This is a test draft."
+)
+
+
+# Send an email
+gmail_send_mail(
+    to="recipient@example.com",
+    subject="Test Email",
+    body="This is a test email."
+)
+```
+
+---
+
+# Security
+
+**Never commit your OAuth credentials to Git.**
+
+Add the following to `.gitignore`:
+
+```gitignore
+credentials.json
+token.json
+.venv/
+__pycache__/
+*.pyc
+.env
+```
+
+Your `.gitignore` should look like:
+
+```gitignore
+# Google OAuth credentials
+credentials.json
+token.json
+
+# Python
+.venv/
+__pycache__/
+*.pyc
+
+# Environment variables
+.env
+
+# macOS
+.DS_Store
+```
+
+If credentials are accidentally committed to a public repository, revoke them immediately from Google Cloud and generate new credentials.
+
+---
+
+# Troubleshooting
+
+## 403: Insufficient Authentication Scopes
+
+If you see:
+
+```text
+HttpError 403
+Request had insufficient authentication scopes
+```
+
+delete the existing token:
+
+```bash
+rm token.json
+```
+
+Then authenticate again:
+
+```bash
+python main.py
+```
+
+Make sure the required scope is present:
+
+```python
+SCOPES = [
+    "https://www.googleapis.com/auth/gmail.compose"
+]
+```
+
+---
+
+## 403: Gmail API Has Not Been Used
+
+If you see:
+
+```text
+Gmail API has not been used in project ... before
+or it is disabled
+```
+
+enable Gmail API for the Google Cloud project associated with your OAuth credentials:
+
+```bash
+gcloud services enable gmail.googleapis.com
+```
+
+You can also enable it from the Google Cloud Console.
+
+After enabling the API, wait a few minutes and run:
+
+```bash
+python main.py
+```
+
+again.
+
+---
+
+## Invalid Credentials
+
+If you see an OAuth/client configuration error, verify that:
+
+```text
+credentials.json
+```
+
+is present in the project root and was downloaded from the correct Google Cloud project.
+
+---
+
+# Future Improvements
+
+Possible extensions for this project:
+
+* HTML email support
+* CC and BCC
+* File attachments
+* Inline images
+* Reply to an existing email
+* Reply within an existing Gmail thread
+* Forward emails
+* Search Gmail messages
+* Read emails
+* Manage labels
+* Delete drafts
+* Schedule email workflows
+* Email templates
+* CLI interface
+* FastAPI service around Gmail operations
+* AI-powered email generation
+
+---
+
+# References
+
+* [Gmail API](https://developers.google.com/workspace/gmail/api)
+* [Gmail API Python Quickstart](https://developers.google.com/workspace/gmail/api/quickstart/python)
+* [Google OAuth 2.0](https://developers.google.com/identity/protocols/oauth2)
+* [Google Cloud Console](https://console.cloud.google.com/)
+
+---
+
+## License
+
+This project is for educational and personal automation purposes.

gmail_api_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+gmail_api_client/__init__.py,sha256=judvXF5iFEiv3_rOQE_3REDFlKfYG1gi75om7He5wnk,281
+gmail_api_client/client.py,sha256=hq0hfYdumTKyOpYeOUSJyF6KN56yUs3CPWaoPHDxtJg,4475
+gmail_api_client/exceptions.py,sha256=TogvdqGHjpUgQY46TJ3uSNb5lv5w4fOraga8A1omM3M,365
+gmail_api_client-0.1.0.dist-info/METADATA,sha256=LDYlNyOalhAV5gDAy3ICB72wNEp5o3IOSXB581DV7xY,8380
+gmail_api_client-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+gmail_api_client-0.1.0.dist-info/top_level.txt,sha256=hKd0VtNHuyjchIQnXC2s1-y7oC-vCmtjvsqIxPSydWA,17
+gmail_api_client-0.1.0.dist-info/RECORD,,

gmail_api_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

gmail_api_client-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+gmail_api_client