Skip to content
Fluxbase

Email Services

Fluxbase includes a built-in email system for sending authentication emails (magic links, password resets, email verification) and custom transactional emails.

Overview

Section titled “Overview”

The email system supports multiple providers:

  • SMTP - Standard SMTP servers (Gmail, Outlook, custom servers)
  • SendGrid - SendGrid API integration
  • Mailgun - Mailgun API integration
  • AWS SES - Amazon Simple Email Service

All providers support:

  • Magic link authentication
  • Email verification
  • Password reset emails
  • Custom HTML email templates
  • Fallback to default templates

Quick Start

Section titled “Quick Start”

Choose a provider:

ProviderBest For
SMTPDevelopment, custom servers
SendGridProduction, high volume
MailgunProduction, flexibility
AWS SESAWS infrastructure

Configure (environment variables):

Terminal window
FLUXBASE_EMAIL_ENABLED=true
FLUXBASE_EMAIL_PROVIDER=smtp  # smtp, sendgrid, mailgun, ses
FLUXBASE_EMAIL_FROM_ADDRESS=noreply@yourapp.com
FLUXBASE_EMAIL_FROM_NAME="Your App Name"


# SMTP example
FLUXBASE_EMAIL_SMTP_HOST=smtp.gmail.com
FLUXBASE_EMAIL_SMTP_PORT=587
FLUXBASE_EMAIL_SMTP_USERNAME=your-email@gmail.com
FLUXBASE_EMAIL_SMTP_PASSWORD=your-app-password
FLUXBASE_EMAIL_SMTP_TLS=true

Provider Configuration

Section titled “Provider Configuration”

SMTP

Section titled “SMTP”
Terminal window
FLUXBASE_EMAIL_PROVIDER=smtp
FLUXBASE_EMAIL_SMTP_HOST=smtp.gmail.com
FLUXBASE_EMAIL_SMTP_PORT=587
FLUXBASE_EMAIL_SMTP_USERNAME=your-email@gmail.com
FLUXBASE_EMAIL_SMTP_PASSWORD=your-app-password
FLUXBASE_EMAIL_SMTP_TLS=true

Common SMTP hosts:

ProviderHostPortNotes
Gmailsmtp.gmail.com587Requires App Password
Outlooksmtp.office365.com587Use account password
Custommail.yourserver.com587TLS recommended

SendGrid

Section titled “SendGrid”
Terminal window
FLUXBASE_EMAIL_PROVIDER=sendgrid
FLUXBASE_EMAIL_SENDGRID_API_KEY=SG.xxxxxxxxxxxxxxxxxxxxx

Setup:

  1. Sign up at sendgrid.com
  2. Settings → client keys → Create API Key (Mail Send permission)
  3. Verify domain: Settings → Sender Authentication → Add DNS records

Mailgun

Section titled “Mailgun”
Terminal window
FLUXBASE_EMAIL_PROVIDER=mailgun
FLUXBASE_EMAIL_MAILGUN_API_KEY=key-xxxxxxxxxxxxxxxxxxxxx
FLUXBASE_EMAIL_MAILGUN_DOMAIN=mg.yourapp.com

Setup:

  1. Sign up at mailgun.com
  2. Add domain: Sending → Domains → Add DNS records
  3. Get API key: Settings → client keys → Copy Private API key

AWS SES

Section titled “AWS SES”
Terminal window
FLUXBASE_EMAIL_PROVIDER=ses
FLUXBASE_EMAIL_SES_ACCESS_KEY=AKIAXXXXXXXXXXXXXXXX
FLUXBASE_EMAIL_SES_SECRET_KEY=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
FLUXBASE_EMAIL_SES_REGION=us-east-1

Setup:

  1. Go to SES console
  2. Verify email/domain
  3. Request production access (sandbox mode only sends to verified addresses)
  4. Create IAM user with AmazonSESFullAccess policy

Email Templates

Section titled “Email Templates”

Fluxbase includes default HTML templates for magic links, email verification, and password resets.

Custom templates:

email:
  magic_link_template: /path/to/magic-link.html
  verification_template: /path/to/verification.html
  password_reset_template: /path/to/password-reset.html

Template variables:

  • {{.Link}} - Full action URL
  • {{.Token}} - Token only

Troubleshooting

Section titled “Troubleshooting”
IssueSolution
Emails not sendingCheck logs for “Email service initialized”, verify SMTP connection with telnet smtp.gmail.com 587, confirm credentials are correct
Gmail “Less secure app”Use App Password: Enable 2FA → Generate app password → Use in config
SendGrid 401Verify API key has “Mail Send” permission: Settings → client keys → Check permissions
Mailgun domain not verifiedAdd DNS records: Copy TXT/MX records → Add to DNS provider → Wait 5-10 min → Verify
AWS SES sandboxIn sandbox, only sends to verified addresses. Request production access or verify recipients
SMTP timeoutCheck firewall allows port 587/465, verify host/port, try different ports, check if hosting provider blocks SMTP

Best Practices

Section titled “Best Practices”
PracticeDescription
Use environment variablesNever commit client keys/passwords to version control. Use FLUXBASE_EMAIL_* env vars
Verify domainAlways verify sending domain in production to improve deliverability and avoid spam
Separate dev/prodUse SMTP/MailHog for development, SendGrid/Mailgun/SES for production
Monitor deliverySet up webhooks to track bounces/complaints. Keep bounce rate < 5%
Respect rate limitsGmail: 500/day, SendGrid: 100/day (free), Mailgun: 5k/month (free), SES: 1/sec (sandbox)
Handle failuresDon’t block user flows if email fails. Log errors and retry later
Protect credentialsStore in env vars/secrets manager, use IAM roles where possible, rotate regularly
Email authenticationConfigure SPF, DKIM, DMARC DNS records to prevent spoofing and improve deliverability
Content securitySanitize user content, use HTTPS links, include unsubscribe for marketing emails