Welcome and Onboarding Emails

// Email 1: Transactional — no unsubscribe needed
await sendEmail({
  from: 'welcome@mail.yourapp.com',
  to: user.email,
  subject: 'Welcome to YourApp — verify your email',
  tags: ['welcome', 'transactional'],
  // Account verification link, getting started steps
});

// Email 2+: Marketing — include unsubscribe
await sendEmail({
  from: 'tips@mail.yourapp.com',
  to: user.email,
  subject: 'Get the most out of YourApp',
  tags: ['onboarding', 'marketing'],
  headers: {
    'List-Unsubscribe': '<https://yourapp.com/unsubscribe?token=xxx>',
    'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
  },
  // Feature tips, tutorials, best practices
});

async function sendOnboardingEmail(user, emailNumber) {
  // Skip "Getting Started" if user already completed setup
  if (emailNumber === 2 && user.hasCompletedSetup) {
    return scheduleNextEmail(user, 3);
  }

  // Skip "Key Feature" if user already used it
  if (emailNumber === 3 && user.hasUsedFeatureX) {
    return scheduleNextEmail(user, 4);
  }

  // Stop sequence if user is already active
  if (user.actionsThisWeek > 5) {
    return; // They don't need onboarding nudges
  }

  await sendEmail({
    from: 'tips@mail.yourapp.com',
    to: user.email,
    subject: onboardingSubjects[emailNumber],
    html: onboardingTemplates[emailNumber](user),
    tags: ['onboarding', `onboarding-${emailNumber}`],
  });

  scheduleNextEmail(user, emailNumber + 1);
}

<div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 600px; margin: 0 auto;">
  <h2 style="color: #1a1a1a;">Welcome to YourApp, {{firstName}}</h2>

  <p style="color: #4a4a4a; line-height: 1.6;">
    Your account is ready. Here's how to get started in under 5 minutes.
  </p>

  <!-- Single primary CTA -->
  <div style="background-color: #f5f3ff; border-radius: 8px; padding: 20px; margin: 24px 0;">
    <h3 style="margin: 0 0 8px; font-size: 16px;">Step 1: Send your first email</h3>
    <p style="color: #4a4a4a; margin: 0 0 16px; line-height: 1.6;">
      Set up your sending domain and send a test email to see Lettr in action.
    </p>
    <a href="{{dashboardUrl}}/domains"
       style="background-color: #6366F1; color: #ffffff; padding: 10px 24px;
              text-decoration: none; border-radius: 6px; font-weight: 600;">
      Set Up Your Domain
    </a>
  </div>

  <!-- Quick links (secondary) -->
  <p style="color: #4a4a4a; line-height: 1.6;">
    Or jump to what you need:
  </p>
  <ul style="color: #4a4a4a; line-height: 2;">
    <li><a href="{{docsUrl}}/quickstart" style="color: #6366F1;">Quickstart guide</a></li>
    <li><a href="{{docsUrl}}/api-reference" style="color: #6366F1;">API reference</a></li>
    <li><a href="{{dashboardUrl}}/api-keys" style="color: #6366F1;">Get your API key</a></li>
  </ul>

  <p style="color: #6b6b6b; font-size: 14px; line-height: 1.6;">
    Need help? Reply to this email or reach us at
    <a href="mailto:support@yourapp.com" style="color: #6366F1;">support@yourapp.com</a>.
  </p>
</div>

// Welcome email — sent immediately on signup
const response = await fetch('https://app.lettr.com/api/emails', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LETTR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'welcome@mail.yourapp.com',
    replyTo: 'support@yourapp.com',
    to: user.email,
    subject: `Welcome to YourApp, ${user.firstName}`,
    html: welcomeEmailHtml,
    text: welcomeEmailText,
    tags: ['welcome', 'onboarding-1'],
    metadata: {
      userId: user.id,
      signupSource: user.source,
    },
  }),
});

// Schedule follow-up emails with appropriate delays
async function scheduleOnboardingSequence(user) {
  // Email 1: Immediate
  await sendWelcomeEmail(user);

  // Email 2: 4 hours later (or next morning if signed up late)
  const email2Time = getNextReasonableTime(user.timezone, 4 * 60);
  await queue.add('sendOnboarding', { userId: user.id, email: 2 }, {
    delay: email2Time - Date.now(),
  });

  // Email 3: Day 3
  const email3Time = getNextReasonableTime(user.timezone, 3 * 24 * 60);
  await queue.add('sendOnboarding', { userId: user.id, email: 3 }, {
    delay: email3Time - Date.now(),
  });
}

function getNextReasonableTime(timezone, minutesFromNow) {
  // Target 10 AM local time if the calculated time falls outside 8AM–6PM
  const targetTime = new Date(Date.now() + minutesFromNow * 60 * 1000);
  const localHour = getHourInTimezone(targetTime, timezone);

  if (localHour < 8 || localHour >= 18) {
    // Push to 10 AM next business day
    return getNext10AM(timezone);
  }

  return targetTime.getTime();
}