Pulse Emails Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Pulse Emails Integration is a specialized module within the Recoup Admin dashboard designed to track, retrieve, and preview automated "Pulse" emails sent to users via the Resend platform. It connects background task executions (specifically the send-pulse-task) with actual email delivery records, allowing administrators to audit the communication sent to specific accounts.
This system provides a seamless bridge between the internal task runner and the external Resend API, surfacing metadata such as recipient lists, subject lines, and the full rendered HTML content of the emails within the admin interface.
System Architecture and Data Flow
The integration operates by identifying specific task runs labeled as send-pulse-task. When an administrator selects a task run, the system extracts a unique email identifier from the task tags and fetches the corresponding email data from the Recoup API, which proxies requests to Resend.
Data Acquisition Flow
The following sequence diagram illustrates how a user interaction triggers the retrieval of email content:
Key Components
UI Components
The user interface is centered around a modal-based previewer that renders the email content in a sandboxed environment.
- PulseEmailModal: The primary container that manages the visibility and data fetching state for a specific email. Sources: components/AccountDetail/PulseEmailModal.tsx:16-52
- PulseEmailModalHeader: Displays the email subject, recipient list, and the creation timestamp. Sources: components/AccountDetail/PulseEmailModalHeader.tsx:11-44
- PulseEmailModalBody: Handles the rendering logic. It uses an
iframewithsrcDocto safely display HTML content or a fallback message for text-only emails. Sources: components/AccountDetail/PulseEmailModalBody.tsx:21-59
Logic and Hooks
- usePulseEmail: A custom React Query hook that handles authentication via Privy and fetches email details based on an email ID. Sources: hooks/usePulseEmail.ts:10-24
- fetchAccountPulseEmails: A utility that retrieves all emails associated with a specific account ID. Sources: lib/recoup/fetchAccountPulseEmails.ts:31-51
Data Structures
The system relies on the PulseEmail interface, which maps directly to the Resend API success response.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier (Resend ID) |
from | string | Sender email address |
to | string[] | Primary recipient list |
subject | string | Email subject line |
html | string | null | The full HTML content for preview |
created_at | string | ISO timestamp of creation |
tags | object[] | Custom metadata tags (e.g., name/value pairs) |
Sources: lib/recoup/fetchAccountPulseEmails.ts:8-21
Implementation Details
Task Integration
Pulse emails are linked to system tasks through specific identifiers. In the AccountDetailPage, task runs are filtered to isolate "Pulse" events:
// Filtering logic for Pulse tasks
const pulseRuns = runs?.filter(r => r.taskIdentifier === "send-pulse-task") ?? [];
Sources: components/AccountDetail/AccountDetailPage.tsx:23
Secure Rendering
To prevent CSS leakage or script execution from the email content into the admin dashboard, the PulseEmailModalBody implements a sandboxed iframe:
<iframe
srcDoc={email.html}
title="Email preview"
sandbox="allow-same-origin"
className="w-full border-0"
style={{ minHeight: "500px" }}
/>
Sources: components/AccountDetail/PulseEmailModalBody.tsx:43-49
Conclusion
The Pulse Emails Integration provides a critical audit trail for the Recoup platform. By mapping background task identifiers to Resend email records, it enables administrators to verify exactly what was sent to users, ensuring transparency and aiding in the debugging of automated communication workflows.