gmail-api-client 0.1.0__tar.gz

gmail_api_client-0.1.0/PKG-INFO

@@ -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.