Relevant source files

The following files were used as context for generating this wiki page: - [apps/api/src/app/email/services/send-email.service.ts](https://github.com/sweetr-dev/sweetr.dev/blob/main/apps/api/src/app/email/services/send-email.service.ts) - [apps/api/src/app/email/workers/send-email.worker.ts](https://github.com/sweetr-dev/sweetr.dev/blob/main/apps/api/src/app/email/workers/send-email.worker.ts) - [packages/email-templates/src/emails/initial-sync-complete.tsx](https://github.com/sweetr-dev/sweetr.dev/blob/main/packages/email-templates/src/emails/initial-sync-complete.tsx) - [packages/email-templates/package.json](https://github.com/sweetr-dev/sweetr.dev/blob/main/packages/email-templates/package.json) - [packages/graphql-types/frontend/gql.ts](https://github.com/sweetr-dev/sweetr.dev/blob/main/packages/graphql-types/frontend/gql.ts)

# Email Service & Templates The Email Service & Templates system in Sweetr is responsible for managing, rendering, and delivering transactional emails to users. It utilizes a decoupled architecture where email templates are defined as React components in a dedicated package, and delivery is handled via a background worker process using BullMQ. The system ensures that communications such as workspace sync notifications and onboarding instructions are delivered reliably. It integrates with external providers (like Resend) for actual SMTP/API transmission while providing local mechanisms for template previewing and environment-based delivery routing. Sources: [apps/api/src/app/email/services/send-email.service.ts](), [apps/api/src/app/email/workers/send-email.worker.ts](), [packages/email-templates/package.json]() ## Architecture and Data Flow The email system is split into three primary layers: Template Definition, Enqueueing, and Execution. This separation allows the application to respond quickly to user actions while offloading the heavy lifting of rendering and network communication to background workers. ### Email Lifecycle Flow The following diagram illustrates the path of an email from an application event to final delivery. ```mermaid flowchart TD A[App Logic] -->|enqueueEmail| B[BullMQ: SEND_EMAIL Queue] B --> C[Email Worker] C --> D{Render Template} D --> E[Email Client/Resend] E --> F[Recipient] ``` The flow begins in the application logic, which enqueues a job. The worker then picks up the job, renders the React-based template into HTML, and sends it via the email client. Sources: [apps/api/src/app/email/services/send-email.service.ts:16-27](), [apps/api/src/app/email/workers/send-email.worker.ts:16-30]() ## Service Layer The `send-email.service.ts` file provides the primary interface for interacting with the email system. It includes methods for both immediate delivery and background queueing. ### Key Service Functions | Function | Purpose | Key Logic | | :--- | :--- | :--- | | `enqueueEmail` | Adds an email job to the BullMQ queue. | Checks `env.EMAIL_ENABLED` before adding to `SweetQueue.SEND_EMAIL`. | | `sendEmail` | Directly sends an email using the email client. | Routes to `delivered@resend.dev` if not in production. | | `markEmailAsSent` | Records an email transmission in Redis. | Uses `redisConnection.setex` with a TTL. | | `hasSentEmail` | Checks if an email was already sent. | Uses `redisConnection.exists`. | Sources: [apps/api/src/app/email/services/send-email.service.ts:16-64]() ### Delivery Configuration The service layer includes environment-specific routing logic. In production, emails are sent to the intended recipient, whereas in non-production environments, all emails are rerouted to a testing address. ```typescript const to = isProduction ? payload.to : "delivered@resend.dev"; const { data, error } = await client.emails.send({ from: "Walter from sweetr.dev ", ...payload, to, }); ``` Sources: [apps/api/src/app/email/services/send-email.service.ts:38-48]() ## Worker Layer The `sendEmail.worker.ts` acts as the consumer for the `SEND_EMAIL` queue. It is responsible for taking the abstract template reference and raw data from a job and transforming them into a deliverable format. ### Rendering Process The worker uses `renderEmailTemplate` from the `@sweetr/email-templates` package. It maps a template type string to the actual React component stored in the service's template registry. ```mermaid sequenceDiagram participant Q as SweetQueue participant W as SendEmailWorker participant T as EmailTemplates participant S as SendEmailService Q->>W: Process Job (Template Type, Props) W->>T: renderEmailTemplate(Component, Props) T-->>W: HTML/Subject Data W->>S: sendEmail(RenderedContent) S-->>W: Delivery Success/Failure ``` Sources: [apps/api/src/app/email/workers/send-email.worker.ts:16-30]() ## Email Templates Templates are housed in a standalone workspace package `@sweetr/email-templates`. They are built using `@react-email/components`, allowing developers to use React and Tailwind-like styling for email design. ### Available Templates Currently, the system defines specific templates for workspace events: * **Initial Sync Complete**: Notifies the user that their GitHub metadata has been successfully indexed. * **Props**: `username` (string), `createTeamLink` (string, optional). * **Component**: `InitialSyncCompleteEmail`. Sources: [packages/email-templates/src/emails/initial-sync-complete.tsx:6-12](), [apps/api/src/app/email/services/send-email.service.ts:10]() ### Template Implementation Example Templates utilize a shared `` component and standardized typography from the `@react-email` library. ```tsx export const InitialSyncCompleteEmail = ({ username, createTeamLink = "https://app.sweetr.dev/teams", }: InitialSyncCompleteProps) => { return ( Your workspace data is ready. Hello {username}, ); }; ``` Sources: [packages/email-templates/src/emails/initial-sync-complete.tsx:11-34]() ## Configuration and Dependencies The system relies on several environment variables and packages for operation. ### Environment Variables * `EMAIL_ENABLED`: A boolean flag to enable or disable the entire email subsystem. * `RESEND_API_KEY`: Required by the email client for transmission (implied by the use of `getEmailClient`). ### Package Dependencies | Package | Version | Purpose | | :--- | :--- | :--- | | `@react-email/components` | 0.5.0 | UI components for email templates. | | `react-email` | 4.2.8 | Local development server for previewing emails. | | `bullmq` | - | Queue management and worker execution. | Sources: [packages/email-templates/package.json:20-22](), [apps/api/src/app/email/services/send-email.service.ts:17-21]() ## Conclusion The Email Service & Templates system provides a robust, scalable way to handle user communications in Sweetr. By leveraging React for templates and BullMQ for asynchronous processing, the system ensures high-quality email rendering without impacting the performance of the main API.