AI SaaS Onboarding Email Agent

curl -X POST https://api.robotomail.com/v1/mailboxes \
  -H "Authorization: Bearer rm_live_key" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "onboarding",
    "domainId": "dom_acmeanalytics",
    "displayName": "Kai from Acme Analytics"
  }'

// Behavioral trigger: runs on a schedule, checks user activity
async function sendBehavioralOnboardingEmails() {
  const users = await db.users.findStalled({
    signedUpAfter: daysAgo(7),
    hasNotCompleted: "first_data_source",
  });

  for (const user of users) {
    const daysSinceSignup = daysBetween(user.createdAt, new Date());
    const template = selectTemplate(user.onboardingStep, daysSinceSignup);

    const personalizedEmail = await generateOnboardingEmail({
      userName: user.name,
      template,
      userActivity: await db.activity.getRecent(user.id),
      product: user.plan,
    });

    await fetch(`https://api.robotomail.com/v1/mailboxes/${mailboxId}/messages`, {
      method: "POST",
      headers: {
        "Authorization": "Bearer rm_live_key",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        to: [user.email],
        subject: personalizedEmail.subject,
        bodyText: personalizedEmail.body,
      }),
    });
  }
}

curl -X POST https://api.robotomail.com/v1/mailboxes/{mailbox_id}/messages \
  -H "Authorization: Bearer rm_live_key" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["[email protected]"],
    "subject": "Quick tip: connecting your first data source",
    "bodyText": "Hi Alex,\n\nI noticed you created your account yesterday but haven\'t connected a data source yet. That\'s the step that unlocks everything — dashboards, alerts, and automated reports.\n\nHere\'s the fastest way to get started:\n\n1. Go to Settings > Integrations\n2. Click \"Add Data Source\"\n3. Choose your database type (we support PostgreSQL, MySQL, BigQuery, and 20+ others)\n\nThe whole process takes about 2 minutes. Once connected, I\'ll send you a guide on building your first dashboard.\n\nStuck on anything? Just reply to this email — I\'m here to help.\n\nKai from Acme Analytics"
  }'

curl -X POST https://api.robotomail.com/v1/webhooks \
  -H "Authorization: Bearer rm_live_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/api/onboarding-inbox",
    "events": ["message.received"],
    "mailboxId": "mbx_onboarding_01"
  }'

{
  "event": "message.received",
  "data": {
    "id": "msg_ob_4k1m",
    "from": "[email protected]",
    "to": ["[email protected]"],
    "subject": "Re: Quick tip: connecting your first data source",
    "text": "Hi Kai, I'm trying to connect our PostgreSQL database but getting a connection timeout error. We're behind a corporate firewall — do I need to whitelist any IPs?",
    "receivedAt": "2026-03-22T11:20:00Z",
    "threadId": "thr_ob_321"
  }
}

async function handleOnboardingReply(payload) {
  const { from, text, threadId } = payload.data;

  // Look up the user and their onboarding state
  const user = await db.users.findByEmail(from);
  const onboardingState = await db.onboarding.findByUser(user.id);

  // Classify the reply — is it a question, a blocker, or just a thank-you?
  const intent = await classifyOnboardingReply(text, {
    currentStep: onboardingState.currentStep,
    product: "acme-analytics",
  });
  // => { type: "support_question", topic: "connectivity", blocker: true }

  if (intent.blocker) {
    // Generate a contextual help response
    const helpResponse = await generateHelpResponse({
      question: text,
      currentStep: onboardingState.currentStep,
      knowledgeBase: await getRelevantDocs(intent.topic),
    });

    await fetch(`https://api.robotomail.com/v1/mailboxes/${mailboxId}/messages`, {
      method: "POST",
      headers: {
        "Authorization": "Bearer rm_live_key",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        to: [from],
        subject: `Re: ${payload.data.subject}`,
        bodyText: helpResponse,
        inReplyTo: threadId,
      }),
    });

    // Track the blocker for product analytics
    await db.onboardingBlockers.create({
      userId: user.id,
      step: onboardingState.currentStep,
      topic: intent.topic,
      resolvedViaEmail: true,
    });
  }

  // If user completed the step, advance to next onboarding email
  if (intent.type === "step_completed") {
    await db.onboarding.update(user.id, {
      currentStep: onboardingState.currentStep + 1,
    });
    // Next behavioral email will trigger based on updated state
  }
}