feat(backend): implement welcome email functionality for new users

Author: Lasim

services/backend/src/email/emailService.ts

@@ -2,6 +2,7 @@ import * as nodemailer from 'nodemailer';
 import type { Transporter } from 'nodemailer';
 import type { FastifyBaseLogger } from 'fastify';
 import { GlobalSettingsService } from '../services/globalSettingsService';
+import { GlobalSettings } from '../global-settings/helpers';
 import { TemplateRenderer } from './templateRenderer';
 import { 
   SendEmailOptionsSchema, 
@@ -293,6 +294,15 @@ export class EmailService {
     }
   }
 
+  /**
+   * Check if welcome emails should be sent
+   */
+  static async shouldSendWelcomeEmail(): Promise<boolean> {
+    const smtpEnabled = await GlobalSettings.getBoolean('smtp.enabled', false);
+    const welcomeEmailEnabled = await GlobalSettings.getBoolean('global.send_welcome_email', false);
+    return smtpEnabled && welcomeEmailEnabled;
+  }
+
   /**
    * Send a welcome email (type-safe helper)
    */

services/backend/src/email/templates/welcome.pug

@@ -6,52 +6,63 @@ block content
   h1 Welcome to DeployStack, #{userName}!
 
   p
-    | We're excited to have you join our community. Your account has been successfully created and you're ready to start deploying your applications with ease.
-  
-  p
-    strong Your account details:
-    br
-    | Email: #{userEmail}
-    br
-    | Registration Date: #{new Date().toLocaleDateString()}
+    | Thanks for joining our mission to simplify MCP complexity for development teams. Your account is now active, and you're ready to eliminate credential management hassles and get productive with MCP tools in minutes, not hours.
 
   .text-center
-    a.button(href=loginUrl) Get Started - Login to Your Account
+    a.button(href=loginUrl) Install DeployStack Gateway
+  
+  h2 Ready to get started?
 
-  h2 What's Next?
+  p Here's how to get your MCP tools working instantly:
 
-  p Here are some things you can do to get started:
+  .steps
+    p
+      strong 1. Install the gateway:
+      br
+      code npm install -g @deploystack/gateway
+    
+    p
+      strong 2. Login to your account:
+      br
+      code deploystack login
+    
+    p
+      strong 3. Start using your team's MCP tools:
+      br
+      code deploystack start
+    
+    p
+      strong 4. Configure VS Code:
+      br
+      | Replace your MCP config with our gateway endpoint:
+      br
+      code "url": "http://localhost:9095/sse"
+  
+  h2 What's next?
 
   ul
+    li 
+      strong Add your first MCP server 
+      | - Browse our catalog and add tools like GitHub, BrightData, or Weather
     li
-      strong Set up your first project
-      | - Create your first deployment stack and configure your environment
-    li
-      strong Explore the dashboard
-      | - Familiarize yourself with the interface and available features
-    li
-      strong Configure integrations
-      | - Connect your favorite tools and services to streamline your workflow
-    li
-      strong Join our community
-      | - Connect with other developers and share your experiences
+      strong Invite team members 
+      | - Share secure access to MCP tools without credential sharing
 
-  h2 Need Help?
+  h2 Need help?
 
-  p
-    | If you have any questions or need assistance getting started, our support team is here to help. You can:
+  p We're here to help you succeed:
 
   ul
-    li Check out our documentation and tutorials
-    li Browse our FAQ section
-    if supportEmail
-      li
-        | Contact our support team at 
-        a(href=`mailto:${supportEmail}`)= supportEmail
-    li Join our community forums for tips and discussions
+    li 📚 Check our 
+      a(href="https://docs.deploystack.io/quick-start") quick start guide
+    li 💬 Join our 
+      a(href="https://discord.gg/42Ce3S7b3b") Discord community
+    li 🔍 Browse the 
+      a(href=loginUrl) MCP catalog
+      |  for available tools
 
   p
-    | Thank you for choosing DeployStack. We look forward to helping you streamline your deployment process!
+    | We're excited to see what you'll build with zero-configuration MCP access!
 
   p.text-muted
     | Best regards,

services/backend/src/global-settings/global.ts

@@ -64,6 +64,14 @@ export const globalSettings: GlobalSettingsModule = {
       description: 'Maximum number of teams a user can create. This includes both default and custom teams.',
       encrypted: false,
       required: false
+    },
+    {
+      key: 'global.send_welcome_email',
+      defaultValue: false,
+      type: 'boolean',
+      description: 'Send welcome email to users when they verify their email or login via OAuth flows (GitHub, etc.)',
+      encrypted: false,
+      required: false
     }
   ]
 };

services/backend/src/routes/auth/github.ts

@@ -9,6 +9,8 @@ import { eq } from 'drizzle-orm';
 import { generateId } from 'lucia';
 import { generateState } from 'arctic';
 import { GlobalSettingsInitService } from '../../global-settings';
+import { EmailService } from '../../email';
+import { GlobalSettings } from '../../global-settings/helpers';
 
 // Response schemas for GitHub OAuth API
 const errorResponseSchema = z.object({
@@ -320,6 +322,41 @@ export default async function githubAuthRoutes(fastify: FastifyInstance) {
 
         await (db as any).insert(authUserTable).values(newUserData);
 
+        // Send welcome email if enabled (for new OAuth users)
+        try {
+          const shouldSendWelcome = await EmailService.shouldSendWelcomeEmail();
+          if (shouldSendWelcome) {
+            const userName = newUserData.first_name 
+              ? `${newUserData.first_name}${newUserData.last_name ? ` ${newUserData.last_name}` : ''}`
+              : newUserData.username || 'User';
+            
+            const loginUrl = await GlobalSettings.get('global.page_url', 'http://localhost:5173') + '/login';
+            const supportEmail = await GlobalSettings.get('smtp.from_email') || undefined;
+            
+            // Send welcome email asynchronously (don't block OAuth flow)
+            EmailService.sendWelcomeEmail({
+              to: newUserData.email,
+              userName,
+              userEmail: newUserData.email,
+              loginUrl,
+              supportEmail
+            }, fastify.log).catch(error => {
+              fastify.log.warn({
+                error,
+                userId: newUserId,
+                operation: 'send_welcome_email_after_oauth_signup'
+              }, 'Failed to send welcome email after GitHub OAuth signup');
+            });
+          }
+        } catch (error) {
+          // Don't fail OAuth if welcome email fails
+          fastify.log.warn({
+            error,
+            userId: newUserId,
+            operation: 'send_welcome_email_after_oauth_signup'
+          }, 'Error occurred while trying to send welcome email after GitHub OAuth signup');
+        }
+
         // Create default team for the user
         try {
           const { TeamService } = await import('../../services/teamService');

services/backend/src/routes/auth/verifyEmail.ts

@@ -1,5 +1,9 @@
 import type { FastifyInstance } from 'fastify';
 import { EmailVerificationService } from '../../services/emailVerificationService';
+import { EmailService } from '../../email';
+import { GlobalSettings } from '../../global-settings/helpers';
+import { getDb, getSchema } from '../../db';
+import { eq } from 'drizzle-orm';
 
 // Reusable Schema Constants
 const VERIFY_EMAIL_QUERYSTRING_SCHEMA = {
@@ -109,6 +113,63 @@ export default async function verifyEmailRoute(server: FastifyInstance) {
           return reply.status(400).type('application/json').send(jsonString);
         }
 
+        // Send welcome email if enabled
+        try {
+          const shouldSendWelcome = await EmailService.shouldSendWelcomeEmail();
+          if (shouldSendWelcome && result.userId) {
+            // Get user details to send welcome email
+            const db = getDb();
+            const schema = getSchema();
+            const authUserTable = schema.authUser;
+            
+            if (authUserTable) {
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              const users = await (db as any)
+                .select({
+                  email: authUserTable.email,
+                  first_name: authUserTable.first_name,
+                  last_name: authUserTable.last_name,
+                  username: authUserTable.username
+                })
+                .from(authUserTable)
+                .where(eq(authUserTable.id, result.userId))
+                .limit(1);
+              
+              if (users.length > 0) {
+                const user = users[0];
+                const userName = user.first_name 
+                  ? `${user.first_name}${user.last_name ? ` ${user.last_name}` : ''}`
+                  : user.username || 'User';
+                
+                const loginUrl = await GlobalSettings.get('global.page_url', 'http://localhost:5173') + '/login';
+                const supportEmail = await GlobalSettings.get('smtp.from_email') || undefined;
+                
+                // Send welcome email asynchronously (don't block verification response)
+                EmailService.sendWelcomeEmail({
+                  to: user.email,
+                  userName,
+                  userEmail: user.email,
+                  loginUrl,
+                  supportEmail
+                }, request.log).catch(error => {
+                  request.log.warn({
+                    error,
+                    userId: result.userId,
+                    operation: 'send_welcome_email_after_verification'
+                  }, 'Failed to send welcome email after email verification');
+                });
+              }
+            }
+          }
+        } catch (error) {
+          // Don't fail verification if welcome email fails
+          request.log.warn({
+            error,
+            userId: result.userId,
+            operation: 'send_welcome_email_after_verification'
+          }, 'Error occurred while trying to send welcome email after verification');
+        }
+
         // Clean up expired tokens (housekeeping)
         EmailVerificationService.cleanupExpiredTokens().catch(error => {
           server.log.warn('Failed to cleanup expired tokens:', error);