> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bothive.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Gmail Agents

> Build agents that read, draft, and send emails — powered by your Gmail inbox.

<div className="hero-container">
  <h1 className="hero-title">
    Gmail Agents
  </h1>

  <p className="hero-subtitle">
    Connect your Gmail to Bothive and build agents that triage, draft, and respond to emails — automatically.
  </p>
</div>

## What you can build

<CardGroup cols={2}>
  <Card title="Email Triage Agent" icon="filter" className="glass-effect">
    Reads incoming emails, classifies them by category, labels them, and drafts initial replies for your review.
  </Card>

  <Card title="Auto-Responder" icon="reply" className="glass-effect">
    Answers common inquiries automatically — FAQs, pricing, support questions — using your knowledge base.
  </Card>

  <Card title="Outreach Composer" icon="pen" className="glass-effect">
    Drafts personalized outreach emails based on lead context. You review and send, or it sends automatically.
  </Card>

  <Card title="Meeting Coordinator" icon="calendar" className="glass-effect">
    Reads scheduling emails, checks Google Calendar availability, and sends meeting invites — end to end.
  </Card>
</CardGroup>

## Setup

<Steps>
  <Step title="Connect Gmail via OAuth">
    In your bot dashboard → **Integrations** → **Gmail** → **Connect with Google**.

    Sign in and authorize the scopes Bothive requests:

    * `gmail.readonly` — Read emails
    * `gmail.compose` — Create and send drafts
    * `gmail.labels` — Apply labels
  </Step>

  <Step title="Configure your agent">
    Create a new bot or open an existing one. Add Gmail capabilities:

    ```hivelang theme={null}
    bot EmailAssistant {
      capabilities {
        gmail.readEmail
        gmail.createDraft
        gmail.sendEmail
        gmail.applyLabel
        gmail.getThread
      }
    }
    ```
  </Step>

  <Step title="Write your instructions">
    Be specific about what the agent should and should not do with emails.
  </Step>

  <Step title="Test in the Playground">
    In the Playground, simulate email content and check that the agent:

    * Reads the email correctly
    * Drafts an appropriate reply
    * Applies the right label
    * Does NOT send unless you explicitly authorize it
  </Step>

  <Step title="Add a safety review step">
    For production, configure the agent to create drafts and await human approval before sending. Only switch to auto-send after the agent has proven accurate over 50+ test cases.
  </Step>
</Steps>

## HiveLang v5 example — email triage agent

```hivelang theme={null}
bot EmailTriage {
  description: "Reads incoming emails and drafts intelligent replies"

  capabilities {
    gmail.readEmail
    gmail.createDraft
    gmail.applyLabel
    knowledgebase.search
  }

  instructions {
    You are an email triage assistant.

    For every email you read:
    1. Classify it as: support / billing / sales / spam / other
    2. Apply the corresponding Gmail label
    3. If it's support or billing:
       - Search the knowledge base for relevant answers
       - Draft a helpful reply in the same language as the email
       - Keep the draft under 150 words unless the question is complex
    4. If it's spam: label it and skip

    Rules:
    - Never send emails automatically — always create drafts
    - Never reveal confidential pricing or internal information
    - Always be polite and professional
    - Sign off as "The [Company] Support Team"
  }

  on "triage inbox" {
    emails = call gmail.readEmail with {
      label: "INBOX",
      unread: true,
      limit: 10
    }

    loop email in emails {
      category = call ai.classify with {
        text: email.body,
        categories: ["support", "billing", "sales", "spam", "other"]
      }
      call gmail.applyLabel with {
        message_id: email.id,
        label: category
      }

      if category != "spam" {
        answer = call knowledgebase.search with { query: email.subject }
        call gmail.createDraft with {
          to: email.from,
          subject: "Re: {email.subject}",
          body: answer
        }
      }
    }

    say "Triaged {emails.length} emails. Drafts created for non-spam."
  }
}
```

## Gmail capabilities reference

| Capability           | What it does                              | Requires         |
| -------------------- | ----------------------------------------- | ---------------- |
| `gmail.readEmail`    | Read emails by label, search query, or ID | `gmail.readonly` |
| `gmail.getThread`    | Read a full conversation thread           | `gmail.readonly` |
| `gmail.createDraft`  | Create a draft (not sent)                 | `gmail.compose`  |
| `gmail.sendEmail`    | Send an email directly                    | `gmail.compose`  |
| `gmail.applyLabel`   | Add/remove Gmail labels                   | `gmail.labels`   |
| `gmail.searchEmails` | Search by subject, body, sender           | `gmail.readonly` |

## Best practices

<AccordionGroup>
  <Accordion title="Always start with drafts, not sends">
    When building an email agent, start by having it create drafts only. Review 50–100 drafts before enabling auto-send. The cost of a wrong email is high.
  </Accordion>

  <Accordion title="Use labels for workflow stages">
    Create Gmail labels like `Bothive/Triaged`, `Bothive/Replied`, `Bothive/NeedsReview`. This makes it easy to track what the agent has processed.
  </Accordion>

  <Accordion title="Limit the inbox query scope">
    Don't query the full inbox every run. Use `label: "INBOX"` with `unread: true` and `limit: 20` to keep runs fast and focused.
  </Accordion>

  <Accordion title="Handle out-of-office and bounce replies">
    Add instructions to skip auto-reply emails. Check the `In-Reply-To` header and skip if the subject starts with "Out of Office" or "Delivery failed".
  </Accordion>

  <Accordion title="Test with your own address first">
    Before connecting your main inbox, test the agent with a dedicated test Gmail account. Send test emails to yourself and verify drafts are correct.
  </Accordion>
</AccordionGroup>

## Next reads

<CardGroup cols={3}>
  <Card title="Meeting Assistants" icon="calendar" href="./meeting-assistants" className="glass-effect" />

  <Card title="Custom Integrations" icon="plug" href="./custom-integrations" className="glass-effect" />

  <Card title="Build Your First Agent" icon="hammer" href="./build-your-first-agent" className="glass-effect" />
</CardGroup>