Emails

The Email entity represents email messages within the Wrkbelt platform. It supports both template-based and custom emails, with capabilities for multiple recipients and attachments.

Schema Definition

type Email = {
  // Base Properties
  _id: string;                 // MongoDB ObjectId
  template_id?: string;        // Optional template identifier
  template_data?: Record<string, unknown>; // Optional template variables
  subject: string;            // Required email subject
  html_body?: string;         // Optional HTML content
  text_body?: string;         // Optional plain text content
  from?: string;              // Optional sender address
  reply_to?: string;          // Optional reply-to address
  to: EmailRecipient[];       // Required recipients
  cc?: EmailRecipient[];      // Optional CC recipients
  bcc?: EmailRecipient[];     // Optional BCC recipients
  attachments?: EmailAttachment[]; // Optional file attachments
  status: EmailStatus;        // Required email status
  error?: string;             // Optional error message
  message_id?: string;        // Optional provider message ID
  sent_at?: Date;             // Optional sent timestamp
  
  // Timestamps
  createdAt: Date;            // Auto-generated
  updatedAt: Date;            // Auto-updated
} & BaseEntity;

Field Descriptions

Base Properties

Field	Type	Required	Description
_id	ObjectId	Yes	Unique identifier for the email
template_id	string	No	Template identifier for template-based emails
template_data	object	No	Variables for template rendering
subject	string	Yes	Email subject line
html_body	string	No	HTML content of the email
text_body	string	No	Plain text content of the email
from	string	No	Sender email address
reply_to	string	No	Reply-to email address
to	EmailRecipient[]	Yes	Primary recipients
cc	EmailRecipient[]	No	Carbon copy recipients
bcc	EmailRecipient[]	No	Blind carbon copy recipients
attachments	EmailAttachment[]	No	File attachments
status	EmailStatus	Yes	Current status of the email
error	string	No	Error message if sending failed
message_id	string	No	Provider-specific message identifier
sent_at	Date	No	Timestamp when email was sent

Recipient Type

interface EmailRecipient {
  email: string;   // Required email address
  name?: string;   // Optional display name
}

Attachment Type

interface EmailAttachment {
  filename: string;    // Required file name
  content: Buffer;     // Required file content
  contentType: string; // Required MIME type
}

Email Status

type EmailStatus = 'pending' | 'sent' | 'failed';

Validation

1. Template-based Emails

   • If template_id is provided, corresponding template must exist
   • Required template variables must be provided in template_data

2. Content Validation

   • At least one of html_body or text_body must be provided if not using a template
   • Valid email addresses for all recipients
   • Valid MIME types for attachments

3. Status Transitions

   • Initial status is always 'pending'
   • Can transition to 'sent' or 'failed'
   • Cannot transition from 'sent' or 'failed' back to 'pending'

Email Lifecycle

1. Creation

   // Example of creating a template-based email
   const email = {
     template_id: "welcome-email",
     template_data: {
       userName: "John Doe",
       activationLink: "https://example.com/activate"
     },
     subject: "Welcome to Wrkbelt!",
     to: [
       { email: "john@example.com", name: "John Doe" }
     ],
     status: "pending"
   };

2. Status Updates

   // Example of updating email status
   await Email.updateOne(
     { _id: emailId },
     { 
       $set: { 
         status: "sent",
         sent_at: new Date(),
         message_id: "provider-message-id"
       }
     }
   );

Security Considerations

1. Content Security

   • HTML sanitization for user-provided content
   • Attachment size and type restrictions
   • Template access control

2. Privacy

   • BCC recipient privacy preservation
   • Logging restrictions for sensitive content
   • Attachment content encryption

Performance Considerations

1. Indexes

   • Status index for querying email states
   • Compound indexes for common queries
   • Timestamp indexes for date-based queries

2. Attachment Handling

   • Size limits for attachments
   • Streaming for large attachments
   • Compression where appropriate

3. Template Processing

   • Template caching
   • Efficient variable substitution
   • Parallel processing for bulk emails