Skip to main content

Documentation Index

Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt

Use this file to discover all available pages before exploring further.

Need help?
Ask in DiscordOpen a GitHub issueSupport guide
Use this setup when a local agent starter needs to call the Gmail API directly from your machine. For the Customer Email Assist starter, this is the path that lets the dashboard send an approved reply automatically after the undo countdown. If you only use the Codex Gmail connector, you can skip this setup.
Do not publish client secrets, refresh tokens, .env.local files, or screenshots that expose OAuth credentials.

​
What You Will Create

ValueWhere it comes fromUsed for
GOOGLE_CLIENT_IDGoogle Cloud OAuth clientIdentifies your local app to Google.
GOOGLE_CLIENT_SECRETGoogle Cloud OAuth clientAuthenticates the OAuth client.
Gmail refresh tokenDashboard Connect Gmail flowStored locally by the app after Google redirects back to localhost.
CUSTOMER_EMAIL_ASSIST_OPERATOR_EMAILGmail profile or optional env varHelps detect human outbound replies and avoid duplicate sends.
CUSTOMER_EMAIL_ASSIST_GMAIL_LABELGmail label ID such as INBOXControls which mailbox label the local sync reads.
GOOGLE_REFRESH_TOKEN, CUSTOMER_EMAIL_ASSIST_DB_PATH, and CUSTOMER_EMAIL_ASSIST_POLICY_PATH are optional. The dashboard stores the refresh token locally, and the starter has defaults for the DB and policy paths.

​
Step 1: Open Or Create A Google Cloud Project

  1. Open Google Cloud Console.
  2. Sign in with the Google account that owns the Gmail mailbox.
  3. In the top bar, click the project selector.
  4. Click New Project.
  5. Name it something explicit, such as Customer Email Assist Local.
  6. Click Create.
  7. Use the project selector again and select the new project.
Using a dedicated project keeps testing credentials separate from production Google projects.

​
Step 2: Enable Gmail API

  1. In the left navigation, open APIs & Services.
  2. Click Library.
  3. Search for Gmail API.
  4. Open Gmail API.
  5. Click Enable.
If the button says Manage, the API is already enabled for this project. Google has been moving this UI into Google Auth Platform. Older projects may still show APIs & Services > OAuth consent screen. The same settings exist in both layouts.
  1. In the left navigation, open Google Auth Platform. If your Console still uses the older layout, open APIs & Services > OAuth consent screen.
  2. If this is a new project, click Get started.
  3. Set the app name to something local and clear, such as Customer Email Assist Local.
  4. Set User support email to your Gmail address.
  5. Set Audience:
    • Choose External for a personal Gmail account.
    • Choose Internal only for a Google Workspace app used inside that organization.
  6. Add your email under Contact information or Developer contact information.
  7. Keep publishing status as Testing while developing.
  8. Save the app information.
Testing mode is enough for a local workshop or single-operator starter. For a public multi-user app, expect Google OAuth verification requirements.

​
Step 4: Add Yourself As A Test User

  1. Open Google Auth Platform > Audience. In the older layout, open APIs & Services > OAuth consent screen.
  2. Find Test users.
  3. Click Add users.
  4. Enter the Gmail address that will authorize mailbox access.
  5. Click Save.
If the app remains in Testing mode, only listed test users can authorize it.

​
Step 5: Add Gmail Scopes

  1. Open Google Auth Platform > Data Access. In the older layout, open the consent screen’s Scopes step.
  2. Click Add or remove scopes.
  3. Search for Gmail.
  4. Select or manually add:
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.readonly
Use gmail.send when the local dashboard needs to send approved replies. Use gmail.readonly when local scripts need to import Gmail threads. If your flow only sends and never imports through local OAuth, gmail.send is the minimum scope.

​
Step 6: Create The OAuth Client

  1. Open APIs & Services > Credentials.
  2. Click Create Credentials.
  3. Select OAuth client ID.
  4. For Application type, choose Web application.
  5. Name it Customer Email Assist Local Web.
  6. Under Authorized redirect URIs, click Add URI.
  7. Enter the callback URI for the port where your dashboard runs:
http://localhost:3002/api/gmail/oauth/callback
If you use the default Next.js port, add this instead: 
http://localhost:3000/api/gmail/oauth/callback
If you use both ports during testing, add both URIs.
  1. Click Create.
  2. Copy the client ID and client secret into .env.local.
Google may only show or download the client secret at creation time. Store it in your local .env.local, not in the repository.

​
Step 7: Create .env.local

In the starter directory, create: 
case-studies/examples/customer-email-assist-starter/.env.local
Use this shape: 
GOOGLE_CLIENT_ID="paste-client-id"
GOOGLE_CLIENT_SECRET="paste-client-secret"

CUSTOMER_EMAIL_ASSIST_GMAIL_LABEL="INBOX"

# Optional
GOOGLE_REDIRECT_URI="http://localhost:3002/api/gmail/oauth/callback"
CUSTOMER_EMAIL_ASSIST_OPERATOR_EMAIL="you@example.com"
GOOGLE_REFRESH_TOKEN="manual-fallback-refresh-token"
CUSTOMER_EMAIL_ASSIST_DB_PATH="/tmp/customer-email-assist.sqlite3"
CUSTOMER_EMAIL_ASSIST_POLICY_PATH="./support-policy.md"
Restart the dashboard after editing .env.local.

​
Step 8: Connect Gmail From The Dashboard

  1. Start the dashboard.
  2. Leave Gmail mode set to OAuth.
  3. Click Connect Gmail.
  4. Sign in as the same test user you configured in Google Cloud.
  5. Approve the Gmail scopes.
  6. Google redirects back to /api/gmail/oauth/callback.
  7. The app stores the refresh token locally under:
~/.codex/state/customer-email-assist/gmail-oauth.json
This is the normal web-app flow. OAuth Playground is only a manual debugging fallback now; users should not need it for the starter.

​
Step 9: Use The Dashboard Mode Switch

In the Customer Email Assist dashboard:
  • Select OAuth to use local OAuth. This attempts the direct Gmail API send path after the undo countdown.
  • Select Gmail connector to queue approved replies for connector-backed processing instead.

​
Quick Verification

From the starter folder: 
npm install
npm run setup-local
npm run dev
For a local OAuth sync pass: 
npm run sync:oauth
For queued approved replies: 
tsx scripts/customer-email-assist.ts apply-send-queue

​
Official References