Skip to main content

​
Overview

GitaChat’s daily verse feature delivers a personalized verse from the Bhagavad Gita every day. The intelligent selection algorithm ensures you receive verses you haven’t seen before, providing a structured way to gradually explore all 700 verses.

​
How Daily Verse Works

Smart Selection

Algorithm prioritizes verses you haven’t seen yet

Web Access

Fetch your daily verse through the API anytime

Email Delivery

Subscribe to receive verses via email at 8 AM in your timezone

Daily Caching

Same verse throughout the day for consistent reflection

​
Daily Verse API

​
Get Daily Verse

Fetch the verse of the day for the authenticated user. Endpoint: GET /api/daily Authentication: Required (Clerk) Rate Limit: 10 requests per minute per client Query Parameters (Optional):
  • tz: Timezone (e.g., “America/New_York”, “Asia/Kolkata”). Defaults to “UTC”
Request Example: 
GET /api/daily?tz=America/New_York
Response: 
{
  "chapter": 2,
  "verse": 47,
  "translation": "You have the right to perform your prescribed duties, but you are not entitled to the fruits of your actions.",
  "summarized_commentary": "This verse emphasizes the importance of performing one's duty without attachment to the results. Krishna teaches that we should focus on our responsibilities and actions, leaving the outcomes to divine will.",
  "cached": false
}
Response Fields:
  • chapter: Chapter number (1-18)
  • verse: Verse number
  • translation: English translation of the verse
  • summarized_commentary: AI-generated explanation
  • cached: Boolean indicating if this was retrieved from cache (true) or newly generated (false)

​
Email Subscription API

​
Check Subscription Status

Check if the user is subscribed to daily verse emails. Endpoint: GET /api/email-subscription Authentication: Required (Clerk) Rate Limit: 10 requests per minute per client Response: 
{
  "subscribed": true,
  "timezone": "America/New_York"
}

​
Subscribe to Daily Emails

Sign up to receive daily verse emails at 8 AM in your timezone. Endpoint: POST /api/email-subscription Authentication: Required (Clerk) Rate Limit: 10 requests per minute per client Request Body: 
{
  "timezone": "America/New_York"
}
Timezone Validation:
  • Must be a valid IANA timezone identifier
  • Examples: “America/Los_Angeles”, “Europe/London”, “Asia/Tokyo”
  • Defaults to “UTC” if not provided
Success Response (200): 
{
  "success": true
}
Implementation Notes:
  • Uses Clerk to retrieve user’s primary email address
  • Generates unique unsubscribe token for each user
  • Upserts subscription (creates new or reactivates existing)
  • Sets is_active to true and records subscribed_at timestamp

​
Unsubscribe from Daily Emails

Stop receiving daily verse emails. Endpoint: DELETE /api/email-subscription Authentication: Required (Clerk) Rate Limit: 10 requests per minute per client Success Response (200): 
{
  "success": true
}
This sets is_active to false without deleting the subscription record.

​
Daily Verse Selection Algorithm

The intelligent verse selection algorithm ensures a varied and complete exploration of the Bhagavad Gita:

Selection Process

  1. Check Cache: Look for today’s cached verse (based on timezone)
  2. Return Cache: If found, return immediately (ensures consistency)
  3. Fetch History: Retrieve all verses you’ve previously seen
  4. Filter Unseen: Identify verses you haven’t encountered yet
  5. Random Selection: Pick randomly from unseen verses
  6. Fallback: If all verses seen, pick randomly from all verses
  7. Fetch Details: Get translation and commentary from backend
  8. Cache Result: Store in database for the rest of the day
Why This Approach:
  • Gradual Coverage: You’ll eventually see all 700 verses
  • No Repetition: Prioritizes new verses until you’ve seen them all
  • Fair Distribution: Random selection ensures variety
  • Consistent Experience: Same verse all day for focused reflection

​
Email Delivery System

The email delivery is handled by a cron job that runs hourly. Endpoint: POST /api/daily-email Authentication: CRON_SECRET bearer token (not for public use)

​
Delivery Process

Timezone Detection

Identifies timezones where it’s currently 8 AM

Subscriber Query

Fetches active subscribers in those timezones

Verse Generation

Generates personalized daily verse for each user

Email Sending

Sends formatted emails via Resend service

​
Email Content

Each daily verse email includes:
  • Subject Line: Customized for the verse
  • Verse Text: Full Sanskrit verse and translation
  • Commentary: Summarized explanation of the teaching
  • Chapter Reference: Chapter and verse number
  • Unsubscribe Link: Easy one-click unsubscribe

​
Supported Timezones

The system supports 30+ major timezones worldwide: Americas: Honolulu, Anchorage, Los Angeles, Denver, Chicago, New York, Toronto, Vancouver, Phoenix, Sao Paulo Europe: London, Paris, Berlin, Moscow, Amsterdam, Rome, Madrid, Stockholm, Reykjavik Asia: Dubai, Kolkata, Bangkok, Singapore, Tokyo, Shanghai, Hong Kong, Seoul Oceania: Sydney, Melbourne, Auckland

​
Data Storage

​
Daily Verse Cache Table

ColumnTypeDescription
user_idStringClerk user identifier
dateDateDate string (YYYY-MM-DD) in user’s timezone
chapterIntegerChapter number
verseIntegerVerse number
translationTextVerse translation
summarized_commentaryTextCommentary
matched_themeTextTheme that matched (nullable)
Unique Constraint: user_id + date ensures one verse per day per user.

​
Email Subscribers Table

ColumnTypeDescription
user_idStringClerk user identifier (unique)
emailStringUser’s email address
timezoneStringIANA timezone identifier
unsubscribe_tokenUUIDUnique token for unsubscribe link
is_activeBooleanWhether subscription is active
subscribed_atTimestampWhen user subscribed
last_email_sent_atTimestampLast email delivery time

​
Implementation Files

/api/daily/route.ts

Web API for fetching daily verse on demand

/api/email-subscription/route.ts

Subscription management (GET, POST, DELETE)

/api/daily-email/route.ts

Cron job handler for automated email delivery

Backend /api/verse

Fetches verse translation and commentary

​
Rate Limiting

Different rate limits for different operations:
EndpointRate LimitPurpose
GET /api/daily10 req/minNormal daily verse fetching
GET /api/email-subscription10 req/minCheck subscription status
POST /api/email-subscription10 req/minSubscribe to emails
DELETE /api/email-subscription10 req/minUnsubscribe from emails

​
Error Handling

Common error scenarios:
ErrorStatusDescription
Unauthorized401User not logged in
No email found400User has no email address (subscription only)
Invalid timezone400Timezone not recognized
Too many requests429Rate limit exceeded
Database not configured503Supabase connection unavailable
Failed to fetch verse500Backend verse API error

​
Best Practices

Daily Verse Tips

  • Set Your Timezone: Ensure accurate delivery time for emails
  • Consistent Reflection: Access your daily verse at the same time each day
  • Add Notes: Write reflections on your daily verse
  • Bookmark Favorites: Save daily verses that resonate deeply
  • Check Once: The verse is cached, so it’s the same all day—take time to reflect

​
Privacy & Unsubscribe

Easy Unsubscribe

Every email includes a one-click unsubscribe link

Data Control

Unsubscribing sets is_active to false, preserving preferences

Email Privacy

Your email is only used for daily verse delivery

Token Security

Unsubscribe tokens are unique UUIDs per user

​
Integration with History

The daily verse selection algorithm uses your search history to ensure variety:
  1. Queries query_history table for all verses you’ve searched
  2. Creates a “seen verses” set from your history
  3. Filters these out when selecting today’s verse
  4. Ensures you see fresh content you haven’t explored before
This creates a personalized, progressive journey through the Bhagavad Gita.

​
Cron Job Monitoring

The daily email cron job returns detailed metrics: 
{
  "sent": 145,
  "total": 150,
  "timezones": ["America/New_York", "Europe/London", "Asia/Tokyo"],
  "errors": ["Failed to send email to a subscriber"]
}
Metrics Tracked:
  • sent: Number of emails successfully delivered
  • total: Total number of subscribers in target timezones
  • timezones: List of timezones where it’s currently 8 AM
  • errors: Array of error messages (only present if errors occurred)

Build docs developers (and LLMs) love

Get started for freeTalk to us