GitHub - Promyer/stellar-inbox: An AI skill for filtering and reading newsletters

GitHub

2 min read Original article ↗

Codex skill for reading a configured Gmail newsletter and passing its raw decoded text MIME parts to the model. It directly queries Gmail for the requested date or range and uses .agents/skills/email-reader/LINK_FILTERING_INSTRUCTIONS.md for report selection, formatting, and feedback collection.

Use with Codex

Invoke the skill with a date or date range:

$email-reader 2026-06-27
$email-reader 2026-06-01 2026-06-27

The skill runs .agents/skills/email-reader/scripts/fetch_messages.py, which returns message metadata and raw decoded text MIME parts. The model interprets those parts when composing the report; the fetcher does not select, clean, or rewrite their content. Generated reports keep per-link feedback in browser localStorage and can export it as Report.feedback.json for later preference updates.

Configure

Create .env in the project root:

ALLOWED_SENDER=sender@example.com
GMAIL_OAUTH_CREDENTIALS_PATH=gmail_client_secret.json

Get the OAuth client file:

  1. Open https://console.cloud.google.com.
  2. Create or select a project.
  3. Enable APIs & Services -> Library -> Gmail API.
  4. Configure Google Auth Platform -> OAuth consent screen -> Branding.
  5. Add your Gmail account to test users if the app is in test mode.
  6. Create Google Auth Platform -> Clients -> Create client.
  7. Select application type Desktop app.
  8. Download the JSON file.
  9. Rename it to gmail_client_secret.json and put it in the project root.

This must be an OAuth client JSON for an installed desktop app. Do not use an API key or a service account JSON.

The scope in code is:

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

Authorization

Install the locked dependencies first:

On the first request, the command prints the OAuth authorization URL to the console. Open it in the browser of your choice and finish authorization; the local OAuth token is saved to .gmail_token.json. If Google rejects an old or revoked token, the command starts authorization again and keeps the old token as a backup.

If Google shows Access blocked: this app has not completed the Google verification process, wait and try again later. It can take up to 24 hours for new OAuth app settings and test-user changes to become available.