# Gmail AWB Reader

## For tenant administrators

1. Open **Integrations & risk**.
2. Select **Gmail AWB Reader**.
3. Click **Connect Gmail**.
4. Sign in to the mailbox containing courier messages.
5. Approve read-only Gmail access.
6. Choose the subject keyword and scan frequency.
7. Enable **Scan automatically** and save the schedule.

Use **Scan now** whenever you want an immediate scan. Matches are staged in
**Review AWB candidates** and are never applied to orders automatically.

The tenant administrator never enters a Client ID, Client Secret, refresh
token, callback URL, or Google scope.

## For the Subset platform operator

Google OAuth is configured once for the entire Subset installation:

```text
SUBSET_GOOGLE_GMAIL_CLIENT_ID=your-client-id
SUBSET_GOOGLE_GMAIL_CLIENT_SECRET=your-client-secret
SUBSET_GOOGLE_GMAIL_REDIRECT_URI=https://your-domain/api/v1/gmail-awb/oauth/callback
```

For local Mac use, the callback can be:

```text
http://localhost:8000/api/v1/gmail-awb/oauth/callback
```

Add the exact callback URL to the Google OAuth Web Application's authorized
redirect URIs and restart Subset.

Subset requests only:

`https://www.googleapis.com/auth/gmail.readonly`

## Automatic scans

Run the Subset worker continuously:

```bash
make worker
```

The worker checks schedules every few seconds. For each due tenant it:

1. Obtains a temporary Gmail access token.
2. Searches messages using the configured subject keyword.
3. Reads supported email bodies and attachments.
4. Stages order, AWB, and courier candidates.
5. Records the run result and next expected scan.

Supported sources are email text, HTML, TXT, CSV, TSV, XLSX, and text-based
PDF attachments. Scanned image PDFs require OCR.

If Google revokes access, Subset stops retrying that tenant, shows
**Reconnect Gmail**, and continues processing other tenants.