Behavioral Email Trigger Agent for WooCommerce Merchants

Send personalized emails based on real-time browsing and cart behavior, not calendar dates.

woocommerce email-automation behavioral-triggers nextjs hono knowledge-agent ecommerce llm-agents

The problem

The marketing contractor at a $3M WooCommerce store relies on a fixed weekly email schedule, missing opportunities to re-engage shoppers who abandon carts or browse specific categories. Without behavioral triggers, they waste budget on irrelevant campaigns and fail to convert high-intent visitors. The contractor has no time to manually monitor analytics and set up complex automation rules. This results in lost revenue and a poor ROI on email marketing spend.

Built from

Intro

Build a behavioral email trigger agent for WooCommerce that replaces calendar-based email schedules with real-time, LLM-driven decisions. When a shopper views a product, abandons a cart, or places an order, this agent classifies the event, stores it in long-term memory, decides which email to send, and enqueues it for delivery via Klaviyo. You’ll wire five REAA packages into a Next.js 16 App Router project, using Vercel AI SDK for LLM calls, Upstash QStash for durable queuing, and Langfuse for observability. This tutorial is for TypeScript developers familiar with Next.js who want to see how LLMs, agent memory, and email APIs combine into an ecommerce automation pipeline.

Prerequisites

Node.js >= 22 and pnpm 10 installed
An OpenAI API key (for LLM calls and embeddings)
A Klaviyo account with an API key
An Upstash account with QStash token and signing keys
(Optional) Langfuse public and secret keys for tracing
A WooCommerce webhook secret for HMAC verification

Step 1: Scaffold the project and install dependencies

Start from an empty directory. You’ll use the Next.js App Router with exact-pinned dependencies.

terminal

mkdir behavioral-email-trigger && cd behavioral-email-trigger

The scaffold includes a package.json with all dependencies already exact-pinned. Verify the key ones are in place:

terminal

cat

Example artifact

A complete, working implementation of this recipe — downloadable as a zip or browsable file by file. Generated by our build pipeline; tested with full coverage before publishing.

Download example (zip)Browse files

183 kB·76 tests·96.7% coverage·vitest passing

SHA-2568bacb230798cf84ec8a75212089012458832a984ad7ec6d0fff3982bc1dfb856

Book a conversation All solutions

Comments

Loading comments…

Intro

Prerequisites

Node.js >= 22 and pnpm 10 installed
An OpenAI API key (for LLM calls and embeddings)
A Klaviyo account with an API key
An Upstash account with QStash token and signing keys
(Optional) Langfuse public and secret keys for tracing
A WooCommerce webhook secret for HMAC verification

Step 1: Scaffold the project and install dependencies

Start from an empty directory. You’ll use the Next.js App Router with exact-pinned dependencies.

terminal

mkdir behavioral-email-trigger && cd behavioral-email-trigger

The scaffold includes a package.json with all dependencies already exact-pinned. Verify the key ones are in place:

terminal

cat

import { AgentMemory, OpenAILLMProvider, MemoryType, } from "@reaatech/agent-memory"; import { ContextInjector } from "@reaatech/agent-memory-retrieval"; import { type Memory, type ConversationTurn, MemoryImportance, } from "@reaatech/agent-memory-core"; import type { BehaviorEvent } from "../types/behavior-events.js"; import { type BehaviorProfile, emptyProfile, } from "../types/memory-context.js"; export class BehaviorMemoryService { private readonly agentMemory: AgentMemory; private readonly contextInjector: ContextInjector; constructor(apiKey: string) { this.agentMemory = new AgentMemory({ storage: { provider: "memory" }, embedding: { provider: "openai", model: "text-embedding-3-small", apiKey, }, extraction: { llmProvider: new OpenAILLMProvider({ apiKey, model: "gpt-4o-mini", }), enabledTypes: [ MemoryType.FACT, MemoryType.PREFERENCE, MemoryType.CORRECTION, ], batchSize: 10, confidenceThreshold: 0.7, }, }); this.contextInjector = new ContextInjector(); } async storeBehaviorEvent(event: BehaviorEvent): Promise<void> { const turns: ConversationTurn[] = [ { speaker: "user", content: JSON.stringify(event), timestamp: new Date(event.timestamp), }, ]; await this.agentMemory.extractAndStore(turns); } async retrieveCustomerProfile(email: string): Promise<BehaviorProfile> { const memories = await this.agentMemory.retrieve(email, { limit: 20 }); if (memories.length === 0) { return emptyProfile(email); } const profile: BehaviorProfile = { customerEmail: email, preferredCategories: [], abandonedCartCount: 0, avgOrderValue: 0, lastActiveAt: new Date(), totalPageViews: 0, inferredInterests: [], recentOrders: [], }; for (const mem of memories) { if (mem.type === MemoryType.PREFERENCE && mem.category) { profile.preferredCategories.push(mem.category); } if ( mem.importance === MemoryImportance.HIGH && mem.content.includes("order") ) { profile.abandonedCartCount++; } if (mem.lastAccessedAt > profile.lastActiveAt) { profile.lastActiveAt = mem.lastAccessedAt; } if (mem.content.includes("page_view")) { profile.totalPageViews++; } if (mem.category && !profile.inferredInterests.includes(mem.category)) { profile.inferredInterests.push(mem.category); } } profile.preferredCategories = [...new Set(profile.preferredCategories)]; return profile; } async formatMemoriesForLLM( memories: Memory[], tokenBudget: number, ): Promise<string> { return this.contextInjector.injectMemoriesIntoContext( [], memories, tokenBudget, ); } async runMaintenance(): Promise<void> { await this.agentMemory.runMaintenance(); } }

import type { LlmClient } from "../lib/llm.js"; import type { BehaviorEvent } from "../types/behavior-events.js"; import { EmailDecisionSchema, type EmailDecision, } from "../types/email-templates.js"; import type { BehaviorProfile } from "../types/memory-context.js"; export interface DecisionResult { success: boolean; decision?: EmailDecision; error?: string; } const TRIGGER_RULES = "Rules:\n" + "1. cart_add or checkout_started with cartTotal > $100 and no recent order → abandoned_cart (priority 4-5)\n" + "2. product_view in a category the customer has purchased from before → category_reengagement (priority 3-4)\n" + "3. 5+ page_view events, no cart_add → browse_abandonment (priority 2-3)\n" + "4. Returning customer with 3+ orders and high AOV (>$75) → high_value_alert (priority 4)\n" + "5. New customer with first page_view → welcome_series (priority 1)\n" + "6. Recent order_placed → post_purchase_followup (priority 3)\n" + "Return a JSON with triggerType, customerEmail, templateId, personalizationVars, priority (1-5), and reason."; export class EmailDecisionService { private readonly llmClient: LlmClient; constructor(llmClient: LlmClient) { this.llmClient = llmClient; } async decide( event: BehaviorEvent, profile: BehaviorProfile, ): Promise<DecisionResult> { try { const systemPrompt = "You are an email trigger decision engine for WooCommerce. " + "Given a customer behavior event and their profile, determine the best email to send.\n" + TRIGGER_RULES; const prompt = JSON.stringify({ event, profile }); const { object } = await this.llmClient.generateStructured({ system: systemPrompt, prompt, schema: EmailDecisionSchema, }); const decision = EmailDecisionSchema.parse(object); return { success: true, decision }; } catch (error) { return { success: false, error: String(error), }; } } }

import type { BehaviorClassifierService } from "./behavior-classifier-service.js"; import type { BehaviorMemoryService } from "./behavior-memory-service.js"; import type { QstashClient } from "../lib/qstash.js"; import { verifyWooCommerceSignature } from "../lib/webhook-validator.js"; export interface IngestResult { accepted: boolean; eventId?: string; error?: string; duplicate?: boolean; } export class WebhookIngestionService { private readonly classifier: BehaviorClassifierService; private readonly memory: BehaviorMemoryService; private readonly qstash: QstashClient; private readonly webhookSecret: string; private readonly processedIds: Map<string, number>; constructor( classifier: BehaviorClassifierService, memory: BehaviorMemoryService, qstash: QstashClient, webhookSecret: string, ) { this.classifier = classifier; this.memory = memory; this.qstash = qstash; this.webhookSecret = webhookSecret; this.processedIds = new Map(); } async ingest( payload: unknown, signature: string, ): Promise<IngestResult> { let rawPayload: Record<string, unknown>; try { rawPayload = payload as Record<string, unknown>; } catch { return { accepted: false, error: "Invalid payload format" }; } const bodyString = JSON.stringify(rawPayload); if (!verifyWooCommerceSignature(bodyString, signature, this.webhookSecret)) { return { accepted: false, error: "Invalid signature" }; } const eventId = rawPayload["id"] as string | number | undefined; if (eventId !== undefined) { const eventKey = String(eventId); const now = Date.now(); const ttl = 300_000; if (this.processedIds.has(eventKey)) { const stored = this.processedIds.get(eventKey); if (stored !== undefined && now - stored < ttl) { return { accepted: true, eventId: eventKey, duplicate: true }; } } this.processedIds.set(eventKey, now); } const classification = await this.classifier.classifyEvent(rawPayload); if (!classification.success || !classification.event) { return { accepted: false, error: classification.error ?? "Classification failed", }; } await this.memory.storeBehaviorEvent(classification.event); try { await this.qstash.enqueueBehaviorEvent(classification.event); } catch (error) { return { accepted: false, error: `queue unavailable: ${error instanceof Error ? error.message : String(error)}`, }; } const id = eventId !== undefined ? String(eventId) : crypto.randomUUID(); return { accepted: true, eventId: id }; } }

import { type NextRequest, NextResponse } from "next/server"; import { WebhookIngestionService } from "../../../../src/services/webhook-ingestion-service.js"; import { BehaviorClassifierService } from "../../../../src/services/behavior-classifier-service.js"; import { BehaviorMemoryService } from "../../../../src/services/behavior-memory-service.js"; import { QstashClient } from "../../../../src/lib/qstash.js"; import { LlmClient } from "../../../../src/lib/llm.js"; import { parseConfig } from "../../../../src/lib/config.js"; let ingestionService: WebhookIngestionService | null = null; function getService(): WebhookIngestionService { if (!ingestionService) { const config = parseConfig(); const llm = new LlmClient(); const classifier = new BehaviorClassifierService(llm); const memory = new BehaviorMemoryService(config.openaiApiKey); const qstash = new QstashClient( config.qstashToken, config.qstashCurrentSigningKey, config.qstashNextSigningKey, ); ingestionService = new WebhookIngestionService( classifier, memory, qstash, config.woocommerceWebhookSecret, ); } return ingestionService; } export async function POST(req: NextRequest): Promise<NextResponse> { const rawBody = await req.text(); if (!rawBody) { return NextResponse.json({ error: "Missing body" }, { status: 400 }); } let payload: unknown; try { payload = JSON.parse(rawBody); } catch { return NextResponse.json( { error: "Invalid JSON body" }, { status: 400 }, ); } const signature = req.headers.get("x-wc-webhook-signature") ?? ""; const service = getService(); const result = await service.ingest(payload, signature); if (!result.accepted && result.error === "Invalid signature") { return NextResponse.json(result, { status: 401 }); } if (!result.accepted) { return NextResponse.json(result, { status: 502 }); } return NextResponse.json(result, { status: 200 }); }

Behavioral Email Trigger Agent for WooCommerce Merchants

The problem

Built from

Intro

Prerequisites

Step 1: Scaffold the project and install dependencies

Example artifact

Comments

Intro

Prerequisites

Step 1: Scaffold the project and install dependencies

Step 2: Set up environment variables

Step 3: Define the Zod-validated type layer

Step 4: Build the environment config loader

Step 5: Build the integration clients

Step 6: Build the behavior memory service

Step 7: Build the classifier and decision services

Step 8: Build the webhook ingestion service

Step 9: Build the trigger executor and MCP service

Step 10: Wire up Next.js API routes

Step 11: Set up instrumentation and landing page

Step 12: Write tests

Step 13: Run the tests

Next steps