# Gmail Connector — User Guide

This guide covers the manual steps required to set up Gmail retrieval for a new tenant. These are **internal actions** performed by ENTR staff — the client does not need to do anything.

All steps use the shared `entr-processor@entr.solutions` Google Workspace account.

---

## Prerequisites

- Access to [Google Admin Console](https://admin.google.com) for `entr.solutions`
- Access to the `entr-processor@entr.solutions` Gmail account
- The tenant's `TENANT_NAME` value (from `.env` or `config.py`)

---

## Step 1: Add an email alias in Google Admin Console

1. Log in to [Google Admin Console](https://admin.google.com)
2. Navigate to **Directory > Users**
3. Find and select the **entr-processor@entr.solutions** user
4. Click **User information > Alternative email addresses (email alias)**
5. Add the alias email address for this tenant (e.g. `tenant-orders@entr.solutions`)
6. Click **Save**

> The alias takes a few minutes to propagate. You can verify by sending a test email to the alias.

---

## Step 2: Create the tenant label in Gmail

1. Log in to [Gmail](https://mail.google.com) as `entr-processor@entr.solutions`
2. In the left sidebar, scroll down and click **+ Create new label**
3. Enter the label name: `TENANT/{TENANT_NAME}`
   - Example: for `TENANT_NAME=Zuidberg`, create label `TENANT/Zuidberg`
   - **Case matters** — `TENANT/Zuidberg` is not the same as `TENANT/zuidberg`
   - The label name must match `TENANT_NAME` in the adapter's `.env` exactly, unless `label_override` is configured in the adapter settings

> If using `label_override`: the label name must match the override value instead of `TENANT/{TENANT_NAME}`.

---

## Step 3: Create a Gmail filter

1. In Gmail, click the **search options icon** (down arrow in the search bar)
2. In the **To** field, enter the alias email created in Step 1
3. Click **Create filter**
4. Check **Apply the label** and select the label created in Step 2
5. Optionally check **Also apply filter to matching conversations** to label existing emails
6. Click **Create filter**

---

## Verification

After completing all steps, send a test email to the alias address. It should:

1. Arrive in the `entr-processor@entr.solutions` inbox
2. Automatically receive the `TENANT/{TENANT_NAME}` label

You can then verify the adapter can see it:

```bash
curl -X POST http://localhost:8096/list_documents \
  -H "Content-Type: application/json" \
  -d '{"adapter_identifier": "<handler_id>", "source_identifier": "gmail"}'
```

The test email should appear in the response.

---

## Troubleshooting

| Problem | Cause | Fix |
|---------|-------|-----|
| Emails arrive but have no label | Filter not matching | Check the **To** field in the filter matches the alias exactly |
| Alias email bounces | Alias not yet propagated | Wait 5-10 minutes after adding in Admin Console |
| Adapter returns 0 documents | Label name mismatch | Compare the label in Gmail with `TENANT_NAME` in `.env` — must be exact match (case-sensitive) |
| `Gmail label 'TENANT/X' not found` error | Label doesn't exist or name differs | Open Gmail, verify the label exists under the exact name `TENANT/{TENANT_NAME}` |
