Files
honeyDueAPI/internal/services/onboarding_email_service.go
Trey t 9761156597 Add onboarding email campaign system with post-verification welcome email
Implements automated onboarding emails to encourage user engagement:
- Post-verification welcome email with 5 tips (sent after email verification)
- "No Residence" email (2+ days after registration with no property)
- "No Tasks" email (5+ days after first residence with no tasks)

Key features:
- Each onboarding email type sent only once per user (enforced by unique constraint)
- Email open tracking via tracking pixel endpoint
- Daily scheduled job at 10:00 AM UTC to process eligible users
- Admin panel UI for viewing sent emails, stats, and manual sending
- Admin can send any email type to users from the user detail Testing section

New files:
- internal/models/onboarding_email.go - Database model with tracking
- internal/services/onboarding_email_service.go - Business logic and eligibility queries
- internal/handlers/tracking_handler.go - Email open tracking endpoint
- internal/admin/handlers/onboarding_handler.go - Admin API endpoints
- admin/src/app/(dashboard)/onboarding-emails/ - Admin UI pages

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-08 14:36:50 -06:00

371 lines
11 KiB
Go

package services
import (
"crypto/rand"
"encoding/hex"
"fmt"
"time"
"github.com/rs/zerolog/log"
"gorm.io/gorm"
"github.com/treytartt/casera-api/internal/models"
)
// OnboardingEmailService handles sending and tracking onboarding emails
type OnboardingEmailService struct {
db *gorm.DB
emailService *EmailService
baseURL string // Base URL for tracking pixel
}
// NewOnboardingEmailService creates a new onboarding email service
func NewOnboardingEmailService(db *gorm.DB, emailService *EmailService, baseURL string) *OnboardingEmailService {
return &OnboardingEmailService{
db: db,
emailService: emailService,
baseURL: baseURL,
}
}
// generateTrackingID generates a unique tracking ID for email open tracking
func generateTrackingID() string {
bytes := make([]byte, 32)
if _, err := rand.Read(bytes); err != nil {
return fmt.Sprintf("%d", time.Now().UnixNano())
}
return hex.EncodeToString(bytes)
}
// HasSentEmail checks if a specific email type has already been sent to a user
func (s *OnboardingEmailService) HasSentEmail(userID uint, emailType models.OnboardingEmailType) bool {
var count int64
s.db.Model(&models.OnboardingEmail{}).
Where("user_id = ? AND email_type = ?", userID, emailType).
Count(&count)
return count > 0
}
// RecordEmailSent records that an email was sent to a user
func (s *OnboardingEmailService) RecordEmailSent(userID uint, emailType models.OnboardingEmailType, trackingID string) error {
email := &models.OnboardingEmail{
UserID: userID,
EmailType: emailType,
SentAt: time.Now().UTC(),
TrackingID: trackingID,
}
if err := s.db.Create(email).Error; err != nil {
return fmt.Errorf("failed to record email sent: %w", err)
}
return nil
}
// RecordEmailOpened records that an email was opened based on tracking ID
func (s *OnboardingEmailService) RecordEmailOpened(trackingID string) error {
now := time.Now().UTC()
result := s.db.Model(&models.OnboardingEmail{}).
Where("tracking_id = ? AND opened_at IS NULL", trackingID).
Update("opened_at", now)
if result.Error != nil {
return fmt.Errorf("failed to record email opened: %w", result.Error)
}
if result.RowsAffected > 0 {
log.Info().Str("tracking_id", trackingID).Msg("Email open recorded")
}
return nil
}
// GetEmailHistory gets all onboarding emails for a specific user
func (s *OnboardingEmailService) GetEmailHistory(userID uint) ([]models.OnboardingEmail, error) {
var emails []models.OnboardingEmail
if err := s.db.Where("user_id = ?", userID).Order("sent_at DESC").Find(&emails).Error; err != nil {
return nil, err
}
return emails, nil
}
// GetAllEmailHistory gets all onboarding emails with pagination
func (s *OnboardingEmailService) GetAllEmailHistory(page, pageSize int) ([]models.OnboardingEmail, int64, error) {
var emails []models.OnboardingEmail
var total int64
if page < 1 {
page = 1
}
if pageSize < 1 {
pageSize = 20
}
offset := (page - 1) * pageSize
// Count total
if err := s.db.Model(&models.OnboardingEmail{}).Count(&total).Error; err != nil {
return nil, 0, err
}
// Get paginated results with user info
if err := s.db.Preload("User").
Order("sent_at DESC").
Offset(offset).
Limit(pageSize).
Find(&emails).Error; err != nil {
return nil, 0, err
}
return emails, total, nil
}
// GetEmailStats returns statistics about onboarding emails
func (s *OnboardingEmailService) GetEmailStats() (*OnboardingEmailStats, error) {
stats := &OnboardingEmailStats{}
// No residence email stats
var noResTotal, noResOpened int64
s.db.Model(&models.OnboardingEmail{}).
Where("email_type = ?", models.OnboardingEmailNoResidence).
Count(&noResTotal)
s.db.Model(&models.OnboardingEmail{}).
Where("email_type = ? AND opened_at IS NOT NULL", models.OnboardingEmailNoResidence).
Count(&noResOpened)
stats.NoResidenceTotal = noResTotal
stats.NoResidenceOpened = noResOpened
// No tasks email stats
var noTasksTotal, noTasksOpened int64
s.db.Model(&models.OnboardingEmail{}).
Where("email_type = ?", models.OnboardingEmailNoTasks).
Count(&noTasksTotal)
s.db.Model(&models.OnboardingEmail{}).
Where("email_type = ? AND opened_at IS NOT NULL", models.OnboardingEmailNoTasks).
Count(&noTasksOpened)
stats.NoTasksTotal = noTasksTotal
stats.NoTasksOpened = noTasksOpened
return stats, nil
}
// OnboardingEmailStats represents statistics about onboarding emails
type OnboardingEmailStats struct {
NoResidenceTotal int64 `json:"no_residence_total"`
NoResidenceOpened int64 `json:"no_residence_opened"`
NoTasksTotal int64 `json:"no_tasks_total"`
NoTasksOpened int64 `json:"no_tasks_opened"`
}
// UsersNeedingNoResidenceEmail finds verified users who registered 2+ days ago but have no residence
func (s *OnboardingEmailService) UsersNeedingNoResidenceEmail() ([]models.User, error) {
var users []models.User
twoDaysAgo := time.Now().UTC().AddDate(0, 0, -2)
// Find users who:
// 1. Are verified
// 2. Registered 2+ days ago
// 3. Have no residences
// 4. Haven't received this email type yet
err := s.db.Raw(`
SELECT u.* FROM users u
LEFT JOIN residences r ON r.owner_id = u.id AND r.is_active = true
LEFT JOIN onboarding_emails oe ON oe.user_id = u.id AND oe.email_type = ?
WHERE u.verified = true
AND u.date_joined < ?
AND r.id IS NULL
AND oe.id IS NULL
`, models.OnboardingEmailNoResidence, twoDaysAgo).Scan(&users).Error
if err != nil {
return nil, fmt.Errorf("failed to find users needing no-residence email: %w", err)
}
return users, nil
}
// UsersNeedingNoTasksEmail finds verified users who created their first residence 5+ days ago but have no tasks
func (s *OnboardingEmailService) UsersNeedingNoTasksEmail() ([]models.User, error) {
var users []models.User
fiveDaysAgo := time.Now().UTC().AddDate(0, 0, -5)
// Find users who:
// 1. Are verified
// 2. Have at least one residence
// 3. Their first residence was created 5+ days ago
// 4. Have no tasks across ANY of their residences
// 5. Haven't received this email type yet
err := s.db.Raw(`
SELECT DISTINCT u.* FROM users u
INNER JOIN residences r ON r.owner_id = u.id AND r.is_active = true
LEFT JOIN tasks t ON t.residence_id IN (SELECT id FROM residences WHERE owner_id = u.id AND is_active = true) AND t.is_active = true
LEFT JOIN onboarding_emails oe ON oe.user_id = u.id AND oe.email_type = ?
WHERE u.verified = true
AND t.id IS NULL
AND oe.id IS NULL
AND EXISTS (
SELECT 1 FROM residences r2
WHERE r2.owner_id = u.id
AND r2.is_active = true
AND r2.created_at < ?
)
`, models.OnboardingEmailNoTasks, fiveDaysAgo).Scan(&users).Error
if err != nil {
return nil, fmt.Errorf("failed to find users needing no-tasks email: %w", err)
}
return users, nil
}
// CheckAndSendNoResidenceEmails finds eligible users and sends them the no-residence onboarding email
func (s *OnboardingEmailService) CheckAndSendNoResidenceEmails() (int, error) {
users, err := s.UsersNeedingNoResidenceEmail()
if err != nil {
return 0, err
}
sentCount := 0
for _, user := range users {
if err := s.sendNoResidenceEmail(user); err != nil {
log.Error().Err(err).Uint("user_id", user.ID).Msg("Failed to send no-residence onboarding email")
continue
}
sentCount++
}
if sentCount > 0 {
log.Info().Int("count", sentCount).Msg("Sent no-residence onboarding emails")
}
return sentCount, nil
}
// CheckAndSendNoTasksEmails finds eligible users and sends them the no-tasks onboarding email
func (s *OnboardingEmailService) CheckAndSendNoTasksEmails() (int, error) {
users, err := s.UsersNeedingNoTasksEmail()
if err != nil {
return 0, err
}
sentCount := 0
for _, user := range users {
if err := s.sendNoTasksEmail(user); err != nil {
log.Error().Err(err).Uint("user_id", user.ID).Msg("Failed to send no-tasks onboarding email")
continue
}
sentCount++
}
if sentCount > 0 {
log.Info().Int("count", sentCount).Msg("Sent no-tasks onboarding emails")
}
return sentCount, nil
}
// sendNoResidenceEmail sends the no-residence onboarding email to a user
func (s *OnboardingEmailService) sendNoResidenceEmail(user models.User) error {
if user.Email == "" {
return fmt.Errorf("user has no email address")
}
// Generate tracking ID
trackingID := generateTrackingID()
// Send email
if err := s.emailService.SendNoResidenceOnboardingEmail(user.Email, user.FirstName, s.baseURL, trackingID); err != nil {
return err
}
// Record that email was sent
if err := s.RecordEmailSent(user.ID, models.OnboardingEmailNoResidence, trackingID); err != nil {
// Email was sent but we failed to record it - log but don't fail
log.Error().Err(err).Uint("user_id", user.ID).Msg("Failed to record no-residence email sent")
}
return nil
}
// sendNoTasksEmail sends the no-tasks onboarding email to a user
func (s *OnboardingEmailService) sendNoTasksEmail(user models.User) error {
if user.Email == "" {
return fmt.Errorf("user has no email address")
}
// Generate tracking ID
trackingID := generateTrackingID()
// Send email
if err := s.emailService.SendNoTasksOnboardingEmail(user.Email, user.FirstName, s.baseURL, trackingID); err != nil {
return err
}
// Record that email was sent
if err := s.RecordEmailSent(user.ID, models.OnboardingEmailNoTasks, trackingID); err != nil {
// Email was sent but we failed to record it - log but don't fail
log.Error().Err(err).Uint("user_id", user.ID).Msg("Failed to record no-tasks email sent")
}
return nil
}
// SendOnboardingEmailToUser manually sends an onboarding email to a specific user
// This is used by admin to force-send emails regardless of eligibility criteria
func (s *OnboardingEmailService) SendOnboardingEmailToUser(userID uint, emailType models.OnboardingEmailType) error {
// Load the user
var user models.User
if err := s.db.First(&user, userID).Error; err != nil {
if err == gorm.ErrRecordNotFound {
return fmt.Errorf("user not found")
}
return fmt.Errorf("failed to load user: %w", err)
}
if user.Email == "" {
return fmt.Errorf("user has no email address")
}
// Check if already sent (for tracking purposes, we still record but warn)
alreadySent := s.HasSentEmail(userID, emailType)
// Generate tracking ID
trackingID := generateTrackingID()
// Send email based on type
var sendErr error
switch emailType {
case models.OnboardingEmailNoResidence:
sendErr = s.emailService.SendNoResidenceOnboardingEmail(user.Email, user.FirstName, s.baseURL, trackingID)
case models.OnboardingEmailNoTasks:
sendErr = s.emailService.SendNoTasksOnboardingEmail(user.Email, user.FirstName, s.baseURL, trackingID)
default:
return fmt.Errorf("unknown email type: %s", emailType)
}
if sendErr != nil {
return fmt.Errorf("failed to send email: %w", sendErr)
}
// If already sent before, delete the old record first to allow re-recording
// This allows admins to "resend" emails while still tracking them
if alreadySent {
s.db.Where("user_id = ? AND email_type = ?", userID, emailType).Delete(&models.OnboardingEmail{})
}
// Record that email was sent
if err := s.RecordEmailSent(userID, emailType, trackingID); err != nil {
log.Error().Err(err).Uint("user_id", userID).Str("email_type", string(emailType)).Msg("Failed to record onboarding email sent")
}
log.Info().
Uint("user_id", userID).
Str("email_type", string(emailType)).
Str("email", user.Email).
Bool("was_resend", alreadySent).
Msg("Onboarding email sent manually")
return nil
}