feat(emails): pivot to a simpler version of email sending functionality

[benjaminpaige]

🎫 Linked Ticket

Ticket to close

💬 Description / Notes

This change adds additional functionality to the email sending process for initial and subsequent submissions.

I think RespondToRAIWithdrawal is still missing, but it can be a follow-up. The code in this section is changing quickly, so I'd like to get this code in and tested so it doesn't have to keep being updated from changes that are made to the transform and sync functionality.

Overview

This changeset introduces functionality that sends email notifications to both state and CMS users when specific initial workflow events occur during the management of state plans. By integrating with AWS SES for email delivery and Kafka for event-driven triggers, the application now automatically notifies relevant stakeholders (e.g., state plan submitters, CMS review teams) at key moments such as new Medicaid or CHIP submissions, temporary extensions, and package withdrawals.

Email Sending Functionality and Trigger Events

New code monitors Kafka-based events that correspond to particular actions in the state plan workflow. When an event such as "new-medicaid-submission", "new-chip-submission", "temp-extension", or "withdraw-package" occurs, the system retrieves the necessary email templates and recipient addresses. It then sends a properly formatted HTML (and text) email via AWS SES.

These notifications target both state-level users (e.g., plan submitters and other state staff) and CMS teams (e.g., State Review Teams, CPOC users). For certain events, both groups receive relevant, custom-tailored messages to ensure all stakeholders remain informed.

Integration with Existing Codebase

New and Modified Files and Modules

• lib/lambda/processEmails.ts: Core lambda function that processes Kafka records and sends emails based on event type and authority.
• lib/lambda/processEmails.test.ts: Introduces unit tests ensuring reliability of email processing functionality.
• lib/lambda/sinkMain.ts and lib/lambda/sinkMainProcessors.ts: Adjusted to handle new event topics and integrate with the email sending pipeline.
• lib/libs/email/ directory: Contains email templates, content components, and helper functions. Newly added files and refactored functions for retrieving and formatting recipient lists, and obtaining email templates depending on the event and authority.
• lib/libs/email/getAllStateUsers.ts: Retrieves state user email addresses from Cognito, now returning a formatted address list for direct email sending.
• HTML/JSX-based email templates under lib/libs/email/content/ directories, each designed to handle a specific event and audience (CMS or state).

Configuration and Environment Variables

Several new environment variables are introduced to support email functionality:

• emailAddressLookupSecretName: Identifies the AWS Secrets Manager secret containing email-related configuration.
• applicationEndpointUrl: URL to the application’s frontend, included in the emails as a link.
• osDomain, indexNamespace, region: Support OpenSearch lookups and AWS region configuration.
• DLQ_URL: Dead-letter queue for failed message processing.
• userPoolId: The Cognito User Pool ID used to fetch state users’ email addresses.
• configurationSetName: SES configuration set for tracking email sending metrics.
• isDev: Flags whether the environment is development, enabling test mode (e.g., routing all emails to a dev mailbox).

Third-Party Libraries and Dependencies

• @aws-sdk/client-ses: Used to send emails through AWS SES.
• p-limit: Limits concurrency when sending multiple emails simultaneously.

Business Logic, Data Models, and Workflow Adjustments

Prior to these changes, the application processed workflow events without sending automatic notifications. Now, when records are processed from Kafka topics (e.g., events representing new package submissions or withdrawals), the system:

• Retrieves event details and relevant user emails (from Cognito and OpenSearch).
• Determines appropriate email templates based on event type and package authority (e.g., Medicaid SPA, CHIP, etc.).
• Generates and sends emails to configured recipients, including fallback behavior in development mode.

These logic additions ensure that each significant workflow milestone triggers timely notifications, reducing manual follow-up and improving communication among stakeholders.

Test Coverage and Reliability

Newly added and updated tests ensure robust validation of the email sending feature:

• lib/lambda/processEmails.test.ts: Verifies that the processEmails handler correctly processes both empty and valid records without errors.
• lib/libs/email/__tests__/getAllStateUsers.test.ts: Confirms correct retrieval and formatting of state user email addresses.
• lib/libs/email/content/email-components.test.tsx: Ensures email component functions correctly identify and format recipient lists.

These tests improve maintainability and reliability, ensuring future changes don’t break the new notification functionality.

Documentation Updates

While no explicit documentation files are included, the changes are structured in a manner that is largely self-documenting. Future maintainers should reference:

• Environment variable listings in the code and README sections.
• In-code comments explaining the purpose of new handlers and templates.
• Test files as examples of how the new email logic functions.

Impact and Forward-Looking Summary

The introduction of automated email notifications represents a significant step forward in the application's communication capabilities. By integrating email sending into the event-driven architecture, stakeholders will receive timely notifications for important submission and workflow changes. As the system evolves, new events and user categories can be easily integrated, ensuring consistent and reliable communication that scales with the project’s growth.