Email Calendar Tool

Automatically create Google Calendar events from your emails using AI

Get Started View on GitHub
📧

Email Parsing

Forward any email and it extracts event details automatically

🤖

AI-Powered

Uses Claude AI to understand complex event descriptions

📅

Auto-Create

Events appear in your Google Calendar instantly

âš¡

Real-Time

Processes emails within seconds using webhooks

1 Create Google Cloud Project

  1. Go to Google Cloud Console
  2. Click Select a project → New Project
  3. Name it "Email Calendar Tool" and click Create

2 Enable Required APIs

  1. In your project, go to APIs & Services → Library
  2. Search for and enable:
    • Gmail API
    • Google Calendar API

3 Configure OAuth Consent Screen

  1. Go to APIs & Services → OAuth consent screen
  2. Choose External user type
  3. Fill in:
    • App name: "Email Calendar Tool"
    • User support email: Your email
    • Developer contact: Your email
  4. Click Add or Remove Scopes and add:
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.modify
    • https://www.googleapis.com/auth/calendar
  5. Add your email as a Test user
  6. Complete the wizard

4 Create OAuth Credentials

  1. Go to APIs & Services → Credentials
  2. Click Create Credentials → OAuth client ID
  3. Application type: Web application
  4. Name: "Email Calendar Tool Web"
  5. Under Authorized redirect URIs, add your callback URL: 
    https://YOUR-APP-NAME.up.railway.app/callback

    Replace YOUR-APP-NAME with your Railway app name (you'll get this after deploying)

  6. Click Create
  7. Download the JSON file - you'll need this!
Important: Make sure to select "Web application" (not "Desktop app") for the OAuth client type!

5 Deploy to Railway

Option A: Deploy from GitHub (Recommended)

  1. Fork the repository to your GitHub account
  2. Go to railway.app/new
  3. Click Deploy from GitHub repo
  4. Select your forked repository
  5. Railway will auto-detect and deploy!

Option B: Railway CLI

brew install railway
railway login
git clone https://github.com/yourusername/email-calendar-tool
cd email-calendar-tool
railway init
railway up

6 Set Environment Variables

In Railway Dashboard → Your Project → Variables tab, add:

Variable Value Required
GOOGLE_CREDENTIALS Paste the entire contents of the downloaded OAuth JSON file Yes
ANTHROPIC_API_KEY Your Anthropic API key from console.anthropic.com Yes
TIMEZONE Your timezone (e.g., America/New_York, Europe/London) Yes
FLASK_SECRET_KEY Any random string for session security Recommended
Tip: After deploying, note your Railway app URL (e.g., https://email-calendar-tool-production-xxxx.up.railway.app) and update the OAuth redirect URI in Google Cloud Console to match.

7 Connect Your Google Account

  1. Visit your Railway app URL
  2. Click Login with Google
  3. Select your Google account and authorize the app
  4. You'll see a success page with your token
  5. Important: Copy the token and add it as GOOGLE_TOKEN environment variable in Railway to persist across deployments
Done! Your Email Calendar Tool is now running and monitoring your Gmail.

8 How to Use

  1. Send or forward any email containing event details to yourself
  2. In Gmail, apply the label calendar-event to the email
  3. The tool automatically extracts event info and creates a calendar event!

Example Email

Subject: Dinner with Sarah

Hey! Let's meet for dinner next Friday at 7pm at
The Italian Place on Main Street. Looking forward to it!

The AI will extract:

Optional: Set Up Gmail Pub/Sub (Instant Processing)

By default, the tool checks for new emails every 5 minutes. For instant processing, set up Gmail Pub/Sub:

Click to expand Pub/Sub setup instructions â–¼
  1. In Google Cloud Console, enable the Cloud Pub/Sub API
  2. Create a Pub/Sub topic named gmail-notifications
  3. Create a push subscription pointing to https://YOUR-APP.up.railway.app/webhook/gmail
  4. Grant [email protected] publish permissions on the topic
  5. Set up a Gmail watch using the Gmail API (see docs for details)

Troubleshooting

"redirect_uri_mismatch" error â–¼

Your OAuth redirect URI doesn't match. In Google Cloud Console:

  1. Go to APIs & Services → Credentials
  2. Edit your OAuth client
  3. Add exactly: https://YOUR-RAILWAY-URL/callback
  4. Make sure it uses HTTPS and matches your Railway URL exactly
"Access blocked: App not verified" â–¼

You need to add yourself as a test user:

  1. Go to OAuth consent screen in Google Cloud Console
  2. Under "Test users", click Add Users
  3. Add your Gmail address
Token lost after Railway redeployment â–¼

Railway's filesystem is ephemeral. To persist your token:

  1. After successful login, copy the token shown on the success page
  2. In Railway Dashboard, add it as GOOGLE_TOKEN environment variable
  3. Your token will now persist across deployments
Events not being created â–¼
  • Check that the Gmail label is exactly calendar-event (case-sensitive)
  • Verify your ANTHROPIC_API_KEY is valid
  • Check Railway logs for error messages: railway logs
  • Try the manual trigger: curl -X POST https://YOUR-APP/trigger

Environment Variables Reference

VariableDefaultDescription
GOOGLE_CREDENTIALS-OAuth client JSON (required)
GOOGLE_TOKEN-OAuth token JSON (set after first login)
ANTHROPIC_API_KEY-Anthropic API key for AI parsing
TIMEZONEUTCYour timezone for event times
GMAIL_LABELcalendar-eventGmail label to monitor
CALENDAR_IDprimaryTarget Google Calendar ID
CHECK_INTERVAL_MINUTES5Polling interval (if not using Pub/Sub)
FLASK_SECRET_KEYrandomSession encryption key
Back to App