Email System Configuration

This guide explains how to configure email notifications in the Nomad Media system, including how to set the "from" address and manage email templates.

Overview

The Nomad Media system uses AWS Simple Email Service (SES) to send transactional emails for various events such as:

• User invitations and approvals
• Asset sharing notifications
• Download ready notifications
• Live recording stopped alerts
• Asset restoration confirmations
• Media builder notifications
• Search results export availability

Prerequisites

Before configuring email notifications, ensure your infrastructure is setup:

1. AWS SES configured in your AWS account
2. Verified sender email addresses in AWS SES

From Address Configuration

The email "from" address can be configured in two ways, with a clear priority order:

1. System-Wide Default From Address

Set a default "from" address for all system emails using the SystemNotifications setting.

Configuration Path: application/emailSettings

Example Configuration:

{
  "systemNotifications": "[email protected]",
  "templates": {
    "assetSharedWithExternalUsers": "s3://your-bucket/email-templates/asset-shared-with-external-users.json",
    "assetSharedWithNomadUsers": "s3://your-bucket/email-templates/asset-shared-with-nomad-users.json"
  }
}

2. Template-Specific From Address

Override the default by specifying a from field in individual email templates.

Example Template:

{
  "name": "Search Results Ready",
  "from": "[email protected]",
  "subject": "Search Results Export Available",
  "html": "<p>Your search results are ready...</p>",
  "text": "Your search results are ready..."
}

Priority Order:

1. Template from field (highest priority)
2. SystemNotifications setting (fallback)

Important: All "from" addresses must be verified in AWS SES before use.

Email Template Configuration

Email templates are JSON files stored in AWS S3. You can configure template locations in two ways:

Option 1: Base Template Path

Set a base path where all templates are stored.

Configuration Path: system/nomadSettings

Property: EmailTemplatePath

Example:

{
  "emailTemplatePath": "s3://nomad-{projectPrefix}-system-system-{uniqueId}/email-templates/"
}

The system will automatically look for template files in this directory.

Option 2: Individual Template URLs

Specify the S3 location for each template individually.

Configuration Path: application/emailSettings

Property: Templates

Example:

{
  "templates": {
    "assetSharedWithExternalUsers": "s3://your-bucket/email-templates/asset-shared-with-external-users.json",
    "userApproved": "s3://your-bucket/email-templates/user-approved.json",
    "downloadZip": "s3://your-bucket/email-templates/email-zip.json",
    "userInvite": "s3://your-bucket/email-templates/user-invite.json"
  }
}

Email Template Structure

Email templates are JSON files with the following structure:

{
  "name": "Template Display Name",
  "from": "[email protected]",
  "subject": "Email Subject with {tokens}",
  "html": "<p>HTML version with {tokens}</p>",
  "text": "Plain text version with {tokens}"
}

Template Fields

Available Email Templates

The following email templates are available in the system:

Token Replacement

Email templates support dynamic content using tokens in curly braces {tokenName}. Tokens are replaced with actual values when emails are sent.

Common Tokens

Example Template with Tokens

{
  "name": "Asset Shared with External Users",
  "subject": "{asset.SubjectType} shared from Your Company",
  "html": "<p>Hello,</p><p>You have had {asset.DisplayType} shared with you. Please click <a href='{asset.FullUrl}'>here</a> to view it.</p><p>Share Duration: {duration}</p>",
  "text": "Hello,\n\nYou have had {asset.DisplayType} shared with you. Please visit {asset.FullUrl} to view it.\n\nShare Duration: {duration}"
}

S3 Configuration File

Configuration is stored in an S3 JSON file:

Path Pattern:

s3://nomad-{projectPrefix}-system-system-{uniqueId}/configuration/{projectPrefix}.json

Example Configuration File:

{
  "application/emailSettings": {
    "systemNotifications": "[email protected]",
    "templates": {
      "userApproved": "s3://your-bucket/email-templates/user-approved.json",
      "userInvite": "s3://your-bucket/email-templates/user-invite.json"
    }
  },
  "system/nomadSettings": {
    "emailTemplatePath": "s3://your-bucket/email-templates/"
  }
}

Deploying Email Templates

Step 1: Create Template Files

Create JSON template files following the structure outlined above.

Step 2: Upload to S3

Upload your template files to your S3 bucket:

aws s3 cp asset-shared-with-external-users.json s3://your-bucket/email-templates/
aws s3 cp user-invite.json s3://your-bucket/email-templates/

Step 3: Update Configuration

Update your configuration in the S3 configuration file to reference the new templates.

Step 4: Verify SES Sender Addresses

Ensure all "from" addresses are verified in AWS SES:

aws ses verify-email-identity --email-address [email protected]

Troubleshooting

Emails Not Sending

Possible Causes:

• From address not verified in AWS SES
• SES is in sandbox mode (can only send to verified addresses)
• IAM permissions missing for SES
• Invalid template configuration

Solutions:

1. Verify sender email addresses in AWS SES console
2. Request production access for SES if in sandbox mode
3. Check CloudWatch logs for error messages
4. Verify IAM role has ses:SendEmail permission

Template Not Found

Possible Causes:

• Incorrect S3 path in configuration
• Template file doesn't exist in S3
• Missing S3 read permissions

Solutions:

1. Verify the template exists in S3: aws s3 ls s3://your-bucket/email-templates/
2. Check EmailTemplatePath or Templates configuration
3. Ensure IAM role has s3:GetObject permission for the bucket

Wrong From Address

Possible Causes:

• Template from field overriding system default
• SystemNotifications not configured

Solutions:

1. Check template JSON for from field
2. Verify application/emailSettings.SystemNotifications is set
3. Remember: template from takes priority over system default

Tokens Not Replaced

Possible Causes:

• Incorrect token syntax
• Token not available for that email type

Solutions:

1. Ensure tokens use curly braces: {tokenName}
2. Verify token is supported for that email template
3. Check CloudWatch logs for template processing errors

Best Practices

Email Configuration

1. Use a dedicated email domain - Consider using a subdomain like [email protected]
2. Verify all sender addresses - Always verify addresses in SES before deployment
3. Start in SES sandbox - Test thoroughly before requesting production access
4. Monitor bounce rates - Set up SNS notifications for bounces and complaints

Template Management

1. Version control templates - Keep templates in source control
2. Use consistent naming - Follow the existing template naming conventions
3. Test with real data - Preview emails with actual token values
4. Provide both HTML and text - Always include plain text versions
5. Keep templates simple - Avoid complex HTML that may not render in all clients

Summary

• Email Service: AWS Simple Email Service (SES)
• From Address: Configure via application/emailSettings.SystemNotifications or template from field
• Templates: JSON files stored in S3
• Configuration: AWS S3 configuration file
• Token Support: Dynamic content using {tokenName} syntax
• Template Priority: Template from field overrides system default