Email Service

Overview

The email service is event-driven and supports:

• Multi-Provider Support — Mailjet or SendGrid
• Transactional Templates — Provider-managed templates
• Custom HTML — Custom templates
• Event-Driven — Triggered by platform events
• Automatic Retry — Handles failures gracefully
• Centralized — Single source for all emails

Supported Email Providers

Mailjet (Default)

• Free Tier: 6,000 emails/month
• Best For: European customers, GDPR compliance
• Features: Templates, analytics, SMTP

SendGrid

• Free Tier: 100 emails/day
• Best For: High volume, US-based
• Features: Dynamic templates, advanced analytics

Switch providers via feature flag:

EMAIL_PROVIDER=mailjet
# or
EMAIL_PROVIDER=sendgrid

Email Types

1. Password Reset Email

Trigger: User requests password reset

Event: email.password-reset

Content:

• 6-digit verification code
• Reset link button
• 1-hour expiration notice
• Security warnings

Template Variables:

• firstName - User's first name
• resetCode - 6-digit code
• resetLink - Password reset URL
• expiryHours - Hours until expiration

2. Password Changed Email

Trigger: Password successfully changed

Event: email.password-changed

Content:

• Confirmation message
• Security alert
• Support contact info

Template Variables:

• firstName - User's first name

3. Welcome Email

Trigger: New user registration

Event: email.welcome

Content:

• Welcome message
• Getting started tips
• Platform features

Template Variables:

• firstName - User's first name

4. Generic Notification Email

Trigger: Custom notifications

Event: email.notification

Content:

• Custom subject and message

Template Variables:

• firstName - User's first name
• subject - Email subject
• message - Email content

Transactional Templates

What are Transactional Templates?

Transactional templates are pre-designed, provider-managed email templates that can be dynamically populated with data.

Benefits

• Easier to update — No code changes needed
• Version control — Provider tracks versions
• A/B testing — Test different versions
• Team collaboration — Non-developers can edit
• Compliance — Easier to manage legal text

Configuration

Enable Templates:

USE_EMAIL_TEMPLATES=true

Configure Template IDs:

Mailjet (Numeric IDs):

TEMPLATE_PASSWORD_RESET=123456
TEMPLATE_PASSWORD_CHANGED=123457
TEMPLATE_WELCOME=123458
TEMPLATE_NOTIFICATION=123459

SendGrid (String IDs):

TEMPLATE_PASSWORD_RESET=d-abc123xyz456
TEMPLATE_PASSWORD_CHANGED=d-def456abc789
TEMPLATE_WELCOME=d-ghi789def012
TEMPLATE_NOTIFICATION=d-jkl012ghi345

Email Events (For Developers)

Publishing Email Events

From any microservice:

import EventService from './services/event.service.js';

// Send password reset email
await EventService.publish('email.password-reset', {
  email: 'user@example.com',
  resetCode: '123456',
  firstName: 'John'
});

// Send welcome email
await EventService.publish('email.welcome', {
  email: 'user@example.com',
  firstName: 'John'
});

// Send custom notification
await EventService.publish('email.notification', {
  email: 'user@example.com',
  firstName: 'John',
  subject: 'Important Update',
  message: 'Your account has been updated.'
});

Event Schema Reference

email.password-reset

{
  "email": "user@example.com",
  "resetCode": "123456",
  "firstName": "John"
}

email.password-changed

{
  "email": "user@example.com",
  "firstName": "John"
}

email.welcome

{
  "email": "user@example.com",
  "firstName": "John"
}

email.notification

{
  "email": "user@example.com",
  "firstName": "John",
  "subject": "Custom Subject",
  "message": "Custom message content"
}

Email Design

All emails include:

• Professional design - Gradient headers, modern layout
• Responsive - Mobile-friendly design
• Branded - 1House Global branding and colors
• Clear CTAs - Prominent call-to-action buttons
• Plain text fallback - For email clients without HTML support
• Footer - Company info and copyright

Design System

Colors:

• Primary: #667eea to #764ba2 (gradient)
• Success: #11998e to #38ef7d (gradient)
• Text: #333 (dark gray)
• Background: #f9f9f9 (light gray)

Typography:

• Font: Arial, sans-serif
• Headers: 24-32px, bold
• Body: 16px, normal
• Code: 32px, monospace, bold

Monitoring

Email Delivery Status

Mailjet Dashboard:

• Go to https://app.mailjet.com/stats
• View sent/delivered/bounced stats
• Check open and click rates

SendGrid Dashboard:

• Go to https://app.sendgrid.com/stats
• View delivery statistics
• Monitor bounce rates

Service Logs

# View email service logs
docker logs -f email-service

# Look for:
# Received event: email.password-reset
# Password reset email sent successfully

Troubleshooting

Emails Not Sending

1. Check email service is running

docker ps | grep email-service

2. Verify provider initialization

docker logs email-service | grep "initialized successfully"

3. Check for events

docker logs email-service | grep "Received event"

4. Verify credentials

# Check environment variables are set
docker exec email-service env | grep MAILJET_API_KEY
# or
docker exec email-service env | grep SENDGRID_API_KEY

Emails Going to Spam

1. Verify sender email in provider dashboard
2. Set up SPF records for your domain
3. Configure DKIM authentication
4. Avoid spam triggers in content
5. Maintain good sender reputation

Template Errors

"Template not found":

• Verify template ID is correct
• Check template is published/active
• Ensure USE_EMAIL_TEMPLATES=true

Email Deliverability Tips

Improve Delivery Rates

1. Verify sender domain - Use verified sender email
2. Authenticate emails - Set up SPF, DKIM, DMARC
3. Monitor bounce rates - Keep below 5%
4. Avoid spam words - Free, guarantee, urgent, etc.
5. Include unsubscribe - For marketing emails
6. Send consistently - Maintain sending reputation
7. Clean lists - Remove bounced emails

Email Content Best Practices

1. Clear subject lines - Descriptive, not misleading
2. Personalize - Use recipient's name
3. Mobile-first - Responsive design
4. Single CTA - One clear call-to-action
5. Test thoroughly - Multiple email clients
6. Brand consistency - Match platform design

Provider Comparison

Architecture

┌──────────────┐     Email Event     ┌──────────────┐
│ Auth Service │────────────────────▶│Email Service │
└──────────────┘                     └──────┬───────┘
                                            │
┌──────────────┐                            │
│Trading Service│───────────────────────────┤
└──────────────┘                            │
                                            ▼
┌──────────────┐                     ┌─────────────┐
│  Any Service │────────────────────▶│   Mailjet   │
└──────────────┘   RabbitMQ Queue    │     or      │
                                     │  SendGrid   │
                                     └─────────────┘

Future Enhancements

• Email scheduling
• Drip campaigns
• A/B testing
• Advanced analytics
• Template versioning
• Multi-language support
• Attachment support
• Bulk sending
• Email preferences center
• Unsubscribe management

Related Documentation

• Password Reset - Password reset flow
• Notifications - Push notifications
• Platform Types - Platform access

Support

For email delivery issues:

1. Check service logs
2. Verify provider dashboard
3. Review RabbitMQ queue
4. Test with simple email
5. Contact platform support