Gmail

Gmail enables an Agent to interact with Gmail, allowing it to read, search, send, manage emails, and organize them with labels.

Prerequisites

The Gmail toolkit requires Google API client libraries and proper authentication setup. Install the required dependencies:

uv pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

You’ll also need to set up Google Cloud credentials:

1. Go to Google Cloud Console
2. Create a project or select an existing one
3. Enable the Gmail API
4. Create OAuth 2.0 credentials
5. Set up environment variables:

export GOOGLE_CLIENT_ID=your_client_id_here
export GOOGLE_CLIENT_SECRET=your_client_secret_here
export GOOGLE_PROJECT_ID=your_project_id_here
export GOOGLE_REDIRECT_URI=http://localhost  # Default value

Example

cookbook/14_tools/gmail_tools.py

from agno.agent import Agent
from agno.tools.gmail import GmailTools

agent = Agent(tools=[GmailTools()])
agent.print_response("Show me my latest 5 unread emails", markdown=True)

Toolkit Params

Parameter	Type	Default	Description
creds	Credentials	None	Pre-fetched OAuth credentials
credentials_path	str	None	Path to credentials file
token_path	str	None	Path to token file
scopes	List[str]	None	Custom OAuth scopes
port	int	None	Port to use for OAuth authentication

Toolkit Functions

Function	Description
get_latest_emails	Get the latest X emails from the user’s inbox. Parameters include count (int) for number of emails to retrieve.
get_emails_from_user	Get X number of emails from a specific sender. Parameters include user (str) for sender name or email, and count (int) for maximum number of emails.
get_unread_emails	Get the latest X unread emails. Parameters include count (int) for maximum number of unread emails.
get_starred_emails	Get X number of starred emails. Parameters include count (int) for maximum number of starred emails.
get_emails_by_context	Get X number of emails matching a specific context. Parameters include context (str) for search term, and count (int) for maximum number of emails.
get_emails_by_date	Get emails within a specific date range. Parameters include start_date (int) for unix timestamp, range_in_days (Optional[int]) for date range, and num_emails (Optional[int], default=10).
get_emails_by_thread	Retrieve all emails from a specific thread. Parameters include thread_id (str) for the thread ID.
search_emails	Search emails using natural language queries. Parameters include query (str) for search query, and count (int) for number of emails to retrieve.
create_draft_email	Create and save an email draft with attachments. Parameters include to (str), subject (str), body (str), cc (Optional[str]), and attachments (Optional[Union[str, List[str]]]).
send_email	Send an email with attachments. Parameters include to (str), subject (str), body (str), cc (Optional[str]), and attachments (Optional[Union[str, List[str]]]).
send_email_reply	Reply to an existing email thread. Parameters include thread_id (str), message_id (str), to (str), subject (str), body (str), cc (Optional[str]), and attachments (Optional[Union[str, List[str]]]).
mark_email_as_read	Mark a specific email as read. Parameters include message_id (str) for the message ID.
mark_email_as_unread	Mark a specific email as unread. Parameters include message_id (str) for the message ID.
list_custom_labels	List all user-created custom labels. No parameters required.
apply_label	Apply labels to emails (creates if needed). Parameters include context (str) for search query, label_name (str) for label name, and count (int, default=10).
remove_label	Remove labels from emails. Parameters include context (str) for search query, label_name (str) for label name, and count (int, default=10).
delete_custom_label	Delete a custom label with confirmation. Parameters include label_name (str) and confirm (bool, default=False) for safety confirmation.

You can use include_tools or exclude_tools to modify the list of tools the agent has access to. Learn more about selecting tools.

Developer Resources

• View Example