Gmail API CRUD Operations

Multi-account Gmail management system with full CRUD operations, unified inbox, and attachment handling.

📋 For complete project details, see PROJECT_SUMMARY.md

Overview

• Manage 7 Gmail accounts from one interface
• Unified inbox (see all emails from all accounts together)
• Full CRUD operations with Gmail API
• Email body parsing (plain text + HTML)
• Attachment download capabilities

Setup

1. Install Dependencies with uv

uv pip install -r requirements.txt

Or install packages directly:

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

2. Run the Application

python gmail_crud.py

On first run, it will:

• Open browser for OAuth authentication
• Ask you to authorize the app
• Save credentials to token.json for future use

Features

READ Operations

• list_messages(max_results, query) - List messages from inbox
• get_message(msg_id) - Get full message by ID
• search_messages(query) - Search messages with Gmail query syntax
• get_message_details(msg_id) - Get formatted message details
• get_message_body(msg_id) - Get full email body (plain text and HTML)
• list_attachments(msg_id) - List all attachments in a message
• download_attachment(msg_id, attachment_id, filename, save_dir) - Download single attachment
• download_all_attachments(msg_id, save_dir) - Download all attachments from a message

CREATE Operations

• send_message(to, subject, body, attachments) - Send email with optional attachments

UPDATE Operations

• mark_as_read(msg_ids) - Mark messages as read
• mark_as_unread(msg_ids) - Mark messages as unread
• add_labels(msg_ids, label_ids) - Add labels to messages
• remove_labels(msg_ids, label_ids) - Remove labels from messages

DELETE Operations

• trash_messages(msg_ids) - Move to trash (recoverable)
• delete_messages(msg_ids) - Permanently delete
• untrash_messages(msg_ids) - Restore from trash

Utility

• list_labels() - Get all available labels

Usage Examples

from gmail_crud import GmailCRUD

# Initialize
gmail = GmailCRUD()

# List recent emails
messages = gmail.list_messages(max_results=10)

# Search unread emails
unread = gmail.search_messages('is:unread')

# Read full email body
body = gmail.get_message_body(msg_id)
print(body['plain'])  # Plain text
print(body['html'])   # HTML version

# List and download attachments
attachments = gmail.list_attachments(msg_id)
for att in attachments:
    print(f"{att['filename']} - {att['size']} bytes")

gmail.download_all_attachments(msg_id, save_dir='./downloads')

# Send email
gmail.send_message(
    to='recipient@example.com',
    subject='Test Email',
    body='Hello from Gmail API!',
    attachments=['file.pdf']
)

# Mark as read
gmail.mark_as_read(msg_id)

# Trash message
gmail.trash_messages(msg_id)

Gmail Search Query Examples

• is:unread - Unread messages
• from:example@gmail.com - From specific sender
• subject:invoice - Messages with subject containing "invoice"
• has:attachment - Messages with attachments
• after:2024/01/01 - Messages after date
• is:starred - Starred messages

Files

• gmail_crud.py - Main CRUD implementation
• token.json - OAuth tokens (auto-generated, DO NOT commit)
• client_secret_*.json - OAuth credentials
• cred.txt - Credential reference

Next Steps for Improvement

1. Add email body parsing (HTML/Plain text)
2. Implement draft operations
3. Add attachment download functionality
4. Create CLI interface
5. Add bulk operations
6. Implement rate limiting
7. Add logging
8. Create unit tests