Email Configuration

nself provides comprehensive email support with zero-configuration for development and simple setup for production across 16+ email providers.

🎯 Development Email (Zero Configuration)

In development mode, nself automatically sets up MailPit to capture all outgoing emails. No configuration required!

  • Automatic Setup: Works out of the box with nself up
  • Web Interface: View emails at http://mailpit.local.nself.org
  • Email Capture: All emails are captured and displayed in a clean interface
  • No External Dependencies: Everything runs locally

🚀 Production Email Setup

Setting up production email takes just 2 minutes with the interactive setup wizard:

nself email setup

This command will guide you through configuring your preferred email provider and automatically update your environment variables.

Supported Email Providers

nself supports 16+ email providers with automatic configuration:

Popular Providers

  • • SendGrid
  • • AWS SES
  • • Mailgun
  • • Postmark
  • • Mailjet

Generic Options

  • • SMTP (Any Provider)
  • • Custom Configuration
  • • Environment Variables

Manual Configuration

If you prefer manual configuration, you can set the following environment variables in your .env.local file:

SendGrid Example

# SendGrid Configuration
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=your_sendgrid_api_key
SMTP_SENDER=your-sender@yourdomain.com

AWS SES Example

# AWS SES Configuration
SMTP_HOST=email-smtp.us-west-2.amazonaws.com
SMTP_PORT=587
SMTP_USER=your_aws_access_key
SMTP_PASS=your_aws_secret_key
SMTP_SENDER=your-sender@yourdomain.com

Generic SMTP Example

# Generic SMTP Configuration
SMTP_HOST=your-smtp-server.com
SMTP_PORT=587
SMTP_USER=your_username
SMTP_PASS=your_password
SMTP_SENDER=your-sender@yourdomain.com
SMTP_SECURE=true  # Use TLS/SSL

📧 Email Templates

nself comes with built-in email templates for common authentication flows:

  • Welcome Emails: User registration confirmation
  • Password Reset: Secure password reset links
  • Email Verification: Confirm email addresses
  • Magic Links: Passwordless authentication

Templates are automatically configured and can be customized through the Hasura console or by modifying the authentication service configuration.

🔧 Advanced Configuration

Environment-Specific Settings

You can configure different email settings for different environments:

# Development (uses MailPit)
ENV=dev

# Production (uses configured provider)
ENV=prod
SMTP_HOST=your-production-smtp.com
SMTP_PORT=587
SMTP_USER=prod_user
SMTP_PASS=prod_password
SMTP_SENDER=noreply@yourcompany.com

Email Provider Detection

nself automatically detects your email provider based on your SMTP configuration and applies optimized settings:

  • Rate Limiting: Respects provider-specific sending limits
  • Authentication: Uses provider-specific authentication methods
  • SSL/TLS: Applies correct security settings automatically
  • Error Handling: Provider-specific error handling and retry logic

🔍 Testing Email Configuration

After configuring your email provider, you can test it by:

  1. Starting your nself stack: nself up
  2. Accessing the Hasura console at http://hasura.local.nself.org
  3. Triggering a password reset or user registration
  4. Checking your email provider's logs or your email client

📊 Monitoring Email Delivery

Most email providers offer delivery tracking and analytics. You can monitor:

  • Delivery Rates: Track successful email deliveries
  • Bounce Rates: Monitor bounced emails
  • Open Rates: See email engagement (if supported)
  • Error Logs: Debug delivery issues

🛠️ Troubleshooting

Common Issues

Emails Not Sending in Development

Check that MailPit is running at http://mailpit.local.nself.org. If not, restart with nself restart.

Authentication Errors in Production

Verify your SMTP credentials are correct. Many providers require app-specific passwords instead of your regular password.

Emails Going to Spam

Ensure your SMTP_SENDER domain matches your email provider's authenticated domain. Consider setting up SPF, DKIM, and DMARC records.

Getting Help

If you're still having issues with email configuration: