Email Management

# Natural language examples
"Show me my recent emails"
"List my inbox messages"
"What emails did I receive today?"

{
  "success": true,
  "message": "Found 5 message(s).",
  "messages": [
    {
      "id": "msg_abc123",
      "subject": "Project Update",
      "from": "Sarah Johnson <[email protected]>",
      "to": "[email protected]",
      "date": "Mon, 10 Mar 2026 14:30:00 -0500",
      "snippet": "Here's the latest status on the project..."
    }
  ]
}

"Read the email from Sarah"
"Show me the full content of the project update email"
"What does the message say?"

"Search for emails from my boss"
"Find messages with 'invoice' in the subject"
"Show me emails with attachments from last week"

# Search by sender
query="from:[email protected]"

# Search by subject keyword
query="subject:meeting"

# Complex query
query="from:[email protected] has:attachment after:2026-03-01"

"Show me my unread emails"
"What messages haven't I read yet?"
"List unread messages"

"Show me emails in my INBOX"
"List starred messages"
"What's in my Important folder?"

query="label:INBOX"      # Inbox messages
query="label:STARRED"    # Starred messages
query="label:IMPORTANT"  # Important messages
query="label:SENT"       # Sent messages

"Summarize my emails from this week"
"Who sent me the most emails recently?"
"Give me a weekly email summary"

{
  "success": true,
  "message": "Weekly summary from past 7 days.",
  "summary": {
    "period": "Past 7 days (2026/03/01 to 2026/03/08)",
    "message_count": 45,
    "top_senders": [
      ["Sarah Johnson", 12],
      ["John Smith", 8],
      ["Team Notifications", 6]
    ],
    "sample_subjects": [
      "Project Update",
      "Meeting Notes",
      "Q1 Planning"
    ],
    "messages": []
  }
}

class GmailService:
    def _get_message_body(self, message: dict) -> str:
        """Extract plain text body from email message.
        Prioritizes plain text over HTML."""

def _decode_message_part(self, part: dict) -> str:
    """Decode email body from base64-encoded MIME part."""
    try:
        if "data" in part:
            return base64.urlsafe_b64decode(part["data"]).decode("utf-8")
    except Exception:
        pass
    return ""

class GmailService:
    def __init__(self, service):
        """Initialize with authenticated Gmail service."""
        self.service = service

User: "Show me my unread emails"
Agent: "You have 5 unread messages:
1. 'Project Update' from Sarah
2. 'Meeting Request' from John
..."

User: "Find the email from my boss about the budget"
Agent: [Searches: from:boss@company.com subject:budget]
"Found 1 message: 'Q2 Budget Review' from yesterday."

User: "Read it"
Agent: [Retrieves full message body]
"The email says: 'Hi team, please review the attached budget...'"

User: "Summarize my emails from this week"
Agent: "You received 45 emails in the past 7 days.
Top senders:
- Sarah Johnson (12 emails)
- John Smith (8 emails)
- Notifications (6 emails)

Common subjects: Project Update, Meeting Notes, Planning"

User: "Show me emails with attachments from Sarah after March 1st"
Agent: [Query: from:sarah@example.com has:attachment after:2026/03/01]
"Found 3 messages matching your criteria."

try:
    result = gmail_service.get_message_full(message_id="invalid_id")
except HttpError as error:
    if error.resp.status == 404:
        return {
            "success": False,
            "message": f"Message '{message_id}' not found.",
            "error": str(error)
        }

"from:[email protected] after:2026-03-01 subject:project"

"subject:the"  # Matches too many messages

"after:2026/03/01 before:2026/03/08"  # Specific week

"from:[email protected] has:attachment is:unread"