Weekly Masterclass - English Learning Workflow

An automated n8n workflow that generates and delivers comprehensive weekly English masterclasses via email, powered by Google Gemini AI.

Overview

This project provides a complete end-to-end automation system that:

• Reads your lesson history from Google Sheets to provide context
• Generates comprehensive weekly lessons using Google Gemini AI
• Creates structured JSON content with vocabulary, grammar, exercises, and solutions
• Transforms content into premium HTML emails with beautiful design
• Delivers automated weekly emails with Gmail integration
• Archives lesson content back to Google Sheets for tracking

Perfect for: Language teachers, self-learners, educational content creators, or anyone building AI-powered learning systems with n8n.

---

Preview

Here's what your weekly masterclass emails will look like:

Beautiful gradient header with dynamic title and emoji based on the week's theme

---

Features

✨ Weekly Schedule Automation - Set-and-forget Sunday delivery (customizable) ✨ AI-Powered Content Generation - Google Gemini creates contextual lessons ✨ Structured Educational Content - Vocabulary, grammar, dialogues, exercises, and solutions ✨ Premium HTML Email Design - Beautiful, responsive email templates with color-coded sections ✨ Exercise Validation - Includes complete solutions for self-assessment ✨ Historical Context Awareness - AI references previous lessons for continuity ✨ Robust Error Handling - Parser validation with fallback values ✨ Production-Ready - Retry logic, error emails, and comprehensive logging

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         Weekly Masterclass Workflow                      │
└─────────────────────────────────────────────────────────────────────────┘

  Schedule Trigger (Weekly - Sunday 9 AM)
           │
           ↓
  Read History from Google Sheets (Last 6 lessons)
           │
           ↓
  Prepare Context (JavaScript - Build AI input)
           │
           ↓
  Generate Lesson (Google Gemini AI)
           │
           ├─→ Returns structured JSON with:
           │   • Weekly emoji & title
           │   • Intro & vocabulary (5-7 words)
           │   • Grammar focus with exercises
           │   • Dialogue practice (6-8 lines)
           │   • Translation & word scramble exercises
           │   • Weekly challenge
           │   • Complete solutions
           │   • Closing motivational quote
           │
           ↓
  Parser & Validation (JavaScript)
           │
           ├─→ Validates JSON structure
           ├─→ Ensures all required fields
           └─→ Provides fallback values
           │
           ↓
  Formatters (JavaScript - Convert to HTML)
           │
           ├─→ Format vocabulary with pronunciation
           ├─→ Format grammar with examples
           ├─→ Format dialogue with translations
           ├─→ Format exercises & solutions
           └─→ Apply color scheme & styling
           │
           ↓
  HTML Generator (JavaScript - Assemble email)
           │
           ├─→ Create header with gradient
           ├─→ Build content sections
           ├─→ Add footer with attribution
           └─→ Generate complete HTML document
           │
           ↓
  Send Email (Gmail)
           │
           ├─→ Send to main recipient
           └─→ BCC to additional recipients
           │
           ↓
  Save to Google Sheets (Archive lesson)
           │
           └─→ Log: Date, Intro, Vocab, Grammar, Dialogue, Challenge

Prerequisites

Before using this workflow, ensure you have:

n8n Instance

• Self-hosted n8n or n8n Cloud account
• n8n version 1.0+ recommended

Google Cloud Account

You'll need to enable these APIs and create credentials:

1. Google Sheets API

   • For reading lesson history and saving new lessons
   • Requires OAuth2 credentials

2. Gmail API

   • For sending weekly emails
   • Requires OAuth2 credentials

3. Google Gemini API

   • For AI content generation
   • Requires API key (Gemini 3 Flash Preview recommended)

Google Sheet Setup

• Create a Google Sheet with two sheets:
  • Sheet 1 (History): Columns: Fecha, Cita, Autor, Contenido Email
  • Sheet 2 (Weekly Lessons): Columns: Fecha, Introduccion, Vocabulario, Grammar Focus, Dialogo, Desafio

Installation

1. Clone or Download

git clone <repository-url>
cd weekly-masterclass

2. Import into n8n

1. Open your n8n instance
2. Click Workflows → Import
3. Select weekly-masterclass.json
4. Click Import

3. Configure Credentials

You'll need to set up three credentials in n8n:

Google Sheets OAuth2

1. Go to Credentials → Add Credential
2. Select Google Sheets OAuth2 API
3. Enter your Google Cloud OAuth2 credentials
4. Authorize access to Google Sheets
5. Copy the credential ID

Google Gemini API

1. Go to Credentials → Add Credential
2. Select Google PaLM API (used for Gemini)
3. Enter your Gemini API key from Google AI Studio
4. Save the credential

Gmail OAuth2

1. Go to Credentials → Add Credential
2. Select Gmail OAuth2 API
3. Enter your Google Cloud OAuth2 credentials
4. Authorize access to Gmail
5. Copy the credential ID

4. Update Workflow Configuration

Open the workflow and update these nodes:

Node: "Leer Historial Quotes" (Read History)

• Replace YOUR_GOOGLE_SHEET_DOCUMENT_ID with your Google Sheet ID
• Update credential to your Google Sheets OAuth2 credential

Node: "Generar Lección Semanal" (Generate Lesson)

• CRITICAL: Replace the [PLACEHOLDER: YOUR CUSTOM LLM PROMPT] with your custom AI prompt
• Update credential to your Google Gemini API credential
• See "Customization" section for prompt engineering guidance

Node: "Enviar Email Semanal" (Send Email)

• Replace your-email@example.com with your email address
• Update bccList with additional recipients (or remove if not needed)
• Update credential to your Gmail OAuth2 credential

Node: "Guardar Lección Semanal" (Save Lesson)

• Replace YOUR_GOOGLE_SHEET_DOCUMENT_ID with your Google Sheet ID
• Ensure the sheet name matches your Sheet 2 name
• Update credential to your Google Sheets OAuth2 credential

Node: "Schedule - Domingo 9AM" (Schedule Trigger)

• Adjust the trigger time if you want a different schedule
• Currently set to weekly on Sundays at 9 AM

5. Test the Workflow

1. Click Execute Workflow to run a test
2. Check each node for successful execution (green checkmarks)
3. Verify:
   • History was read correctly
   • AI generated valid JSON content
   • Email was sent successfully
   • Lesson was saved to Google Sheets
4. Check your email inbox for the masterclass email

6. Activate

Once testing is successful:

1. Toggle the Active switch in the top right
2. The workflow will now run automatically on schedule

Configuration

Google Sheet Structure

Sheet 1: History (Daily Quotes)

This sheet should contain your daily lesson history:

Fecha	Cita	Autor	Contenido Email
2024-01-15	"The only way to do great work..."	Steve Jobs	[Full lesson content]
2024-01-16	"Success is not final..."	Winston Churchill	[Full lesson content]

Sheet 2: Weekly Lessons (Archive)

The workflow automatically populates this:

Fecha	Introduccion	Vocabulario	Grammar Focus	Dialogo	Desafio
2024-01-21	¡Buen domingo! Esta semana...	[JSON array]	[JSON object]	[JSON array]	Challenge text

AI Prompt Engineering

⚠️ IMPORTANT: The workflow includes a placeholder prompt. You must create your own custom prompt.

Your prompt should define:

1. Role & Persona

• Define the AI's role (e.g., English teacher, motivator, curriculum designer)
• Specify teaching style and tone
• Set language level expectations (e.g., A1-A2 beginner)

2. Task Description

• Clearly state what the AI should produce (weekly masterclass content)
• Define inputs (last 6 lessons from context)
• Specify output requirements (JSON structure)

3. Content Strategy

• Define pedagogical approach (grammar-focused, communicative, etc.)
• Specify curriculum or syllabus to follow (optional)
• Provide topic selection guidance

4. Output Structure

• Specify exact JSON schema with all required fields
• Provide examples for each field
• Define validation rules (e.g., "translation array must have exactly 3 items")

5. Quality Guidelines

• Specify content quality expectations
• Provide examples of good vs. bad outputs
• Define edge case handling

Example prompt structure:

You are an expert English teacher creating weekly masterclasses.

INPUT: You'll receive the last 6 daily lessons with quotes and content.

OUTPUT: Respond with ONLY valid JSON (no markdown) in this exact structure:
{
  "weeklyEmoji": "🚀",
  "weeklyTitle": "Your Adventure with Present Simple",
  "intro": "...",
  "vocab": [...],
  "grammar": {...},
  "dialogue": [...],
  "exercises": {...},
  "challenge": "...",
  "solutions": {...},
  "closingQuote": {...}
}

RULES:
- Keep language simple (A1-A2 level)
- Provide exactly 3 translation exercises
- Include complete solutions for all exercises
- Choose the best quote from the week for closingQuote

See the "Generar Lección Semanal" node comments for the full expected JSON structure.

Customization

Email Design Customization

The email design is fully customizable through the Formatadores (Formatters) node. Here's how to modify the visual appearance:

Color System

All colors are defined in the colors object in the Formateadores node (line ~259):

const colors = {
    // Background & Text
    bg: "#FFFDF9",           // Email background (warm white)
    text: "#1a202c",         // Primary text color (dark)
    textLight: "#555555",    // Secondary text (gray)
    textMuted: "#888888",    // Tertiary text (light gray)
    pronunciation: "#FF6B6B", // Pronunciation guide (red)

    // Section Badges
    vocabBadgeBg: "#E3F2FD",      // Vocabulary badge background (light blue)
    vocabBadgeText: "#1565C0",    // Vocabulary badge text (blue)
    grammarBadgeBg: "#F3E5F5",    // Grammar badge background (light purple)
    grammarBadgeText: "#7B1FA2",  // Grammar badge text (purple)
    talkBadgeBg: "#E8F5E9",       // Dialogue badge background (light green)
    talkBadgeText: "#2E7D32",     // Dialogue badge text (green)
    exercisesBadgeBg: "#FFF3E0",  // Exercises badge background (light orange)
    exercisesBadgeText: "#EF6C00", // Exercises badge text (orange)
    challengeBadgeBg: "#FFE0F0",  // Challenge badge background (light pink)
    challengeBadgeText: "#C2185B", // Challenge badge text (pink)
    solutionsBadgeBg: "#FFF9C4",  // Solutions badge background (light yellow)
    solutionsBadgeText: "#F57F17", // Solutions badge text (gold)
    quoteBadgeBg: "#E0F2F1",      // Quote badge background (light teal)
    quoteBadgeText: "#00695C",    // Quote badge text (teal)

    // Header Gradient
    gradientStart: "#f6d365",     // Gradient left (gold)
    gradientEnd: "#fda085",       // Gradient right (coral)

    // Section Backgrounds
    vocabBg: "#FFFFFF",           // Vocabulary section (white)
    grammarBg: "#F8FAFC",         // Grammar section (light gray)
    dialogueBg: "#F0FFF4",        // Dialogue section (very light green)
    exercisesBg: "#FFFBF0",       // Exercises section (light cream)
    solutionsBg: "#FFFFF0",       // Solutions section (ivory)
    quoteBg: "#F0FFFF",           // Quote section (light cyan)

    // Accents
    accentBlue: "#2C7BE5",        // Link and highlight blue
    accentBorder: "#D0E6FF",      // Border accent (light blue)
    accentGold: "#FFD700"         // Border accent for special sections (gold)
};

Typography Customization

Modify font families, sizes, and weights throughout the formatters:

Primary Fonts:

• Headers: Georgia, serif (classic, elegant)
• Body text: 'Trebuchet MS', sans-serif (modern, readable)
• Code/Pronunciation: 'Courier New', monospace (fixed-width for clarity)

Font Sizes:

• Main title (header): 36px
• Section titles: 20px
• Body text: 16px
• Small text (hints, meta): 13-14px

To change fonts, search for font-family in the Formateadores node and replace with your preferred web-safe fonts.

Layout & Spacing

Card Padding:

// In createCard function (~line 285)
<td style=\"padding: 32px;\">  // Increase/decrease for more/less spacing

Section Margins:

// Between sections
style=\"margin: 24px 0;\"  // Vertical spacing between cards

Border Radius:

border-radius: 20px;  // Roundness of cards
border-radius: 50px;  // Roundness of badges

Header Gradient Customization

The header uses a linear gradient. Modify in Generador HTML node (~line 320):

style=\"background:linear-gradient(135deg,${colors.gradientStart} 0%,${colors.gradientEnd} 100%);\"

// Change angle: 135deg → 90deg (vertical) or 180deg (horizontal)
// Change colors: Update gradientStart and gradientEnd in colors object

Badges & Icons

Badge Style:

// In createBadge function (~line 275)
padding: 6px 14px;           // Horizontal and vertical padding
border-radius: 50px;         // Pill shape
font-size: 11px;             // Text size
letter-spacing: 1px;         // Character spacing
text-transform: uppercase;   // ALL CAPS style

Emoji Icons: Update emoji icons in each section badge:

• Vocabulary: 🧩
• Grammar: 💡
• Dialogue: 🗣️
• Exercises: 📚
• Challenge: 🎯
• Solutions: 🔑
• Quote: 📜

Change these in the Generador HTML node where createBadge() is called.

Responsive Design

The email template uses table-based layout for maximum email client compatibility. The max-width is set to 600px:

<table width=\"600\" cellpadding=\"0\" cellspacing=\"0\" border=\"0\"
       style=\"max-width:600px; ...\">

To adjust for mobile, consider media queries (though support varies by email client).

Email Output Example

The weekly masterclass email includes the following sections:

Header Section

• Dynamic Emoji Badge: Changes based on weekly theme (e.g., 🚀 ⭐ 💪 🎯 🔥)
• Personalized Title: AI-generated title matching the week's grammar focus
• Gradient Background: Eye-catching gold-to-coral gradient

Content Sections

1. Introduction

• Warm greeting and weekly theme overview
• Connection to previous lessons
• Grammar topic preview

2. 🧩 Vocabulario (Vocabulary)

• 5-7 carefully selected words from the week's quotes
• Pronunciation guide in IPA format: /pronunciación/
• Spanish translation
• Example sentence at A1-A2 level

Each word includes pronunciation, translation, and a practical example sentence

3. 💡 Grammar Focus

• Clear grammar topic title (e.g., "Present Simple", "Past Tense")
• Simple explanation (max 3 sentences)
• 3 practical examples
• Fill-in-the-blank exercise

Grammar explanation with examples and an interactive fill-in exercise

4. 🗣️ Let's Talk (Dialogue)

• 6-8 lines of natural conversation
• Speaker labels (A/B format)
• Pronunciation for each line
• Spanish translation

5. 📚 Ejercicios Prácticos (Practice Exercises)

Translation Practice:

• 3 sentences to translate from English to Spanish
• Helpful hints for each (e.g., "Use the verb 'to be'")
• Color-coded boxes

Word Scramble:

• 2 scrambled sentences to put in correct order
• Structure hints (e.g., "Subject + Verb + Object")
• Monospace font for clarity

Translation exercises and word scramble challenges with helpful hints

6. 🎯 Desafío Semanal (Weekly Challenge)

• Practical, achievable task
• Related to the week's grammar topic
• Example: "Write 3 sentences about your day using Present Simple"

7. 🔑 Soluciones (Solutions)

• Complete answers to all exercises
• Grammar exercise solution
• All 3 translations
• Both word scrambles solved
• Example challenge response

8. 📜 Cita de la Semana (Quote of the Week)

• Best quote from the week's lessons
• Original author attribution
• Spanish translation
• Centered, elegant typography

Footer

• Motivational message: "Keep learning, keep growing 🌱"
• Attribution link (customizable)

Example HTML Output

Here's a snippet showing the vocabulary section HTML:

<div style="margin-bottom: 24px; padding-bottom: 16px; border-bottom: 1px dashed #EEF2F7;">
    <div style="margin-bottom: 6px;">
        <span style="color: #2C7BE5; font-weight: 700; font-size: 18px; font-family: Georgia, serif;">
            PRACTICE
        </span>
        <span style="color: #FF6B6B; font-family: 'Courier New', monospace; font-weight: 600; font-size: 15px; margin-left: 10px;">
            /práctis/
        </span>
    </div>
    <div style="color: #555555; font-size: 16px; line-height: 1.8; font-family: 'Trebuchet MS', sans-serif;">
        práctica
    </div>
    <div style="margin-top: 8px; padding-left: 12px; border-left: 3px solid #D0E6FF; color: #556677; font-style: italic; font-size: 15px;">
        Practice makes perfect (La práctica hace al maestro)
    </div>
</div>

Workflow Nodes

Detailed breakdown of each node in the workflow:

1. Schedule - Domingo 9AM (Schedule Trigger)

• Type: Schedule Trigger
• Function: Executes the workflow weekly on Sundays at 9 AM
• Customizable: Change day, time, and frequency in node settings
• Output: Trigger signal (no data)

2. Leer Historial Quotes (Read History)

• Type: Google Sheets
• Function: Fetches all rows from the daily quotes history sheet
• Configuration:
  • Document ID: Your Google Sheet
  • Sheet: Sheet 1 (gid=0)
  • Operation: Read
• Output: Array of all lesson rows with columns: Fecha, Cita, Autor, Contenido Email

3. Preparar Contexto Semanal (Prepare Weekly Context)

• Type: Code (JavaScript)
• Function: Takes the last 6 lessons and formats them as AI input context
• Logic:
  • Slices last 6 rows from history
  • Builds formatted text with lesson date, quote, and full content
  • Creates context string for AI
• Output: Object with context (formatted text) and lessonCount (number)

4. Generar Lección Semanal (Generate Weekly Lesson)

• Type: Google Gemini (LangChain)
• Function: Sends context to AI and receives structured JSON lesson
• Configuration:
  • Model: gemini-3-flash-preview
  • Messages: System prompt + user context
• Critical: Requires custom prompt (see Customization section)
• Output: AI response with content.parts[0].text containing JSON

5. Parser y Limpieza (Parser & Validation)

• Type: Code (JavaScript)
• Function: Validates and cleans AI output
• Validation Steps:
  1. Checks for content existence
  2. Removes markdown code blocks if present
  3. Parses JSON
  4. Validates all required fields exist
  5. Checks array lengths (translation = 3, wordScramble = 2)
  6. Provides fallback values for missing/empty fields
• Error Handling: Returns error object if parsing fails
• Output: Validated JSON object with all required fields

6. Formateadores (Formatters)

• Type: Code (JavaScript)
• Function: Converts JSON data into formatted HTML strings
• Includes:
  • Color system definition
  • Formatter functions for each content type
  • HTML generation for vocab, grammar, dialogue, exercises, etc.
• Output: Object with formatted HTML strings for each section

7. Generador HTML (HTML Generator)

• Type: Code (JavaScript)
• Function: Assembles complete HTML email document
• Components:
  • Header with gradient and title
  • Content sections (intro, vocab, grammar, etc.)
  • Footer with attribution
• Error Handling: Generates error email if previous nodes failed
• Output: Complete HTML email in htmlContent field

8. Enviar Email Semanal (Send Weekly Email)

• Type: Gmail
• Function: Sends the formatted email
• Configuration:
  • To: Main recipient
  • BCC: Additional recipients (optional)
  • Subject: "🎓 Tu Masterclass Semanal de Inglés"
  • Body: HTML content from previous node
• Retry Logic: 3 attempts with 5-second delays

9. Guardar Lección Semanal (Save Weekly Lesson)

• Type: Google Sheets
• Function: Archives the lesson content to Sheet 2
• Columns Saved:
  • Fecha: Current date
  • Introduccion: Intro text
  • Vocabulario: Vocab JSON array (stringified)
  • Grammar Focus: Grammar object (stringified)
  • Dialogo: Dialogue array (stringified)
  • Desafio: Challenge text
• Retry Logic: 3 attempts with 5-second delays

Troubleshooting

Common Issues and Solutions

Issue: "No se recibió contenido del modelo de IA"

Cause: Gemini API returned empty response Solutions:

• Check your Gemini API credentials
• Verify API key is valid and has quota remaining
• Check if Gemini API is experiencing outages
• Review the AI prompt - it might be too complex or malformed

Issue: "Error al parsear JSON"

Cause: AI returned invalid JSON or included markdown Solutions:

• Review your prompt - ensure it explicitly says "NO markdown" and "ONLY JSON"
• Add examples of correct JSON format in your prompt
• Check if the model you're using supports JSON mode
• Inspect the rawContent in error output to see what AI actually returned

Issue: Email not sending

Cause: Gmail credentials invalid or quota exceeded Solutions:

• Re-authorize Gmail OAuth2 credentials
• Check Gmail sending limits (500/day for regular accounts)
• Verify the email address in "sendTo" is correct
• Check spam folder

Issue: Google Sheets not updating

Cause: Sheets credentials invalid or Sheet structure mismatch Solutions:

• Re-authorize Google Sheets OAuth2 credentials
• Verify Sheet ID in both nodes matches your actual Google Sheet
• Ensure Sheet 1 has columns: Fecha, Cita, Autor, Contenido Email
• Ensure Sheet 2 has columns: Fecha, Introduccion, Vocabulario, Grammar Focus, Dialogo, Desafio
• Check that gid values match your sheet structure

Issue: "exercises.translation debe tener exactamente 3 items"

Cause: AI generated wrong number of translation exercises Solutions:

• Make your prompt more explicit: "EXACTLY 3 translation exercises"
• Add validation rules to your prompt
• Provide examples in your prompt showing arrays with 3 items
• Consider adding retry logic to regenerate if validation fails

Issue: Workflow times out

Cause: AI taking too long to generate content Solutions:

• Increase timeout in Gemini node settings
• Simplify your AI prompt to reduce processing time
• Switch to a faster Gemini model (e.g., flash instead of pro)
• Check n8n execution timeout settings

Issue: Formatting looks broken in email

Cause: Email client doesn't support certain CSS Solutions:

• Test email in multiple clients (Gmail, Outlook, Apple Mail)
• Use inline styles only (already implemented)
• Avoid advanced CSS features
• Use table-based layout (already implemented)
• Check for unclosed HTML tags in custom content

Issue: Vocabulary/exercises are empty

Cause: Parser fallback values being used due to AI output issues Solutions:

• Review AI prompt for clarity on required content
• Check if context from history is being passed correctly
• Inspect "Preparar Contexto" node output to verify lesson data
• Add more specific instructions for each content type

Technologies Used

• n8n - Workflow automation platform
• Google Gemini (3 Flash Preview) - AI content generation
• Google Sheets API - Data storage and retrieval
• Gmail API - Email delivery
• JavaScript (ES6+) - Custom code nodes for data transformation
• HTML5 & CSS3 - Email template design
• OAuth2 - Secure API authentication

Disclaimer

⚠️ Proprietary Content Notice

This workflow uses a placeholder prompt for the AI content generation. The original project uses proprietary prompt engineering techniques developed specifically for language teaching, including:

• Detailed pedagogical strategies
• Specific curriculum syllabus (Headway Beginner units)
• Advanced prompt optimization
• Custom JSON structure validation rules

You must replace the placeholder with your own custom prompt that matches your:

• Teaching methodology
• Target audience and language level
• Content goals and structure
• Quality standards

The JSON structure and workflow architecture are provided as-is, but the quality and effectiveness of your lessons will depend entirely on your prompt engineering skills.

Contributing

Contributions are welcome! Here's how you can help:

1. Report Bugs: Open an issue with:

   • Clear description of the problem
   • Steps to reproduce
   • Expected vs. actual behavior
   • n8n version and environment details

2. Suggest Features: Open an issue with:

   • Feature description
   • Use case and benefits
   • Possible implementation approach

3. Submit Pull Requests:

   • Fork the repository
   • Create a feature branch
   • Make your changes
   • Test thoroughly
   • Submit PR with clear description

Areas for Contribution

• Multi-language support - Adapt for other languages
• Alternative AI models - Integration with OpenAI, Claude, etc.
• Enhanced email designs - New templates and themes
• Advanced exercises - New exercise types and formats
• Mobile app integration - Push notifications instead of email
• Progress tracking - Dashboard for learning analytics
• A/B testing - Experiment with different teaching approaches

License

MIT License - See LICENSE file for details.

This means you can:

• ✅ Use commercially
• ✅ Modify and distribute
• ✅ Use privately
• ✅ Sublicense

Requirements:

• Include original license and copyright notice
• No liability or warranty provided

Support

Documentation

• Full workflow walkthrough in this README
• Inline comments in all Code nodes
• Detailed node descriptions

Community

• Issues: Report bugs or request features via GitHub Issues
• Discussions: Share tips and ask questions

Resources

• n8n Documentation
• Google Gemini API Docs
• n8n Community Forum

---

Built with ❤️ for language learners everywhere

Transform your English learning with AI-powered weekly masterclasses 🚀