Skip to main content
An intelligent email assistant that connects to Gmail, triages incoming messages, summarizes important emails, drafts responses, and helps manage inbox zero.

​
Key Concepts

ConceptDescription
Email TriageCategorizes emails by urgency and type
Priority Levels1-5 priority scale based on sender and content
Draft-Only ModeNever auto-sends emails. Drafts require approval
Phishing DetectionWarns about suspicious emails

​
Prerequisites

  • Python 3.12+
  • OpenAI API key
  • Google OAuth credentials (for Gmail access)

​
Setup

1

Clone the repository

git clone https://github.com/agno-agi/agno.git
cd agno
2

Create and activate virtual environment

uv venv --python 3.12
source .venv/bin/activate
3

Install dependencies

uv pip install -r cookbook/01_showcase/01_agents/inbox_agent/requirements.in
4

Set up Google OAuth credentials

  1. Go to Google Cloud Console
  2. Create a new project or select existing
  3. Enable the Gmail API:
    • Go to “APIs & Services” > “Enable APIs and Services”
    • Search for “Gmail API” and enable it
  4. Create OAuth credentials:
    • Go to “APIs & Services” > “Credentials”
    • Click “Create Credentials” > “OAuth client ID”
    • Select “Desktop app” as application type
    • Download the credentials
  5. Add redirect URI:
    • Go to OAuth consent screen settings
    • Add http://127.0.0.1/ as authorized redirect URI
5

Set environment variables

export OPENAI_API_KEY=your-openai-key
export GOOGLE_CLIENT_ID=your-client-id
export GOOGLE_CLIENT_SECRET=your-client-secret
export GOOGLE_PROJECT_ID=your-project-id
export GOOGLE_REDIRECT_URI=http://127.0.0.1/

​
Run the Agent

The first run will open a browser window for OAuth authentication.

​
Triage Inbox

Categorize and prioritize unread emails: 
python cookbook/01_showcase/01_agents/inbox_agent/examples/triage_inbox.py
Demonstrates:
  • Retrieving unread emails
  • Categorization (urgent, action_required, fyi, newsletter, spam)
  • Priority scoring

​
Summarize Thread

Get a summary of an email conversation: 
python cookbook/01_showcase/01_agents/inbox_agent/examples/summarize_thread.py
Demonstrates:
  • Fetching email threads
  • Key point extraction
  • Action item identification

​
Draft Response

Create a draft reply: 
python cookbook/01_showcase/01_agents/inbox_agent/examples/draft_response.py
Demonstrates:
  • Context-aware draft generation
  • Tone matching
  • Draft storage (never auto-sends)

​
Agent Configuration

inbox_agent = Agent(
    name="Inbox Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    system_message=SYSTEM_MESSAGE,
    tools=[
        ReasoningTools(add_instructions=True),
        GmailTools(),
    ],
    add_datetime_to_context=True,
    add_history_to_context=True,
    num_history_runs=5,
    read_chat_history=True,
    enable_agentic_memory=True,
    markdown=True,
)
ParameterPurpose
modelGPT-5.2 for email understanding and drafting
GmailToolsGmail API integration (read, search, draft, label)
ReasoningToolsPlan triage and response approach
read_chat_historyRemember previous email context

​
How It Works

​
Email Categories

CategoryCriteriaDefault Action
urgentTime-sensitive, VIPs, deadlinesSurface immediately
action_requiredRequests, questionsQueue for response
fyiUpdates, notifications, CC’dSummarize briefly
newsletterMarketing, subscriptionsArchive or summarize
spamUnwanted promotionalArchive

​
Priority Levels

LevelDescriptionTimeframe
1CriticalImmediate
2High24-48 hours
3MediumWithin a week
4LowInformational
5MinimalArchive/skip

​
Gmail Tools

ToolDescription
get_unread_emailsRetrieve unread messages
get_emails_by_threadGet full thread
search_emailsSearch by query
create_draft_emailSave draft (no send)
send_email_replyReply to thread
apply_labelOrganize with labels
mark_email_as_readMark processed

​
Safety Features

  1. No auto-send: Emails are saved as drafts, never auto-sent
  2. Confirmation required: Sending requires explicit user approval
  3. Read-only default: Only reads emails unless action requested
  4. Phishing detection: Warns about suspicious emails

​
Troubleshooting

Verify your Google Cloud credentials are set correctly:
echo $GOOGLE_CLIENT_ID
echo $GOOGLE_CLIENT_SECRET
Ensure the redirect URI is configured in Google Cloud Console.
Go to Google Cloud Console > APIs & Services > Enable APIs and Services > Search for “Gmail API” > Enable.
Delete token.json and re-authenticate:
rm token.json
Run the agent again to trigger OAuth flow.

​
Source Code