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

# Gmail Integration — Search Your Inbox with AI Agents

> Connect Gmail to Hyper to sync important email threads and search your inbox using Gmail operators — from:, subject:, has:attachment — via any AI agent.

Gmail is often where critical decisions, approvals, and external context live — buried across thousands of threads. When you connect Gmail to Hyper, it automatically identifies and ingests your most important email threads, making them searchable by any AI agent without you having to dig through your inbox manually. Hyper keeps your indexed threads fresh using Google's push notification system, so new important mail surfaces in your memory layer within minutes of arrival.

## Connect Gmail

<Steps>
  <Step title="Open Settings in the Hyper desktop app">
    Launch the Hyper desktop app and click **Settings** in the navigation, then select **Connections**.
  </Step>

  <Step title="Click Connect next to Gmail">
    Find Gmail in the list of available integrations and click **Connect**.
  </Step>

  <Step title="Authorize with Google OAuth 2.0">
    A Google sign-in window opens. Sign in with the Google account whose Gmail you want to connect, then grant Hyper the requested permissions. Hyper uses standard Google OAuth 2.0 — your Google password is never stored by Hyper.
  </Step>

  <Step title="Wait for the initial sync to complete">
    Hyper begins fetching and classifying your email threads immediately. The initial sync may take a few minutes depending on your inbox size. You'll see a sync status indicator in Settings → Connections.
  </Step>
</Steps>

## What Hyper Syncs

Hyper does not ingest every email in your inbox — only threads that Google's classification signals as **important** are pulled in. This keeps your memory layer focused on meaningful content rather than promotional noise.

| What's synced           | Details                                                                        |
| ----------------------- | ------------------------------------------------------------------------------ |
| **Email threads**       | Full thread content, including all messages in a conversation                  |
| **Importance filter**   | Only threads marked or classified as important by Gmail                        |
| **Incremental updates** | New threads and changes are tracked via Gmail's `historyId` mechanism          |
| **Push notifications**  | Google push notifications trigger near-real-time updates                       |
| **Source links**        | Each thread links back to `https://mail.google.com/mail/u/0/#inbox/{threadId}` |

<Info>
  Hyper reads email content only — it never sends, drafts, deletes, or modifies any messages in your Gmail account.
</Info>

## Search Your Email with AI Agents

Once synced, your AI agents can query Gmail using the full Gmail search syntax. Ask questions in natural language and Hyper will translate them, or pass search operators directly.

**Supported search operators:**

| Operator         | Example                  | What it does                         |
| ---------------- | ------------------------ | ------------------------------------ |
| `from:`          | `from:alice@example.com` | Emails from a specific sender        |
| `subject:`       | `subject:Q4 budget`      | Emails with text in the subject line |
| `after:`         | `after:2024/01/01`       | Emails received after a date         |
| `has:attachment` | `has:attachment`         | Emails with file attachments         |
| `is:unread`      | `is:unread`              | Unread threads only                  |

**Example agent queries:**

```text theme={null}
Find emails from our legal team about the contract renewal
Show me unread threads with attachments from this month
Search Gmail: from:ceo@company.com subject:strategy after:2024/01/01
Read the full thread about the Q3 board meeting
```

Agents can also read the complete content of any specific thread by ID, giving them full context for multi-message conversations.

## Reconnect Gmail

If your Google OAuth token expires, Hyper will show a **Reconnect** prompt next to Gmail in **Settings → Connections**.

<Steps>
  <Step title="Go to Settings → Connections">
    Open the Hyper desktop app and navigate to **Settings → Connections**.
  </Step>

  <Step title="Click Reconnect next to Gmail">
    Click the **Reconnect** button. A Google sign-in window opens.
  </Step>

  <Step title="Re-authorize with Google">
    Complete the OAuth flow. Your previously synced threads are preserved — Hyper resumes incremental sync from where it left off.
  </Step>
</Steps>

<Note>
  Your existing indexed email data is not deleted when a token expires. Reconnecting simply restores the sync pipeline.
</Note>

## Disconnect Gmail

To remove Gmail from Hyper, go to **Settings → Connections**, find Gmail, and click **Disconnect**. This revokes Hyper's access token and stops all future syncing. Previously indexed thread content will be removed from your memory layer.

<Warning>
  Disconnecting Gmail removes all synced email data from Hyper's memory layer. If you reconnect later, Hyper will perform a fresh initial sync.
</Warning>