Skip to main content
Gmail integration is optional and allows you to include recent email messages in your morning briefing, providing context for your day.
Gmail uses the same OAuth credentials as Google Calendar. If you’ve already set up Google Calendar, you just need to enable the Gmail API and configure filtering preferences.

​
What Gmail Integration Enables

With Gmail configured, Morning Brain Starter can:
  • Display recent email messages in your morning briefing
  • Filter emails by label (e.g., INBOX, specific labels)
  • Limit the number of messages shown
  • Filter messages by date range (e.g., last 7 days)

​
Prerequisites

  • Google Calendar integration already configured (see Google Calendar Setup)
  • Gmail API enabled in your Google Cloud project
  • OAuth token with Gmail scope (generated by setup_oauth.py)

​
Step 1: Enable Gmail API

1

Navigate to Google Cloud Console

Go to Google Cloud Console and select your Morning Brain Starter project.
2

Enable Gmail API

  1. Go to APIs & Services → Library
  2. Search for “Gmail API”
  3. Click on it
  4. Click Enable
If you already ran setup_oauth.py, you may need to regenerate your token to include the Gmail scope. See Step 2 below.

​
Step 2: Verify OAuth Token Has Gmail Scope

The OAuth token generated by setup_oauth.py includes Gmail scope by default. However, if you generated your token before enabling the Gmail API, you’ll need to regenerate it.
1

Check if regeneration is needed

If you see errors related to Gmail permissions when running the morning routine, regenerate your token:
.venv/bin/python scripts/setup_oauth.py --regenerate
2

Authorize Gmail access

During the OAuth flow:
  1. Your browser will open
  2. Sign in to your Google account
  3. Review permissions - you should see Gmail access listed
  4. Click Allow
The script will update GOOGLE_REFRESH_TOKEN in your .env file.
The setup_oauth.py script requests all Google scopes in a single authorization flow:
  • Calendar (read and edit)
  • Gmail (read only)
  • Google Docs (read only)
  • Google Meet (manage settings)

​
Step 3: Configure Gmail Settings

Customize Gmail integration behavior by editing config/email.yaml.
1

Open email.yaml

Open config/email.yaml in your editor:
# Opcional: configuración para sincronizar emails (Gmail).
# Solo se usa si en setup_oauth añadiste el scope de Gmail.

# Etiqueta de Gmail a leer (dejar vacío para usar "INBOX")
label: INBOX

# Número máximo de mensajes a traer (por defecto 20)
max_messages: 20

# Días atrás para filtrar (por defecto 7)
# days_back: 7
2

Customize settings

Adjust the configuration to your preferences:Filter by Label
label: INBOX              # System label
# OR
label: Work/Urgent        # Custom label (use slash for nested labels)
Limit Message Count
max_messages: 10          # Show only 10 most recent messages
Adjust Date Range
days_back: 3              # Only emails from last 3 days

​
Configuration Reference

​
config/email.yaml

Location: config/email.yaml
​
label
string
default:"INBOX"
Gmail label to filter messages.System labels:
  • INBOX - Main inbox
  • SENT - Sent messages
  • DRAFT - Draft messages
  • SPAM - Spam folder
  • TRASH - Trash folder
  • IMPORTANT - Important messages
  • STARRED - Starred messages
Custom labels:
  • Use the exact label name as it appears in Gmail
  • For nested labels, use slash: Work/Urgent
Example:
label: Work/High-Priority
​
max_messages
integer
default:"20"
Maximum number of messages to retrieve.Purpose: Limits the number of messages shown in your morning briefing to avoid overwhelming output.Recommendation: 10-20 messages is usually sufficient for morning context.Example:
max_messages: 15
​
days_back
integer
default:"7"
Number of days to look back when filtering messages.Purpose: Only show recent messages relevant to your current work.Recommendation: 3-7 days for active projects, 1-2 days for high-volume inboxes.Example:
days_back: 5

​
Example Configurations

​
High-Volume Inbox

For busy inboxes, show only recent important messages: 
label: IMPORTANT
max_messages: 10
days_back: 2

​
Work Email

Focus on work-related messages from the past week: 
label: Work
max_messages: 20
days_back: 7

​
Minimal Setup

Use defaults for standard inbox monitoring: 
label: INBOX
max_messages: 20
# days_back: 7  # Commented out to use default

​
OAuth Scopes Used

Gmail integration uses these OAuth scopes (requested by setup_oauth.py): 
# Gmail: read recent email (morning briefing, bitácoras)
"https://www.googleapis.com/auth/gmail.readonly"
Read-only access: Morning Brain Starter only reads your emails. It cannot send, delete, or modify messages.

​
Testing Your Configuration

After configuring Gmail:
1

Verify token has Gmail scope

Run the morning routine:
.venv/bin/python run_morning.py
If you see a permission error, regenerate your token:
.venv/bin/python scripts/setup_oauth.py --regenerate
2

Check for email section

Look for an email section in the morning output. You should see:
  • Subject lines of recent messages
  • Sender information
  • Date/time received
  • Preview snippets
3

Adjust filtering if needed

If you see too many or too few messages:
  1. Edit config/email.yaml
  2. Adjust max_messages, days_back, or label
  3. Run the morning routine again

​
Troubleshooting

Possible causes:
  • Gmail API not enabled
  • OAuth token doesn’t include Gmail scope
  • No messages match the filter criteria
Solution:
  1. Verify Gmail API is enabled in Google Cloud Console
  2. Regenerate token: .venv/bin/python scripts/setup_oauth.py --regenerate
  3. Check config/email.yaml filters (label, days_back)
  4. Verify messages exist matching your criteria in Gmail
Your OAuth token doesn’t have Gmail scope.Solution: Regenerate the token with Gmail scope:
.venv/bin/python scripts/setup_oauth.py --regenerate
Make sure to authorize Gmail access when the browser opens.
The label filter isn’t working as expected.Solution:
  1. Verify the label name in config/email.yaml matches exactly (case-sensitive)
  2. For nested labels, use slash separator: Parent/Child
  3. For system labels, use uppercase: INBOX, SENT, STARRED
Reduce the number of messages shown.Solution: Edit config/email.yaml:
max_messages: 10    # Reduce from 20
days_back: 3        # Reduce from 7
The label specified in config/email.yaml doesn’t exist in your Gmail.Solution:
  1. Open Gmail and verify the label exists
  2. Check spelling and capitalization in config/email.yaml
  3. Use INBOX if unsure

​
Disabling Gmail Integration

Gmail integration is automatically disabled if:
  1. Gmail API is not enabled in your Google Cloud project
  2. Your OAuth token doesn’t include the Gmail scope
  3. You leave config/email.yaml with default/empty settings
To explicitly disable:
  1. Comment out or remove the Gmail scope when regenerating tokens (edit scripts/setup_oauth.py)
  2. Or simply don’t enable the Gmail API in Google Cloud Console
Morning Brain Starter will continue to work without Gmail integration.

​
Privacy and Security

Read-only access: Morning Brain Starter uses the gmail.readonly scope, which only allows reading messages. It cannot:
  • Send emails
  • Delete or move messages
  • Modify labels or categories
  • Access other users’ emails
Token storage: Your GOOGLE_REFRESH_TOKEN is stored in resources/secrets/.env, which is excluded from version control by default. Keep this file secure.

​
Next Steps

Client Configuration

Map calendar events to clients

Asana Integration

Optional: Add task management

Usage Guide

Learn how to run morning routine

Google Calendar Setup

Review Google Calendar configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us