Pulse Email Tasks
Relevant source files
The following files were used as context for generating this wiki page:
Pulse Email Tasks are automated background workers designed to generate and deliver daily personalized email digests to Recoup users. These digests, referred to as "Pulses," aggregate relevant artist insights, social media statistics, and context from connected productivity applications like Google Drive and Slack. The system leverages Trigger.dev v4 for orchestration and isolated sandboxes for content execution.
The primary goal of the Pulse system is to surface the most relevant information for music industry professionals, such as trending social metrics for specific artists or unfinished work mentioned in recent conversations.
Sources: src/tasks/sendPulsesTask.ts:1-125, README.md:32-34
System Architecture
The Pulse system operates through a two-tier task structure. A parent task identifies eligible accounts, while individual child tasks manage the generation and tracking for each specific user.
Orchestration Flow
The following diagram illustrates the high-level flow from the scheduled trigger to individual pulse execution.
The system uses a parent-child pattern to ensure that failures in one user's pulse generation do not interrupt the processing of others in the daily batch.
Sources: src/tasks/sendPulsesTask.ts:133-176, src/tasks/sendPulseTask.ts:11-28
Task Definitions
| Task Name | Trigger | Description |
|---|---|---|
sendPulsesTask | Daily Cron (9 AM ET) | Coordinates the daily dispatch by fetching all accounts with active pulse subscriptions and triggering batch sub-tasks. |
sendPulseTask | Batch Trigger | Executes the pulse logic for a single account within an isolated sandbox environment. |
Sources: src/tasks/sendPulsesTask.ts:133-135, src/tasks/sendPulseTask.ts:11-13, README.md:32-34
Data Gathering and Logic
Pulse generation follows a strict multi-step logic defined in the DEFAULT_PULSE_PROMPT. This prompt guides an AI agent through context gathering and prioritization.
Priority Determination
Artists are categorized as "High Priority" based on two primary data sources:
- Recent Conversations: Discussed in the past 7 days, unfinished work mentioned, or deadlines highlighted.
- Artist Data: Recent releases or upcoming release dates.
Sources: src/tasks/sendPulsesTask.ts:13-33
Service Integration
If a user has connected external services, the system performs deeper analysis using specific tools:
- Composio: Searches Google Drive, Docs, and Sheets for marketing plans or strategy documents related to priority artists.
- Social Stats: Fetches metric changes via
get_artist_socialsonly for the identified top 1-3 artists. - Google Images: Retrieves a relevant artist image for visual inclusion in the email.
Sources: src/tasks/sendPulsesTask.ts:36-54
Execution Environment
Individual pulses are executed using executePulseInSandbox, which provides an isolated Linux microVM for running the pulse logic.
Sandbox Execution Sequence
After the sandbox completes its run, the tagPulseEmailId function is called to associate the sandbox execution with the specific email identifier for auditing and delivery tracking.
Sources: src/tasks/sendPulseTask.ts:16-24, src/pulse/tests/executePulseInSandbox.test.ts:31-48
Email Formatting and Structure
The Pulse email is generated as a responsive HTML document with strict conditional rendering rules to avoid broken layouts or missing data.
Formatting Rules
- Images: The
<img>block is only included if a valid URL is returned fromgoogle_images. - Chat Links: Links to specific conversations are only rendered if the insight was derived from a chat.
- Insights: Insights must be actionable and include real numbers where available; vague summaries are explicitly forbidden.
Sources: src/tasks/sendPulsesTask.ts:65-115
Data Structure for Pulse Email
| Element | Logic |
|---|---|
| Subject Line | Must be specific (e.g., "Artist X release is up 23%"). |
| Personal Greeting | Uses user's name if available. |
| Insight Block | Limited to maximum 3 priority items. |
| Fallback | Searches music industry news if no specific artist activity is found. |
Sources: src/tasks/sendPulsesTask.ts:56-61, src/tasks/sendPulsesTask.ts:117-123
Summary
The Pulse Email system is a sophisticated integration of scheduled tasks, AI-driven prioritization, and multi-service data fetching. By utilizing sendPulsesTask to manage batch processing and sendPulseTask for isolated execution, the system ensures reliable delivery of high-value, data-backed insights tailored to individual music industry professionals.
Sources: src/tasks/sendPulsesTask.ts:175-180, src/tasks/sendPulseTask.ts:24-28