Email Notification System

Epic 1 Scope - Automated Email Notifications

Epic 1 includes 3 automated emails to keep users informed during manual processing:

Request Confirmation - Sent immediately when user submits request (status: pending)
Processing Notification - Sent when admin starts processing (status: processing)
Completion Email - Sent when audio is ready with playback link (status: completed)

Overview

The email notification system sends automated emails to users at key stages of request processing:

Epic 1 Emails:

Confirmation - When user submits request (status: pending)
Processing - When admin starts working on request (status: processing)
Completion - When audio is ready with playback link (status: completed)

Email Service: SendGrid / AWS SES (to be decided)

Delivery Rate Target: > 99%

Email Templates

1. Confirmation Email (Immediate)

Trigger: User submits request via POST /api/v1/requests See Confirmation Email Trigger Flow for implementation details

Subject: Your MicDots request has been received

Template Variables:

{
  userName: string;
  requestId: string;
  textPreview: string; // First 100 chars
  voiceName: string;
  voiceGender: string;
  voiceAccent: string;
  estimatedTime: string; // "1-24 hours"
}

Email Content (HTML):

<!DOCTYPE html>
<html>
<body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333;">
  <div style="max-width: 600px; margin: 0 auto; padding: 20px;">
    <h1 style="color: #4d7cfe;">Request Received ✓</h1>

    <p>Hi there,</p>

    <p>Thank you for your MicDots request! We've received your text-to-audio request and will start processing it soon.</p>

    <div style="background: #f5f5f5; padding: 16px; border-radius: 8px; margin: 20px 0;">
      <p style="margin: 0;"><strong>Request ID:</strong> {{requestId}}</p>
      <p style="margin: 8px 0 0 0;"><strong>Voice:</strong> {{voiceName}} ({{voiceGender}}, {{voiceAccent}})</p>
    </div>

    <div style="background: #e3f2fd; padding: 16px; border-radius: 8px; border-left: 4px solid #4d7cfe;">
      <p style="margin: 0;"><strong>Text Preview:</strong></p>
      <p style="margin: 8px 0 0 0; font-style: italic;">"{{textPreview}}..."</p>
    </div>

    <h3 style="color: #4d7cfe;">What happens next?</h3>
    <p>Our team will process your request and generate your audio. You'll receive another email when:</p>
    <ul>
      <li>We start processing your audio (Processing status)</li>
      <li>Your audio is ready with a QR code (Done status)</li>
    </ul>

    <p><strong>Estimated time:</strong> {{estimatedTime}}</p>

    <hr style="border: none; border-top: 1px solid #ddd; margin: 24px 0;">

    <p style="font-size: 12px; color: #777;">
      Need help? Contact support at <a href="mailto:support@micdots.com">support@micdots.com</a>
    </p>
  </div>
</body>
</html>

Email Content (Plain Text):

Request Received ✓

Hi there,

Thank you for your MicDots request! We've received your text-to-audio request and will start processing it soon.

Request ID: {{requestId}}
Voice: {{voiceName}} ({{voiceGender}}, {{voiceAccent}})

Text Preview:
"{{textPreview}}..."

What happens next?

Our team will process your request and generate your audio. You'll receive another email when:
- We start processing your audio (Processing status)
- Your audio is ready with a QR code (Done status)

Estimated time: {{estimatedTime}}

---

Need help? Contact support at support@micdots.com

2. Processing Email (Admin Triggered)

Trigger: Admin updates status to "processing" via PUT /api/v1/text-to-speech/{id} See Processing Email Trigger Flow for implementation details

Subject: Your audio is being generated

Template Variables:

{
  userName: string;
  requestId: string;
  voiceName: string;
}

Email Content (HTML):

<!DOCTYPE html>
<html>
<body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333;">
  <div style="max-width: 600px; margin: 0 auto; padding: 20px;">
    <h1 style="color: #4d7cfe;">We're Working on Your Audio 🔄</h1>

    <p>Hi there,</p>

    <p>Great news! We've started processing your text-to-audio request.</p>

    <div style="background: #f5f5f5; padding: 16px; border-radius: 8px; margin: 20px 0;">
      <p style="margin: 0;"><strong>Request ID:</strong> {{requestId}}</p>
      <p style="margin: 8px 0 0 0;"><strong>Voice:</strong> {{voiceName}}</p>
      <p style="margin: 8px 0 0 0;"><strong>Status:</strong> <span style="color: #4d7cfe; font-weight: bold;">Processing</span></p>
    </div>

    <p>You'll receive another email as soon as your audio is ready with a playback link and QR code.</p>

    <hr style="border: none; border-top: 1px solid #ddd; margin: 24px 0;">

    <p style="font-size: 12px; color: #777;">
      Need help? Contact support at <a href="mailto:support@micdots.com">support@micdots.com</a>
    </p>
  </div>
</body>
</html>

Email Content (Plain Text):

We're Working on Your Audio 🔄

Hi there,

Great news! We've started processing your text-to-audio request.

Request ID: {{requestId}}
Voice: {{voiceName}}
Status: Processing

You'll receive another email as soon as your audio is ready with a playback link and QR code.

---

Need help? Contact support at support@micdots.com

3. Completion Email

Trigger: Admin updates request with audio URL via PUT /api/v1/text-to-speech/\{id\} (with audioUrl and status: completed)

Subject: Your audio is ready! 🎉

Template Variables:

{
  userName: string;
  requestId: string;
  playbackUrl: string;
  voiceName: string;
  textPreview: string;
}

Email Content (HTML):

<!DOCTYPE html>
<html>
<body style="font-family: Arial, sans-serif; line-height: 1.6; color: #333;">
  <div style="max-width: 600px; margin: 0 auto; padding: 20px;">
    <h1 style="color: #4ade80;">Your Audio is Ready! 🎉</h1>

    <p>Hi {{userName}},</p>

    <p>Great news! Your text-to-audio request has been completed successfully!</p>

    <div style="background: #f5f5f5; padding: 16px; border-radius: 8px; margin: 20px 0;">
      <p style="margin: 0;"><strong>Request ID:</strong> {{requestId}}</p>
      <p style="margin: 8px 0 0 0;"><strong>Voice:</strong> {{voiceName}}</p>
    </div>

    <div style="background: #e8f5e9; padding: 20px; border-radius: 8px; border-left: 4px solid #4ade80; margin: 24px 0;">
      <h3 style="margin-top: 0; color: #2e7d32;">🎙️ Listen Now</h3>
      <p>Click the button below to play your audio:</p>
      <p style="text-align: center; margin: 16px 0;">
        <a href="{{playbackUrl}}" style="display: inline-block; padding: 12px 32px; background: #4d7cfe; color: white; text-decoration: none; border-radius: 6px; font-weight: bold;">
          Play Audio
        </a>
      </p>
      <p style="font-size: 12px; color: #666; word-break: break-all;">
        {{playbackUrl}}
      </p>
    </div>

    <hr style="border: none; border-top: 1px solid #ddd; margin: 24px 0;">

    <p style="font-size: 12px; color: #777;">
      Need help? Contact support at <a href="mailto:support@micdots.com">support@micdots.com</a>
    </p>
  </div>
</body>
</html>

Email Content (Plain Text):

Your Audio is Ready! 🎉

Hi {{userName}},

Great news! Your text-to-audio request has been completed successfully!

Request ID: {{requestId}}
Voice: {{voiceName}}

🎙️ Listen Now

Click the link below to play your audio:
{{playbackUrl}}

---

Need help? Contact support at support@micdots.com

Email Service Configuration

SendGrid Setup

Configuration Requirements:

API Key: Configure SendGrid API key in environment variables
Sender Email: noreply@micdots.com
Sender Name: "MicDots"
Template IDs: Create three templates in SendGrid dashboard
- Confirmation template
- Processing template
- Done template

Domain Verification:

Verify micdots.com domain in SendGrid
Configure SPF and DKIM records
Enable link tracking and open tracking

AWS SES Setup (Alternative)

Configuration Requirements:

AWS Region: us-east-1 (or preferred region)
Access Credentials: Configure AWS access key and secret
Sender Email: Verify noreply@micdots.com in SES
Email Templates: Create three SES email templates

Domain Verification:

Verify micdots.com domain in AWS SES
Configure DKIM settings
Move out of sandbox mode for production

Implementation

Email Service Architecture

The email service is responsible for sending three types of automated emails during the request lifecycle. The implementation should include:

Email Service Methods:

sendConfirmationEmail() - Sends confirmation when request is created
sendProcessingEmail() - Sends notification when admin starts processing
sendDoneEmail() - Sends completion email with audio link and QR code

Required Parameters for Each Email Type:

Confirmation Email:

Recipient email address
User name
Request ID
Text preview (first 100 characters)
Voice name, gender, and accent
Estimated completion time

Processing Email:

Recipient email address
User name
Request ID
Voice name

Done Email:

Recipient email address
User name
Request ID
Playback URL (audio player link)
QR code URL (S3 link to PNG file)
Voice name
Text preview

Trigger Implementation

1. Confirmation Email Trigger

When: Immediately after request creation

API Endpoint: POST /api/v1/requests

Flow:

User submits text-to-audio request
System creates request in database
System automatically sends confirmation email
Email includes request details and estimated processing time
API returns success response to user

Email should be sent asynchronously to avoid blocking the API response. If email fails, the request should still be created successfully.

2. Processing Email Trigger

When: Admin changes request status to "processing"

API Endpoint: PUT /api/v1/text-to-speech/:id

Flow:

Admin updates request status to "processing" in backoffice
System updates status in database via PUT endpoint
System checks if new status is "processing"
If yes, system automatically sends processing email to client
Email notifies client that their audio is being generated
API returns success response to admin

Important: Only send email when status changes TO "processing", not when changing from processing to another status.

3. Completion Email Trigger

When: Admin uploads audio file and updates request with audio URL

API Endpoint: PUT /api/v1/text-to-speech/:id (with audioUrl and status: completed)

Flow:

Admin gets pre-signed URL: POST /api/v1/text-to-speech/upload-url
Admin uploads audio file directly to S3
Admin updates request with audioUrl and status "completed": PUT /api/v1/text-to-speech/:id
System verifies audio URL exists in S3
System updates request status to "completed"
System automatically sends completion email with playback link
API returns success response to admin

Email must include:

Clickable playback link
Request details

Error Handling

Email Delivery Failures

Strategy: Graceful degradation - don't block main operations if email fails

When Confirmation Email Fails:

Log the error for monitoring
Continue with request creation - return success to user
Request is still valid even if email failed

When Processing Email Fails:

Log the error for monitoring
Continue with status update - return success to admin
Status change is still valid

When Completion Email Fails:

Log the error for monitoring
Continue with status update - return success to admin
Audio file is still available and playable
User can still access via "My Requests" page

Testing

Epic 1 Testing

Manual testing for 3 email types (Confirmation, Processing, Completion)
Basic email delivery verification
Template rendering in major email clients
Playback link validation in completion emails

Success Criteria

✅ 3 email types send successfully (Confirmation, Processing, Completion)
✅ Emails arrive within 1 minute of trigger
✅ Email delivery rate > 99%
✅ Email templates render correctly in major email clients (Gmail, Outlook, Apple Mail)
✅ Errors are logged for debugging
✅ Users receive confirmation immediately after submission
✅ Users receive processing notification when admin starts work
✅ Users receive completion email when audio is ready
✅ Playback links in completion email work correctly

User Flow - When emails are sent
Request Management API - API triggers
Admin Request Details - Admin actions that trigger emails

Overview​

Email Templates​

1. Confirmation Email (Immediate)​

2. Processing Email (Admin Triggered)​

3. Completion Email​

Email Service Configuration​

SendGrid Setup​

AWS SES Setup (Alternative)​

Implementation​

Email Service Architecture​

Trigger Implementation​

1. Confirmation Email Trigger​

2. Processing Email Trigger​

3. Completion Email Trigger​

Error Handling​

Email Delivery Failures​

Testing​

Success Criteria​

Related Documentation​

Overview

Email Templates

1. Confirmation Email (Immediate)

2. Processing Email (Admin Triggered)

3. Completion Email

Email Service Configuration

SendGrid Setup

AWS SES Setup (Alternative)

Implementation

Email Service Architecture

Trigger Implementation

1. Confirmation Email Trigger

2. Processing Email Trigger

3. Completion Email Trigger

Error Handling

Email Delivery Failures

Testing

Success Criteria

Related Documentation