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

# Gmail

> Turn new mail in a Gmail inbox into email.received events.

A Gmail source reads new mail in the labels that you pick. Each message becomes an [`email.received`](/events/email-received) event.

<Info>Gmail sources are in beta and need a Pro project.</Info>

## Set up

<Steps>
  <Step title="Connect">
    Open **Sources → Add source → Gmail** and sign in with Google. hooksnode asks for read-only access to your mail (`gmail.readonly`).
  </Step>

  <Step title="Pick labels">
    Pick the labels to watch, for example `INBOX` or a label that a Gmail filter adds.
  </Step>

  <Step title="Add filters (optional)">
    Send only the mail you need. Each filter matches part of the header text and ignores case.

    | Filter           | Example             |
    | ---------------- | ------------------- |
    | From contains    | `alerts@gtbank.com` |
    | To contains      | `orders@`           |
    | Subject contains | `Credit Alert`      |
  </Step>

  <Step title="Turn on bank alerts (optional)">
    See [Bank alerts](/sources/bank-alerts).
  </Step>
</Steps>

## How it works

1. Gmail tells hooksnode when the mailbox changes.
2. hooksnode reads the new messages and stores one event for each message. The idempotency key is `gmail:<source>:<message>`, so a message is never sent twice.
3. Every 5 minutes, hooksnode checks mailboxes that it has not synced for 10 minutes. This catches lost notices.

hooksnode starts at the time you connect. It does not send old mail.

## Problems

| What you see                        | What to do                                                                                                  |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Needs sign-in**                   | Google refused the access. It was revoked or it expired. Press **Reconnect**. The owner also gets an email. |
| **Some email may have been missed** | Gmail's history was too old. hooksnode started again from now. Mail in the gap is not sent.                 |