Email Reply Agent
Relevant source files
The following files were used as context for generating this wiki page:
The Email Reply Agent is a specialized component of the Recoup AI system designed to facilitate seamless communication between users and the AI via email. It acts as an orchestrator that processes inbound emails, maintains conversation continuity through threading, and generates contextually aware responses using the project's core AI logic.
The agent's primary scope includes transforming standard email interactions into structured chat sessions within the Recoup platform. This ensures that a conversation started over email can be continued on the web interface without losing history or context.
Sources: features/feature-email-client.md:3-11, lib/emails/inbound/generateEmailResponse.ts:13-21
System Architecture
The Email Reply Agent operates within the inbound email pipeline, triggered by webhooks from external services like Resend. It leverages several internal modules to validate senders, retrieve historical context, and generate formatted responses.
Data Flow Overview
When an email is received, the system follows a structured path to generate a reply:
- Webhook Reception: Resend sends an
email.receivedevent to the API. - Context Retrieval: The system maps the email thread to a specific
roomId. - Agent Initialization: The
generalAgentis instantiated with specific system prompts and tool access. - Response Generation: The AI generates a text response based on the conversation history.
- Formatting & Delivery: The response is converted to HTML, a standardized footer is appended, and the email is sent back to the user.
Core Components
1. Inbound Processing logic
The system uses the References header in incoming emails to maintain thread continuity. By looking up these references in the memory_emails table, it can map an email reply back to its original roomId.
Sources: features/feature-email-client.md:175-195
2. General Agent Integration
The Email Reply Agent utilizes the getGeneralAgent function to create a ToolLoopAgent. This agent is configured with the SYSTEM_PROMPT which defines its personality as a "strategic AI assistant for the music industry."
Sources: lib/chat/const.ts:3-10, lib/agents/generalAgent/tests/getGeneralAgent.test.ts:70-85
3. CC and Reply Logic
The system includes logic to handle complex email scenarios, such as when the Recoup email address is included in the CC field rather than the TO field. The validateCcReplyExpected function determines if a reply is necessary or if the email is merely an "FYI."
Sources: lib/emails/inbound/tests/validateCcReplyExpected.test.ts:38-70
| Component | Responsibility | Relevant Files |
|---|---|---|
generateEmailResponse | Orchestrates the full generation of the reply HTML. | generateEmailResponse.ts |
getEmailRoomMessages | Retrieves historical memories for the specific room. | getEmailRoomMessages.ts |
getGeneralAgent | Sets up the AI model and tool environment. | getGeneralAgent.ts |
validateCcReplyExpected | Decides if a response is required based on email headers. | validateCcReplyExpected.ts |
Response Generation Logic
The generation of an email response involves converting markdown text produced by the AI into a readable HTML format, while also ensuring that the user has a path to transition to the web interface.
The Standardized Footer
Every email generated by the agent includes a footer designed for cross-platform seamlessness. This footer contains:
- A note that the user can reply directly to the email.
- A direct link to the conversation on the Recoup web app (e.g.,
https://chat.recoupable.com/chat/${roomId}). - Optional context if the conversation is within a specific artist's workspace.
Sources: lib/emails/tests/getEmailFooter.test.ts:5-45
AI Personality and Constraints
The agent follows a "Sandbox-First" approach, preferring the prompt_sandbox tool for complex tasks like data analysis or report generation. Its communication style is designed to be:
- Brief by default: Expanding only when necessary.
- Strategic: Focused on next steps and monetization paths for artist teams.
- Transparent: Avoiding technical jargon like "root directory" or "storage keys."
Sources: lib/chat/const.ts:13-25, 45-55
Duplicate Prevention (Idempotency)
To prevent users from receiving multiple replies for the same email (due to webhook retries), the system uses the Resend email_id as a unique identifier in the memories table. If a duplicate email_id is detected during insertion, the database returns a unique constraint error (code 23505), and the system halts the redundant response.
Sources: features/feature-email-client.md:215-235
The Email Reply Agent effectively bridges the gap between traditional asynchronous email communication and modern AI-driven chat, ensuring consistency across all user touchpoints.