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

# Connect Gmail

> Send and read emails from your Gmail account through Hiveku

Connect a Gmail mailbox so Hiveku can send, read, or manage email for your CRM workflows, sales agents, and automations.

<Info>
  Before you start: [Set up a Google Cloud OAuth app](/how-tos/google-oauth-app) and enable the Gmail API in your Google Cloud project. You only do this once — the same OAuth app powers every Google integration.
</Info>

## Pick Your Scope

Gmail supports several access levels. Pick the smallest scope that does what you need:

| Scope               | OAuth scope                        | What it does                                    |
| ------------------- | ---------------------------------- | ----------------------------------------------- |
| **Read-only**       | `gmail.readonly`                   | Read messages, threads, labels                  |
| **Send only**       | `gmail.send`                       | Send new emails; can't read inbox               |
| **Full access**     | `gmail.modify`                     | Read, send, label, archive, move                |
| **Full + Calendar** | `gmail.modify` + `calendar.events` | Full mail access plus calendar event management |

<Tip>
  If your sales agent needs to book meetings, choose **Full + Calendar**. Calendar access is bundled here rather than as a separate integration so users consent once.
</Tip>

## Connect the Mailbox

<Steps>
  <Step title="Open the email connections page">
    In Hiveku, go to **CRM > Email Connections > Add Connection > Gmail**.
  </Step>

  <Step title="Select your registered Google OAuth app">
    Pick the Google app you registered under **Settings > OAuth Apps**. If you see no apps in the dropdown, create one first — see [Set up a Google Cloud OAuth app](/how-tos/google-oauth-app).
  </Step>

  <Step title="Choose your scope">
    Pick one of:

    * **Read-only** — for reading inboxes (e.g., pulling in support tickets)
    * **Send only** — for outbound email only (transactional, campaigns)
    * **Full access** — for general CRM use, including labeling and archiving
    * **Full + Calendar** — for sales agents that book meetings

    <Warning>
      Choose carefully — changing scopes later requires disconnecting and reconnecting the mailbox, and the user must consent again.
    </Warning>
  </Step>

  <Step title="Authorize with Google">
    Click **Authorize with Google**. You'll be redirected to a Google consent screen showing your app name and the scopes you're requesting.

    Sign in to the Google account you want to connect, review the scopes, and click **Allow**.
  </Step>

  <Step title="Confirm the connection">
    You return to Hiveku, where the new Gmail connection shows:

    * Your email address
    * Active scopes
    * Connection status (**Active**)
  </Step>
</Steps>

## Real-Time Inbox Sync

When you connect Gmail with a read or full scope, Hiveku subscribes to Google Cloud Pub/Sub watch notifications for your mailbox. New messages push to Hiveku in seconds, so inbox-triggered workflows fire almost immediately.

If Pub/Sub can't be configured automatically (some account types require manual Pub/Sub setup), Hiveku falls back to periodic polling — you'll still get new messages, just on a slightly longer delay.

## Connect Multiple Mailboxes

You can connect as many Gmail accounts as you need — each mailbox gets its own connection. Repeat the flow above for each account.

<Info>
  Each Gmail account can be used as a send address, a receiving inbox, or both, depending on the scope you chose.
</Info>

## Verify the Connection

* Connection status on the Email Connections page should show **Active**
* Send a test email from the CRM's compose UI — the recipient should see it arrive from your Gmail address
* For read scopes, trigger a test inbound workflow or check the message list in CRM

## Changing the Scope Later

OAuth tokens are scope-locked. To change a connection from, say, read-only to full access:

<Steps>
  <Step title="Disconnect the existing Gmail connection">
    Click the three-dot menu next to the connection and choose **Disconnect**.
  </Step>

  <Step title="Reconnect with the new scope">
    Start the flow again from **Add Connection > Gmail**, pick the new scope, and authorize.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Access blocked: invalid_scope">
    The Gmail API isn't enabled in your Google Cloud project. Go to **Google Cloud Console > APIs & Services > Library**, search for **Gmail API**, and enable it. Retry the connection.
  </Accordion>

  <Accordion title="Push notifications aren't arriving">
    Gmail push uses Google Cloud Pub/Sub. For most accounts, Hiveku configures this automatically. If your project has specific Pub/Sub requirements (private topics, custom IAM), contact support with your Google Cloud project ID so we can help complete the setup. Hiveku falls back to polling in the meantime.
  </Accordion>

  <Accordion title="Connection says 'Token revoked'">
    The user revoked access to your Google app at [myaccount.google.com/permissions](https://myaccount.google.com/permissions), or the token was invalidated server-side. Reconnect the mailbox to re-issue tokens.
  </Accordion>

  <Accordion title="'App isn't verified' warning for new users">
    Expected if your OAuth consent screen is **External** and you haven't completed Google verification yet. Users can click **Advanced > Go to \[app name] (unsafe)** to continue during testing, or add them as test users in the Google Cloud Console. For production, submit for Google verification.
  </Accordion>

  <Accordion title="I changed scopes and it's not taking effect">
    Tokens are scope-locked — changing scopes requires a fresh authorization. Disconnect the Gmail connection in Hiveku and reconnect with the new scope selected.
  </Accordion>
</AccordionGroup>

## What's Next?

<CardGroup cols={2}>
  <Card title="Connect Google Calendar" icon="calendar" href="/how-tos/connect-google-calendar">
    Bundle calendar access for sales booking
  </Card>

  <Card title="Run Sales Sequences" icon="list-ol" href="/how-tos/crm-sales-sequences">
    Personal OAuth cadences — sent from this Gmail inbox
  </Card>

  <Card title="Work with the AI SDR" icon="robot" href="/how-tos/ai-sdr">
    The AI drafts and sends from your connected Gmail on approval
  </Card>

  <Card title="Send Emails" icon="paper-plane" href="/how-tos/send-emails">
    Use your Gmail connection in workflows
  </Card>
</CardGroup>