onedevcommonmsgraph 1.0.3

Biblioteca para integração com Microsoft Graph API

OnedevCommon MS Graph

Python library for Microsoft Graph API integration, focused on sending and analyzing emails for shared mailboxes.

📋 Overview

This library offers complete functionality for:

• ✉️ Email sending via Microsoft Graph API
• 📧 Email reading from shared mailboxes
• 📊 Advanced email analysis with multiple configuration options
• 💾 Automatic saving of results in JSON format

🗂️ Project Structure

onedev-common-ms-graph/
├── onedevcommonmsgraph/
│   ├── __init__.py              # Package initialization
│   ├── email_.py                # 📤 Email sending
│   ├── email_reader.py          # 📥 Email reading (core)
│   ├── email_analyzer.py        # 📊 Advanced email analysis
│   └── logs/
│       └── .gitkeep            # Keeps folder in repository
├── setup.py                    # Installation configuration
├── pyproject.toml              # Project metadata
└── README.md                   # This documentation

📁 File Description

📤 email_.py - Email Sending

Function: Sends emails via Microsoft Graph API to shared mailboxes.

Features:

• Automatic authentication with Azure AD
• Support for multiple recipients (TO, CC, BCC)
• Attachment sending
• Priority and importance configuration
• HTML and plain text formatting

Main usage:

from onedevcommonmsgraph.email_ import EmailSender
sender = EmailSender(tenant_id, client_id, client_secret, from_email)
sender.send_email(to=["[e-mail]"], subject="Subject", body="Content")

---

📥 email_reader.py - Email Reading (Core)

Function: Simplified base class for reading emails via Microsoft Graph API.

Main methods:

• list_emails(limit, filter_query) - Lists emails with filters
• read_detailed_email(email_id) - Reads specific email with complete details
• list_unread_emails() - Lists only unread emails
• list_emails_period(days) - Lists emails from a specific period
• mark_as_read(email_id) - Marks email as read

Main usage:

from onedevcommonmsgraph.email_reader import EmailReader
reader = EmailReader(tenant_id, client_id, client_secret, email_box)
emails = reader.list_emails(limit=10)

---

📊 email_analyzer.py - Advanced Email Analysis

Function: Configurable and advanced email analysis with automatic JSON saving.

Supported Email Types:

• 'all' - All emails
• 'latest' - Latest N emails
• 'unread' - Only unread emails
• 'period' - Emails from a specific period
• 'by_sender' - Emails from specific sender
• 'by_subject' - Emails with term in subject

Information Types Extracted:

• 'all' - All available information
• 'basic' - Basic information (ID, subject, sender, date)
• 'status' - Email status (read/unread, attachments)
• 'senders' - Only sender information
• 'content' - Email content
• 'attachments' - Attachment information
• 'summary' - Executive summary
• [custom list] - Specific fields defined by user

Features:

• 🎯 Flexible configuration - Combine any email type with any information type
• 📊 Automatic statistics - Read rate, top senders, emails with attachments
• 💾 Automatic saving - JSON files with unique timestamp in logs/
• 📈 Progress reports - Real-time processing tracking
• 🔧 Custom fields - Extract only the information you need

Main usage:

from onedevcommonmsgraph.email_analyzer import EmailAnalyzer
analyzer = EmailAnalyzer(tenant_id, client_id, client_secret, email_box)

# Analysis of latest 5 emails with basic information
result = analyzer.analyze_emails(
    email_type='latest',
    information_to_extract='basic',
    parameters={'limit': 5}
)

# Analysis of unread emails with complete information
result = analyzer.analyze_emails(
    email_type='unread',
    information_to_extract='all'
)

# Analysis with custom fields
result = analyzer.analyze_emails(
    email_type='period',
    information_to_extract=['subject', 'sender', 'status'],
    parameters={'days': 7}
)

---

📁 logs/ - Logs Folder

Function: Automatically stores JSON files generated by EmailAnalyzer.

Content:

• email_analysis_YYYYMMDD_HHMMSS.json - Analysis results with unique timestamp
• .gitkeep - Keeps folder in Git repository even when empty

Features:

• ✅ Automatic creation - Folder created automatically if it doesn't exist
• ✅ Unique timestamps - Each analysis generates file with unique date/time
• ✅ Git preservation - Folder maintained in repository via .gitkeep
• ✅ Safe cleanup - Can delete logs without affecting functionality

🚀 Installation and Configuration

Prerequisites

pip install requests

Azure AD Configuration

1. Register an application in Azure AD
2. Configure necessary permissions:
   • Mail.Send (for sending)
   • Mail.Read (for reading)
   • Mail.ReadWrite (for marking as read)
3. Obtain credentials:
   • tenant_id - Tenant ID
   • client_id - Application ID
   • client_secret - Application secret

📋 Usage Examples

Email Sending

from onedevcommonmsgraph.email_ import EmailSender

sender = EmailSender(tenant_id, client_id, client_secret, "[e-mail]")
sender.send_email(
    to=["[e-mail]"],
    subject="Email Subject",
    body="<h1>HTML Content</h1>"
)

Simple Reading

from onedevcommonmsgraph.email_reader import EmailReader

reader = EmailReader(tenant_id, client_id, client_secret, "[e-mail]")
emails = reader.list_emails(limit=10)
unread = reader.list_unread_emails()

Advanced Analysis

from onedevcommonmsgraph.email_analyzer import EmailAnalyzer

analyzer = EmailAnalyzer(tenant_id, client_id, client_secret, "[e-mail]")

# Complete analysis of latest 50 emails
result = analyzer.analyze_emails(
    email_type='latest',
    information_to_extract='all',
    parameters={'limit': 50}
)

# Result automatically saved in logs/email_analysis_YYYYMMDD_HHMMSS.json
print(f"Analysis saved to: {result['saved_file']}")
print(f"Total emails: {result['total_emails']}")
print(f"Statistics: {result['statistics']}")

🔧 Advanced Settings

EmailAnalyzer Parameters

• email_type: Defines which emails to analyze
• information_to_extract: Defines which information to extract
• parameters: Specific parameters (limit, days, sender, etc.)
• save_file: Whether to save automatically (default: True)

Result JSON Structure

{
  "success": true,
  "configuration": {
    "email_type": "latest",
    "information_extracted": "all",
    "parameters": {"limit": 10}
  },
  "total_emails": 10,
  "emails": [...],
  "statistics": {
    "read_rate": 85.5,
    "emails_with_attachments": 3,
    "top_senders": [...]
  },
  "analysis_timestamp": "2024-06-18T11:25:19.978831",
  "saved_file": "logs/email_analysis_20240618_112519.json"
}

📊 Use Cases

1. 📧 Shared Mailbox Monitoring

   • Automatically analyze unread emails
   • Generate team activity reports

2. 📈 Communication Analysis

   • Identify top senders
   • Analyze communication patterns

3. 🔍 Search and Filtering

   • Find emails by specific sender
   • Filter by period or subject

4. 📋 Automated Reports

   • Generate automatic JSON reports

🤝 Contributing

This project is part of the uFly ecosystem and is constantly evolving. For suggestions or improvements, contact the development team.