gmail-enhanced

# Gmail Enhanced Advanced Gmail integration with powerful automation features. ## Features ### 1. Advanced Search - Complex query building (AND, OR, NOT) - Date range filters - Attachment filters - Label filters - Search within attachments ### 2. Label Management - Create, rename, delete labels - Nested labels (folders) - Color customization - Label statistics ### 3. Attachment Handling - Download attachments - Upload and send attachments - Filter attachments by type/size - Extract attachments to cloud storage ### 4. Email Processing - Auto-categorize emails - Extract data from emails - Auto-reply rules - Email templates - Bounce detection ### 5. Email Parsing - Extract structured data - Parse invoices, receipts - Extract contact info - HTML parsing ## Prerequisites 1. Enable Gmail API in Google Cloud Console 2. Create OAuth 2.0 credentials 3. Download credentials.json 4. Generate tokens.json (run once with authentication) ## Configuration ```bash export GMAIL_CREDENTIALS_PATH="/path/to/credentials.json" export GMAIL_TOKEN_PATH="/path/to/tokens.json" ``` Or place credentials in default locations: - `~/.credentials/gmail-credentials.json` - `~/.credentials/gmail-token.json` ## Usage ### Send Email ```python from gmail_enhanced import GmailClient gmail = GmailClient() # Simple email gmail.send( to="recipient@example.com", subject="Hello", body="Email content" ) # With attachment gmail.send( to="recipient@example.com", subject="Report", body="Please find the report attached", attachments=["report.pdf"] ) ``` ### Advanced Search ```python # Complex queries results = gmail.search( query="from:boss@company.com", label="INBOX", after="2024/01/01", has_attachments=True ) # Search with OR results = gmail.search_or([ "subject:urgent", "label:important" ]) ``` ### Label Management ```python # Create label label = gmail.create_label("Projects/Work/Q1", color="#4A90E2") # Get label stats stats = gmail.get_label_stats("INBOX") # Apply labels gmail.add_labels(["Label1", "Label2"], message_ids) ``` ### Attachment Handling ```python # Download attachments from search results attachments = gmail.search_attachments( query="subject:invoice", save_dir="./downloads" ) # Upload attachment gmail.send( to="recipient@example.com", subject="File", attachments=["/path/to/file.pdf"] ) ``` ### Auto-categorization ```python # Create rule gmail.add_rule( name="Categorize invoices", query="subject:invoice has:attachment", add_labels=["Processed/Invoices"] ) # Run rules gmail.process_rules() ``` ## API Reference ### Core Methods | Method | Description | |--------|-------------| | `send(to, subject, body, attachments, cc, bcc)` | Send email | | `search(query, max_results, label)` | Search emails | | `get_message(msg_id, format)` | Get email details | | `delete_message(msg_id)` | Move to trash | | `archive_message(msg_id)` | Archive email | ### Label Methods | Method | Description | |--------|-------------| | `create_label(name, color)` | Create label | | `rename_label(old_name, new_name)` | Rename label | | `delete_label(name)` | Delete label | | `get_labels()` | List all labels | | `get_label_stats(label)` | Get label statistics | ### Attachment Methods | Method | Description | |--------|-------------| | `download_attachment(msg_id, attachment_id, save_path)` | Download attachment | | `search_attachments(query, save_dir)` | Search and download | | `get_attachment_info(msg_id)` | List attachments | ### Automation Methods | Method | Description | |--------|-------------| | `add_rule(name, query, actions)` | Create processing rule | | `process_rules()` | Run all rules | | `create_template(name, subject, body)` | Create email template | | `send_template(template_name, to, variables)` | Send using template | ### Parsing Methods | Method | Description | |--------|-------------| | `parse_email(msg_id)` | Extract structured data | | `extract_invoice(msg_id)` | Parse invoice data | | `extract_contacts(msg_id)` | Extract email addresses | ## Email Query Syntax ``` Basic: from:user@example.com to:user@example.com subject:keyword "exact phrase" Filters: after:2024/01/01 before:2024/12/31 older_than:7d newer_than:2h Flags: has:attachment has:drive is:unread is:starred is:important Labels: label:INBOX label:Work Combinations: from:boss AND subject:urgent (from:alice OR from:bob) AND is:unread ``` ## Error Handling Common errors: - `invalid_credentials`: Re-authenticate - `rate_limit`: Wait and retry - `not_found`: Message ID invalid - `permission_denied`: Check scopes ## Scopes Required ``` https://www.googleapis.com/auth/gmail.readonly https://www.googleapis.com/auth/gmail.send https://www.googleapis.com/auth/gmail.labels https://www.googleapis.com/auth/gmail.modify ``` ## Links - [Gmail API Documentation](https://developers.google.com/gmail/api) - [Google Cloud Console](https://console.cloud.google.com) - [OAuth Setup Guide](https://developers.google.com/gmail/api/quickstart/python)