Skip to main content
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: 
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/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

ParameterTypeDefaultDescription
credsCredentialsNonePre-fetched OAuth credentials
credentials_pathstrNonePath to credentials file
token_pathstrNonePath to token file
scopesList[str]NoneCustom OAuth scopes
portintNonePort to use for OAuth authentication

​
Toolkit Functions

FunctionDescription
get_latest_emailsGet the latest X emails from the user’s inbox. Parameters include count (int) for number of emails to retrieve.
get_emails_from_userGet 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_emailsGet the latest X unread emails. Parameters include count (int) for maximum number of unread emails.
get_starred_emailsGet X number of starred emails. Parameters include count (int) for maximum number of starred emails.
get_emails_by_contextGet 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_dateGet 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_threadRetrieve all emails from a specific thread. Parameters include thread_id (str) for the thread ID.
search_emailsSearch emails using natural language queries. Parameters include query (str) for search query, and count (int) for number of emails to retrieve.
create_draft_emailCreate 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_emailSend an email with attachments. Parameters include to (str), subject (str), body (str), cc (Optional[str]), and attachments (Optional[Union[str, List[str]]]).
send_email_replyReply 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_readMark a specific email as read. Parameters include message_id (str) for the message ID.
mark_email_as_unreadMark a specific email as unread. Parameters include message_id (str) for the message ID.
list_custom_labelsList all user-created custom labels. No parameters required.
apply_labelApply 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_labelRemove labels from emails. Parameters include context (str) for search query, label_name (str) for label name, and count (int, default=10).
delete_custom_labelDelete 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