AVK Email Service (Multi-Provider Strategy)

A robust, cloud-native email notification service built with Spring Boot, supporting a hybrid strategy of AWS Simple Email Service (SES) and Standard SMTP (Gmail, Outlook, etc.). This service provides a centralized API for sending emails, managing dynamic templates, and tracking delivery status with a resilient retry mechanism.

🚀 Features

• Multi-Provider Strategy: Seamlessly switch between AWS SES and SMTP providers at runtime.
• Dynamic Strategy Factory: Smartly handles retries by maintaining the original provider for each specific email log.
• Centralized Email API: Unified interface for sending emails across multiple applications.
• Synchronous & Asynchronous Sending: Supports both immediate feedback and background processing.
• Dynamic Templating: Integration with Thymeleaf for rich HTML email templates with dynamic content.
• Resilient Retry Mechanism: Built-in background scheduler that retries transient failures with status tracking.
• PostgreSQL Persistence: Detailed logging of every email attempt, including provider tracking and error messages.
• Client Authentication: Secure access management using Client ID and Secret headers.

🛠️ Tech Stack

• Framework: Spring Boot 3.5.7
• Language: Java 21
• Email Providers:
  • AWS SES (AWS SDK v2)
  • Java SMTP (Support for Gmail, Outlook, etc.)
• Database: PostgreSQL
• Templating: Thymeleaf
• Build Tool: Maven

⚙️ Configuration

The application requires specific properties in application.properties to manage the active strategy and credentials:

Property	Description	Default Value
email.provider.active	Currently active provider (AWS_SES or SMTP)	AWS_SES
aws.ses.sender-email	Default verified sender for AWS SES	-
spring.mail.host	SMTP Host (e.g., smtp.gmail.com)	-
spring.mail.username	SMTP Account Username	-
spring.mail.password	SMTP Password (use App Passwords for Gmail)	-
email.retry.max-retries	Max retry attempts for sending	3
server.port	Application Port	8081

📐 Architecture: Strategy Design Pattern

The service implements the Strategy Pattern to decouple the sender logic:

1. Interface: EmailSenderStrategy defines the contract.
2. Implementations: AwsSesStrategyImpl and SmtpStrategyImpl handle specific vendor logic.
3. Factory: EmailStrategyFactory resolves the correct engine at runtime based on the email's assigned provider.

📡 API Endpoints

Email Operations

Method	Endpoint	Description
POST	/api/v1/email/send/sync	Send email synchronously.
POST	/api/v1/email/send/async	Send email asynchronously.
GET	/api/v1/email/status/{id}	Get status of an email by ID.

Example Request:

{
  "to": ["recipient@example.com"],
  "subject": "System Alert",
  "body": "Your account has been accessed.",
  "priority": "HIGH"
}

🏃 Getting Started

1. Clone and Build:

   mvn clean install

2. Database Setup: Ensure PostgreSQL is running and credentials are updated in application.properties.

3. Configure Strategy:

   • Set email.provider.active to AWS_SES or SMTP.
   • Provide the corresponding credentials (AWS keys or SMTP login).

4. Run:

   mvn spring-boot:run

📊 Database Schema

Managed under the avk_core_services schema:

• clients: API access management.
• email_templates: HTML template storage.
• emails: Central log of all emails, including the provider used and current status.