Codex skill for reading a configured Gmail newsletter and passing its raw decoded text MIME parts to the model. The skill contains a local read-only Gmail daemon as an implementation detail; users normally invoke the skill with a specific date or date range rather than interacting with the daemon directly.
The skill starts the daemon, requests all messages from the configured sender for the requested period, passes all decoded text/plain
and text/html
MIME parts to the model, and uses .agents/skills/email-reader/LINK_FILTERING_INSTRUCTIONS.md
for report selection, formatting, and feedback collection.
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.
Create .env
in the project root:
ALLOWED_SENDER=sender@example.com
GMAIL_OAUTH_CREDENTIALS_PATH=gmail_client_secret.json
HOST=127.0.0.1
PORT=4873
Get the OAuth client file:
- Open
https://console.cloud.google.com
. - Create or select a project.
- Enable
APIs & Services -> Library -> Gmail API
. - Configure
Google Auth Platform -> OAuth consent screen -> Branding
. - Add your Gmail account to test users if the app is in test mode.
- Create
Google Auth Platform -> Clients -> Create client
. - Select application type
Desktop app
. - Download the JSON file.
- 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
Install the locked dependencies first:
uv sync --locked
The daemon can also be started directly for local development:
UV_CACHE_DIR=/tmp/uv-cache uv run --locked python -m email_reader
On the first /messages
request, the daemon opens the OAuth authorization URL in the default browser. Finish Google authorization; the local OAuth token is saved to .gmail_token.json
. If Google rejects an old or revoked token, the daemon automatically 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.
The API is available at /messages
:
curl 'http://127.0.0.1:4873/messages?start_date=2026-06-01&end_date=2026-06-27'