Gmail Integration

Send, search, and manage emails programmatically with Gmail API integration and OAuth authentication.

---

Timbal integrates with Gmail to enable sending, searching, and managing emails programmatically.

This integration allows you to send emails, create drafts, search messages, and handle attachments directly from your Timbal workflows.

Prerequisites

Before using the Gmail integration, you'll need:

1. A Google account with Gmail access
2. A Google Cloud project with the Gmail API enabled
3. OAuth 2.0 credentials (see Google Cloud Console)
4. Download your credentials as gmail_credentials.json and place it in the appropriate directory
5. Authenticate for the first time to generate token.json (see below)

Authentication Setup

The first time you use the integration, you'll be prompted to authenticate:

uv run authenticate.py

This will open a browser window for Google sign-in and create a token.json file for future use.

Installation

Install the requirements by doing:

uv add timbal[steps-gmail]

Send Email

Description

The send_message step allows you to send an email (with optional CC, BCC, and attachments) from your authenticated Gmail account.

Example

from timbal.steps.gmail.messages import send_message

await send_message(
  to=["recipient@example.com"],
  subject="Hello from Timbal!",
  body="This is a test email."
)

Parameters

Parameter	Type	Description	Required
to	list[str]	Email addresses of the recipients	Yes
body	str	The body of the email	Yes
subject	str	The subject of the email	No
cc	list[str]	Email addresses to include in CC	No
bcc	list[str]	Email addresses to include in BCC	No
attachment	str	Path to a file to attach	No

Create Draft

Description

The create_draft_message step allows you to create a draft email (with optional CC, BCC, and attachments).

Example

from timbal.steps.gmail.messages import create_draft_message

await create_draft_message(
  to=["recipient@example.com"],
  subject="Draft Subject",
  body="Draft content."
)

Parameters

Parameter	Type	Description	Required
to	list[str]	Email addresses of the recipients	Yes
body	str	The body of the email	No
subject	str	The subject of the email	No
cc	list[str]	Email addresses to include in CC	No
bcc	list[str]	Email addresses to include in BCC	No
attachment	str	Path to a file to attach	No

Search Messages/Threads

Description

The search step allows you to search Gmail messages or threads using Gmail's search syntax.

Example

from timbal.steps.gmail.messages import search

results = await search(query="from:someone@example.com", resource="messages", max_results=5)

Parameters

Parameter	Type	Description	Required
query	str	Search query using Gmail's search syntax	Yes
resource	str	Type of resource to search: "messages" or "threads"	No
max_results	int	Maximum number of results to return	No

Get Message/Thread

Description

The get_message and get_thread steps allow you to retrieve a specific email or thread by ID.

Example

from timbal.steps.gmail.messages import get_message, get_thread

retrieved_message = await get_message(message_id="your-message-id")
retrieved_thread = await get_thread(thread_id="your-thread-id")

Parameters (get_message)

Parameter	Type	Description	Required
message_id	str	The ID of the message to get	Yes
message_format	str	Format: "minimal", "full", "raw", or "metadata" (default: "full")	No

Parameters (get_thread)

Parameter	Type	Description	Required
thread_id	str	The ID of the thread to get	Yes
message_format	str	Format: "minimal", "full", "raw", or "metadata" (default: "full")	No

Agent Integration Example

from timbal.steps.gmail.messages import send_message
from timbal import Agent

agent = Agent(
  tools=[send_message]
)

response = await agent.complete(
  prompt={
      "to": ["recipient@example.com"],
      "subject": "Hello from Agent!",
      "body": "This is a test email sent by Agent."
  }
)

Notes

• Make sure your Google Cloud project is properly configured and credentials are in place.
• The first authentication will prompt a browser sign-in and create a token.json file for future use.
• For more advanced usage, see the Gmail API documentation.