# Gmail API Setup for bob.eagle.suites@gmail.com

This guide sets up a proper Gmail API path for sending email safely from the local machine.

## Goal

Enable a local workflow that can:
- authenticate as `bob.eagle.suites@gmail.com`
- send plain emails
- send emails with file attachments
- be wrapped later into a safe OpenClaw-accessible script

## Phase 1 — Google Cloud setup

### 1. Create or choose a Google Cloud project
Go to:
- https://console.cloud.google.com/

Create a project dedicated to local assistant automation.
Suggested name:
- `bob-eagle-gmail`

### 2. Enable the Gmail API
In the project:
- open **APIs & Services**
- choose **Library**
- search for **Gmail API**
- click **Enable**

### 3. Configure OAuth consent screen
Go to:
- APIs & Services → OAuth consent screen

Recommended:
- User type: **External**
- App name: `bob_the_bot local mailer`
- Support email: `bob.eagle.suites@gmail.com`
- Developer contact: `bob.eagle.suites@gmail.com`

Scopes to add:
- `https://www.googleapis.com/auth/gmail.send`

For a private/personal setup, you can keep this limited to test users.
Add:
- `bob.eagle.suites@gmail.com`

### 4. Create OAuth client credentials
Go to:
- APIs & Services → Credentials
- Create Credentials → OAuth client ID
- Application type: **Desktop app**

Suggested name:
- `bob-local-gmail-desktop`

Download the credentials JSON.

## Phase 2 — Local file placement

Store the downloaded credentials at:

- `/Users/bobeagle/.openclaw/workspace/secrets/gmail-oauth-client.json`

Create the folder if needed.

Do **not** commit this file to git.

## Phase 3 — Local Python environment

Install the required packages:

```bash
pip3 install --user google-api-python-client google-auth google-auth-oauthlib google-auth-httplib2
```

## Phase 4 — First-run authentication

The first auth flow should create a reusable token file locally.

Recommended token location:
- `/Users/bobeagle/.openclaw/workspace/secrets/gmail-token.json`

The first auth run will open a browser window, let you sign in, and store the refresh token for later local use.

## Phase 5 — Safe operational design

The agent should not directly freestyle raw email calls.
Use a wrapper script that accepts explicit inputs such as:
- recipient
- subject
- body file or body text
- optional attachment path

That wrapper should:
- use only Gmail API send scope
- send only after explicit user instruction for external mail
- log basic send metadata locally
- fail safely if token/credentials are missing

## Recommended local paths

- Credentials:
  - `secrets/gmail-oauth-client.json`
- Token:
  - `secrets/gmail-token.json`
- Script:
  - `scripts/send_gmail.py`
- Logs:
  - `logs/gmail-send.log`

## Security notes

- never store credentials in chat
- never commit credentials or tokens to git
- keep OAuth scope limited to `gmail.send`
- do not request mailbox read permissions unless genuinely needed later
- require explicit approval before any real outbound email send

## What success looks like

Once complete, the local system should be able to run something like:

```bash
python3 scripts/send_gmail.py \
  --to recipient@example.com \
  --subject "Test Email" \
  --body-file message.txt \
  --attach /Users/bobeagle/.openclaw/workspace/shared/pdfs/hello-world.pdf
```

and send it as:
- `bob.eagle.suites@gmail.com`

## Next step after setup

Once the credentials JSON is in place, the next move is to run the local auth flow and test a single outbound email.