feat(integrations): Gmail UDFs for email automation

[generalplantain]

Checklist

• Read CONTRIBUTING.md.
• PR title is short and non-generic (see previously merged PRs for examples).
• PR only implements a single feature or fixes a single bug.
• Tests passing (uv run pytest tests)?
• Lint / pre-commits passing (pre-commit run --all-files)?

Description

This PR adds Gmail UDFs (User Defined Functions) for email security automation workflows.

Functions Included

• search_messages - Search Gmail with query syntax
• get_message - Get full message content
• get_message_headers - Get headers only (faster)
• list_labels - List Gmail labels
• get_thread - Get full email thread
• get_connected_account - Show connected Gmail account

Features

• OAuth Integration: Uses Tracecat's built-in OAuth system (google_gmail provider)
• Security-focused: Designed for phishing investigations and threat hunting
• Query Syntax: Full Gmail search syntax support
• Flexible: Read-only by default, optional modify permissions

Use Cases

• Phishing investigations: Search for suspicious emails by sender, subject, or content
• Email analysis: Extract headers, attachments, and metadata
• Automated response: Monitor inbox for security alerts
• Threat hunting: Search across email history with powerful queries

Related Issues

Companion PR for Gmail OAuth provider: #[PR_NUMBER_FROM_PR1]

Screenshots / Recordings

The Gmail UDFs will appear in the workflow builder under the "Gmail" display group. Users can:

1. Search emails with Gmail query syntax
2. Retrieve full messages or just headers
3. Access email threads for investigation
4. List available labels

Steps to QA

Prerequisites

• Gmail OAuth provider must be configured (PR #[NUMBER])
• User must have connected their Gmail account via OAuth

Testing

1. Create a new workflow in Tracecat
2. Add a Gmail action (e.g., "Search Gmail Messages")
3. Configure the search query (e.g., from:test@example.com)
4. Run the workflow
5. Verify email results are returned correctly

Example Queries

• from:suspicious@evil.com has:attachment - Find emails with attachments from sender
• subject:urgent after:2024/01/01 - Find urgent emails after date
• is:unread label:inbox - Find unread emails in inbox
• has:attachment filename:pdf - Find emails with PDF attachments

Note: Requires companion OAuth provider PR to be merged first for full functionality.

---

Summary by cubic

Adds Gmail UDFs for security automation. Workflows can search emails, fetch full messages or headers, get threads, list labels, and download attachments using the Tracecat Gmail OAuth.

• New Features

  • Search messages with Gmail query syntax (search_messages)
  • Get full message content, headers, and body (get_message)
  • Get headers only for faster metadata retrieval (get_message_headers)
  • List user labels (list_labels)
  • Get all messages in a thread (get_thread)
  • Download attachments by message and attachment ID (get_attachment)

• Migration

  • Configure the google_gmail OAuth provider and connect a Gmail account.

^{Written for commit db7608f. Summary will update automatically on new commits.}

[cubic-dev-ai]

1 issue found across 1 file

Prompt for AI agents (all 1 issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="packages/tracecat-registry/tracecat_registry/integrations/gmail.py">

<violation number="1" location="packages/tracecat-registry/tracecat_registry/integrations/gmail.py:85">
P2: Silent failure when fetching individual message metadata. Non-200 responses are silently ignored, which could lead to confusing partial results without any indication that some messages failed to fetch. Consider logging failed fetches or including error info in the response.</violation>
</file>

_{Reply to cubic to teach it or ask questions. Re-run a review with @cubic-dev-ai review this PR}

[topher-lo]

We generally prefer to be a very thin wrapper around the API themselves (to avoid losing context). Can we just return the original data as opposed to change the schema?

[topher-lo]

Same comment as above? Can we just return the msg_data directly?

[topher-lo]

See above suggestion

[topher-lo]

See above