Function maybeSendUsageThresholdEmail

apps/sim/lib/billing/core/usage.ts:823–1001

(params: {
  scope: 'user' | 'organization'
  planName: string
  percentBefore: number
  percentAfter: number
  userId?: string
  userEmail?: string
  userName?: string
  organizationId?: string
  /** Workspace the usage occurred in, used to build a live upgrade/billing link. */
  workspaceId?: string
  currentUsageAfter: number
  limit: number
})

 * - For organization plans, emails owners/admins who have notifications enabled.
 */
export async function maybeSendUsageThresholdEmail(params: {
  scope: 'user' | 'organization'
  planName: string
  percentBefore: number
  percentAfter: number
  userId?: string
  userEmail?: string
  userName?: string
  organizationId?: string
  /** Workspace the usage occurred in, used to build a live upgrade/billing link. */
  workspaceId?: string
  currentUsageAfter: number
  limit: number
}): Promise<void> {
  try {
    if (!isBillingEnabled) return
    if (params.limit <= 0 || params.currentUsageAfter <= 0) return

    const baseUrl = getBaseUrl()
    const isFreeUser = params.planName === 'Free'

    const upgradeCreditsLink = params.workspaceId
      ? `${baseUrl}${buildUpgradeHref(params.workspaceId, 'credits')}`
      : `${baseUrl}/workspace`
    const billingSettingsLink = params.workspaceId
      ? `${baseUrl}/workspace/${params.workspaceId}/settings/billing`
      : `${baseUrl}/workspace`

    // Check for 80% threshold crossing — used for paid users (budget warning) and free users (upgrade nudge)
    const crosses80 = params.percentBefore < 80 && params.percentAfter >= 80
    // Check for 100% threshold (free users only — credits exhausted)
    const crosses100 = params.percentBefore < 100 && params.percentAfter >= 100

    // Skip if no thresholds crossed
    if (!crosses80 && !crosses100) return

    // For 80% threshold email (paid users only)
    if (crosses80 && !isFreeUser) {
      const ctaLink = billingSettingsLink
      const sendTo = async (email: string, name?: string) => {
        const prefs = await getEmailPreferences(email)
        if (prefs?.unsubscribeAll || prefs?.unsubscribeNotifications) return

        const html = await renderUsageThresholdEmail({
          userName: name,
          planName: params.planName,
          percentUsed: Math.min(100, Math.round(params.percentAfter)),
          currentUsage: params.currentUsageAfter,
          limit: params.limit,
          ctaLink,
        })

        await sendEmail({
          to: email,
          subject: getEmailSubject('usage-threshold'),
          html,
          emailType: 'notifications',
        })