Email System

Time Capsule uses SendGrid for reliable email delivery with custom HTML templates.

How It Works

Scheduled Delivery

When you create a capsule:

1. Capsule Created - Saved to database
2. Email Scheduled - Celery task created for unlock date
3. Wait Period - Task waits until unlock date
4. Email Sent - Recipient receives notification
5. Status Updated - sent_at timestamp recorded

Architecture

Create Capsule → Celery Task → Redis Queue → Wait → SendGrid → Recipient

Email Components

SendGrid Integration

Time Capsule uses SendGrid API for:

• Reliable delivery
• Custom HTML templates
• Delivery tracking
• High deliverability rates

Configuration:

EMAIL_HOST_PASSWORD = 'your_sendgrid_api_key'
DEFAULT_FROM_EMAIL = 'noreply@yourdomain.com'

Celery Tasks

Asynchronous task handling:

• send_capsule_template_email - Main email task
• send_simple_email - Test email task
• Scheduled execution at unlock date
• Retry logic on failures

Redis Queue

Message broker for Celery:

• Stores scheduled tasks
• Manages task queue
• Enables distributed processing

Email Template

Custom HTML Design

Emails include:

• Header - Time Capsule branding
• Title - Capsule title in large text
• Content - Full message content
• CTA Button - Link to view online
• Footer - Timestamp and branding

Template Variables

{
  'capsule_title': 'My First Capsule',
  'capsule_content': 'Message content here...',
  'capsule_url': 'https://yourdomain.com/capsule_detail/1/'
}

Email Subject

🎁 Your Time Capsule '{title}' is Unlocked!

Fallback System

With Redis (Preferred)

if is_redis_available():
    send_capsule_template_email.apply_async(
        args=[email, title, content, url],
        eta=unlock_date
    )

Without Redis (Fallback)

else:
    send_capsule_template_email_sync(
        email, title, content, url
    )

Manual Email Sending

Admins can manually trigger emails:

1. Navigate to capsule detail page
2. Click "Send Email" button
3. Email sent immediately to recipient

Use Cases:

• Testing email delivery
• Resending failed emails
• Sending before unlock date

Email Testing

Admin-only test interface at /test-email/:

1. Enter test email address
2. Submit form
3. Receive sample capsule email

Test Email Contains:

• Sample title: "My First Time Capsule"
• Sample content with placeholder text
• Link to homepage

Delivery Status

Tracking

The Recipient model tracks:

{
  "email": "recipient@example.com",
  "sent_at": "2024-01-15 10:30:00"  # null until sent
}

Verification

Check if email was sent:

• sent_at is null → Not sent yet
• sent_at has timestamp → Sent successfully

Error Handling

Common Issues

SendGrid API Error:

• Check API key is valid
• Verify sender email is verified in SendGrid
• Check SendGrid account status

Redis Connection Error:

• Falls back to immediate send
• Check Redis URL configuration
• Verify Redis server is running

Email Not Received:

• Check spam/junk folder
• Verify recipient email is correct
• Check SendGrid activity logs

Logging

All email operations are logged:

print(f"Email sent successfully to {recipient_email}")
print(f"Failed to send email: {error_message}")

Best Practices