M3-05 Email Sharing System Tasks¶

Milestone: M3 — Issuing Functionality | SOW Reference: FR1 (also feeds M3-12 reminders) | Requirement Clarity: ✅ Clear | Dev Status: 🟢 Prototyped in POC Moved from docs/requirements/tasks/POC/04-email-sharing-system.md. Completion status companion: M3-05-implementation-summary.md. Unmodified below.

🎯 VNF SDK Reference Implementation¶

PRIMARY REFERENCE: `vnf-wallet-sdk-nodejs-main/`¶

All email sharing tasks MUST follow the official VNF SDK sample application patterns

Key Reference Files: - Deep Link Generation: packages/sample-app/src/Constants.ts:10 - VNF deep link patterns for claim URLs - Credential Offers: packages/sdk/src/api/entities/VCLOffers.ts - Offer structure for email content - JWT Handling: packages/sdk/src/api/entities/VCLJwt.ts - Secure token patterns - Session Tokens: packages/sdk/src/api/entities/VCLToken.ts - Token management for claim links

Overview¶

Implementation of configurable email templates and credential offer notifications with landing page for credential acceptance following VNF SDK deep link and token patterns.

Backend Tasks¶

Email Service Integration¶

Task: Create email service for credential notifications
Create email.service.ts
Configure SMTP settings for sandbox environment
Implement email template rendering using Handlebars
Add email delivery tracking and retry logic

Email Template Management¶

Task: Implement configurable email templates
Create email-template.entity.ts (already exists)
Add template types: CREDENTIAL_OFFER, CREDENTIAL_REMINDER, CREDENTIAL_EXPIRED
Implement template variable substitution (employee name, company, claim link)
Add template preview functionality

Credential Notification Service¶

Task: Create credential offer notification system
Create notification.service.ts
Implement credential offer email generation
Add personalized claim links with security tokens
Integrate with VNF SDK for credential offer URLs

Email Delivery Tracking¶

Task: Track email delivery status and engagement
Create email-log.entity.ts
Track delivery status: QUEUED, SENT, DELIVERED, OPENED, FAILED
Implement webhook handling for email service providers
Add bounce and unsubscribe handling

Credential Landing Page API¶

Task: Create landing page backend for credential claiming
Create claim.controller.ts
Implement GET /claim/{token} endpoint for credential details
Add token validation and expiration checking
Provide credential claim instructions and mobile app links

Frontend Tasks¶

Email Template Editor¶

Task: Create email template configuration interface
Create EmailTemplateEditor.tsx
Implement rich text editor for email content
Add template variable insertion ({{employeeName}}, {{companyName}})
Provide template preview with sample data

Email Campaign Management¶

Task: Manage credential offer email campaigns
Create EmailCampaign.tsx
Add bulk email sending controls
Implement email scheduling functionality
Show campaign statistics (sent, delivered, opened)

Email Analytics Dashboard¶

Task: Track email performance and engagement
Create EmailAnalytics.tsx
Display delivery rates and open rates
Show bounce and failure analytics
Add email performance charts and graphs

Credential Landing Page¶

Task: Create public credential claim landing page
Create CredentialClaim.tsx
Display credential details and claim instructions
Add QR code for mobile wallet integration
Provide download links for credential wallet apps

Email Templates¶

Credential Offer Template¶

<!DOCTYPE html>
<html>
<head>
    <title>Your Employment Credential is Ready</title>
</head>
<body>
    <h1>Hello {{employeeName}},</h1>
    <p>{{companyName}} has issued you a verifiable employment credential.</p>
    <p><strong>Position:</strong> {{jobTitle}}</p>
    <p><strong>Employment Period:</strong> {{startDate}} to {{endDate}}</p>

    <a href="{{claimUrl}}" style="background: #007bff; color: white; padding: 12px 24px; text-decoration: none;">
        Claim Your Credential
    </a>

    <p>This link expires on {{expirationDate}}.</p>
</body>
</html>

Reminder Template¶

<!DOCTYPE html>
<html>
<body>
    <h1>Reminder: Claim Your Employment Credential</h1>
    <p>Hi {{employeeName}},</p>
    <p>You have an unclaimed employment credential from {{companyName}}.</p>
    <p>This credential expires in {{daysRemaining}} days.</p>
    <a href="{{claimUrl}}">Claim Now</a>
</body>
</html>

API Endpoints¶

Email Management¶

POST /api/v1/admin/email-templates
GET /api/v1/admin/email-templates
PUT /api/v1/admin/email-templates/{id}
DELETE /api/v1/admin/email-templates/{id}
POST /api/v1/admin/email-templates/{id}/preview

Notification System¶

POST /api/v1/issuer/notifications/send-credential-offers
POST /api/v1/issuer/notifications/send-reminders
GET /api/v1/issuer/notifications/campaigns
GET /api/v1/issuer/notifications/analytics

Public Claim Page¶

GET /api/v1/public/claim/{token}
POST /api/v1/public/claim/{token}/track-open
GET /api/v1/public/claim/{token}/download-apps

Dependencies & Assumptions¶

Prerequisites¶

SMTP server configuration for sandbox
Email template storage in database
Token generation and validation system
Public route configuration for claim pages

Cross-team Dependencies¶

Email template designs from UI/UX team
SMTP provider setup (SendGrid, AWS SES, etc.)
Mobile wallet app download links
Legal compliance for email communications

Acceptance Criteria¶

Send personalized credential offer emails with 95%+ delivery rate
Track email delivery status and engagement metrics
Support configurable email templates with variable substitution
Provide secure credential claim landing pages
Handle email bounces and unsubscribes properly
Send automated reminder emails for unclaimed credentials
Generate QR codes for mobile credential claiming
Support bulk email campaigns for large batches

Estimated Timeline¶

Week 5-6: 10 days - Day 1-2: Email service and SMTP configuration - Day 3-4: Email template management system - Day 5-6: Credential notification service - Day 7-8: Email tracking and analytics - Day 9-10: Landing page and frontend components

Blockers & Risks¶

Dependency: SMTP provider setup and configuration
Risk: Email deliverability and spam filtering
Blocker: Email template design approval
Risk: Token security and expiration handling
Dependency: Mobile wallet app availability for testing