Email Configuration

Email configuration in Skycloak allows you to customize all authentication-related emails and use your own SMTP server for sending. This ensures consistent branding and reliable email delivery for your users.

Email Types in Skycloak

Skycloak sends various types of authentication emails:

1. Welcome Email - Sent when users first register
2. Email Verification - Confirms user email addresses
3. Password Reset - Allows users to reset forgotten passwords
4. Multi-Factor Authentication - MFA setup and verification codes
5. Account Security - Security alerts and notifications
6. Invitation Emails - When inviting users to your application

Email Template Customization

Accessing Email Templates

1. Navigate to Email in your Skycloak dashboard
2. Select the template you want to customize
3. Edit the template using the visual editor or HTML

Template Variables

All email templates support dynamic variables:

{{user.firstName}} - User's first name
{{user.lastName}} - User's last name
{{user.email}} - User's email address
{{application.name}} - Your application name
{{link.url}} - Action link (verification, reset, etc.)
{{link.expirationTime}} - Link expiration time
{{company.name}} - Your company name
{{company.logo}} - Your uploaded logo

Customization Options

For each email template, you can customize:

1. Subject Line - Personalized with variables
2. Header Content - Logo and branding
3. Body Content - Main message and styling
4. Footer Content - Links and legal text
5. Call-to-Action Buttons - Colors and text
6. Overall Styling - Fonts, colors, spacing

Email Template Best Practices

1. Keep it Simple: Clean, focused designs work best
2. Mobile Responsive: 60% of emails are opened on mobile
3. Clear CTAs: Make action buttons prominent
4. Brand Consistency: Match your application’s look
5. Accessibility: Use good contrast and alt text

SMTP Configuration

Why Configure SMTP?

Using your own SMTP server provides:

• Better Deliverability: Emails from your domain
• Brand Trust: Users recognize the sender
• Compliance: Meet data residency requirements
• Analytics: Track email metrics

Setting Up SMTP

1. Access SMTP Settings: Navigate to Email → SMTP Configuration

2. Enter SMTP Details:

   Host: smtp.yourprovider.com
   Port: 587 (or 465 for SSL)
   Username: your-smtp-username
   Password: your-smtp-password
   From Email: noreply@yourcompany.com
   From Name: Your Company Name

3. Configure Security:

   • Encryption: TLS/STARTTLS recommended
   • Authentication: Usually required
   • SSL/TLS: Enable for secure transmission

4. Test Configuration:

   • Click “Send Test Email”
   • Enter recipient address
   • Verify email delivery

Popular SMTP Providers

SendGrid

Host: smtp.sendgrid.net
Port: 587
Encryption: TLS

Amazon SES

Host: email-smtp.region.amazonaws.com
Port: 587
Encryption: STARTTLS

Mailgun

Host: smtp.mailgun.org
Port: 587
Encryption: TLS

Google Workspace

Host: smtp.gmail.com
Port: 587
Encryption: TLS
Note: Requires app-specific password

Email Branding

Logo Upload

1. Upload your logo (recommended: 200x50px PNG)
2. Logo appears in all email headers
3. Supports transparent backgrounds
4. Automatically optimized for email

Color Scheme

Customize email colors to match your brand:

• Primary Color: Buttons and links
• Secondary Color: Accents and borders
• Background Color: Email background
• Text Color: Body text

Custom CSS

For advanced customization, add custom CSS:

/* Example custom styles */
.email-header {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

.cta-button {
  border-radius: 8px;
  padding: 14px 28px;
  font-weight: 600;
}

Advanced Email Theme Customization (Business & Enterprise)

Business and Enterprise customers can download and customize the complete email theme package, including all templates and message properties.

Theme-Based Email Customization

When you upload a custom theme that includes email templates, it provides complete control over:

1. Message Properties - All email text content via messages_en.properties
2. HTML Templates - Full control over email structure and layout
3. Styling - Complete CSS customization for all elements
4. Multi-language - Support for internationalization

Understanding the Email Theme System

Note

Important: Email customization through themes uses the message properties file (messages_en.properties) as the primary customization point. Most text changes happen here, not in the template files.

Key Files in Email Themes

email/
├── html/                           # HTML email templates
│   ├── email-verification.ftl     # Account verification
│   ├── password-reset.ftl         # Password reset
│   ├── executeActions.ftl         # Required actions
│   └── template.ftl              # Base template
├── text/                          # Plain text versions
└── messages/
    └── messages_en.properties     # ALL email text content

Message Properties - Your Control Center

The messages_en.properties file controls all email text:

# Email Subjects
emailVerificationSubject=Welcome to {2} - Please Verify Your Email
passwordResetSubject=Password Reset Request for {2}

# Email Body Content (with placeholders)
emailVerificationBody=Welcome to {2}!\n\n\
Please verify your email by clicking below:\n\n\
{0}\n\n\
This link expires in {3}.\n\n\
Thank you!

# Custom Branding (added by Skycloak)
companyName=Your Company Name
footerText=© 2024 Your Company. All rights reserved.
primaryColor=#3B82F6

Placeholder Reference:

• {0} - Action link URL
• {1} - Link expiration (minutes)
• {2} - Realm/Application name
• {3} - Human-readable expiration
• {4} - Username

Quick Customization Examples

Professional Welcome Email

emailVerificationSubject=Welcome to {2} - Activate Your Account
emailVerificationBody=Thank you for joining {2}!\n\n\
Your account is almost ready. Please verify your email:\n\n\
{0}\n\n\
Once verified, you'll have access to all premium features.\n\n\
This link expires in {3}.\n\n\
Best regards,\n\
The {2} Team

Security-Focused Password Reset

passwordResetSubject=🔒 Security Alert: Password Reset for {2}
passwordResetBody=A password reset was requested for your account.\n\n\
If this was you, click here:\n\
{0}\n\n\
If not, please ignore this email. Your account remains secure.\n\n\
Expires in: {3}

Download → Customize → Upload Workflow

1. Download Current Theme (Business/Enterprise only)

   • Navigate to Branding page
   • Click “Download Theme”
   • Receive ZIP with login + email folders

2. Modify Message Properties

   • Edit email/messages/messages_en.properties
   • Update subjects, body text, and custom properties
   • Keep all placeholders ({0}, {1}, etc.) intact

3. Test and Upload

   • ZIP the modified theme
   • Upload via Custom Theme section
   • Apply to see changes

Advanced Template Modifications

For complete control, modify the FreeMarker templates:

<!-- email/html/template.ftl -->
<html>
<head>
    <style>
        .email-container {
            max-width: 600px;
            font-family: ${properties.fontFamily!'Arial, sans-serif'};
        }
        .header {
            background: ${properties.primaryColor!'#3B82F6'};
            padding: 30px;
        }
        .button {
            background: ${properties.primaryColor!'#3B82F6'};
            color: white;
            padding: 12px 24px;
            text-decoration: none;
            border-radius: 6px;
        }
    </style>
</head>
<body>
    <div class="email-container">
        <div class="header">
            <img src="${properties.headerLogoLight}" alt="${properties.companyName}">
        </div>
        <div class="content">
            <#nested>
        </div>
        <div class="footer">
            ${properties.footerText}
        </div>
    </div>
</body>
</html>

Best Practices for Email Themes

1. Always Backup: Keep original theme before modifying
2. Test Thoroughly: Check all email types after changes
3. Preserve Variables: Never remove {0}, {1} placeholders
4. Use UTF-8: Save files with UTF-8 encoding
5. Mobile First: Design for mobile email clients

Learn More

For a complete guide on email theme customization including designer-developer collaboration, visual examples, and technical details, see our comprehensive Email Theme Customization Tutorial.

Caution

Note: When a custom theme with email templates is active, the visual email template editor in the Email page is disabled to prevent conflicts. All email customization must be done through the theme files.

Email Delivery Best Practices

Improve Deliverability

1. SPF Records: Add Skycloak to your SPF record
2. DKIM Signing: Enable in SMTP settings
3. Consistent From Address: Use a recognizable sender
4. Avoid Spam Triggers: No excessive caps or symbols
5. Include Unsubscribe: For marketing emails

Monitor Email Performance

Track key metrics:

• Delivery Rate: Should be >95%
• Open Rate: Aim for >20% for transactional
• Click Rate: Higher is better for CTAs
• Bounce Rate: Keep under 2%

Localization and Internationalization

Multi-Language Support

1. Create templates for each language
2. Auto-detect user language preference
3. Fallback to default language
4. Support RTL languages

Translation Management

• Use translation variables
• Maintain consistency across languages
• Test all language versions
• Consider cultural differences

Testing Email Templates

Preview Mode

1. Select any template
2. Click “Preview”
3. View desktop and mobile versions
4. Test with sample data

Send Test Emails

1. Configure test recipients
2. Send to multiple email clients
3. Check rendering in:
   • Gmail
   • Outlook
   • Apple Mail
   • Mobile clients

Troubleshooting Email Issues

Common Problems

1. Emails Not Sending

   • Verify SMTP credentials
   • Check firewall/port access
   • Review error logs

2. Emails in Spam

   • Configure SPF/DKIM
   • Check sender reputation
   • Avoid spam trigger words

3. Broken Formatting

   • Test in multiple clients
   • Use inline CSS
   • Avoid complex layouts

4. Slow Delivery

   • Check SMTP server performance
   • Consider email queue size
   • Upgrade SMTP provider plan

Debug Mode

Enable debug mode to troubleshoot:

1. Go to Email Settings
2. Enable “Debug Mode”
3. View detailed logs for each email
4. Disable when issues are resolved

Integration with Other Features

Domain Management

• Emails use your custom domain
• Consistent sender addresses
• Better deliverability

Branding

• Unified brand experience
• Consistent colors and logos
• Matching login pages

User Management

• Targeted email campaigns
• Role-based notifications
• Automated workflows

Email Templates Reference

Welcome Email

• Sent on user registration
• Includes getting started info
• Can include verification link

Password Reset

• Secure reset link
• Customizable expiration time
• Security best practices

Email Verification

• Required for new accounts
• Resendable by users
• Clear instructions

Next Steps

• Email Theme Customization Tutorial - Complete guide for developers and designers
• Set up custom domain for email sending
• Configure branding to match emails
• Review security settings for email