Email Configuration

v0.4.8Updated for nself v0.4.8

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

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 start
  • Web Interface: View emails at https://mail.local.nself.org
  • Email Capture: All emails are captured and displayed in a clean interface
  • No External Dependencies: Everything runs locally

Email Commands

The nself email command provides comprehensive email management.

CommandDescription
nself emailShow current email configuration
nself email setupInteractive setup wizard
nself email listList all 16+ supported providers
nself email configure <provider>Configure a specific provider
nself email validateValidate current configuration
nself email checkSMTP pre-flight connection test
nself email test [email]Send a test email
nself email docs [provider]Show provider documentation
nself email detectDetect current provider

SMTP Pre-flight Check

The nself email check command runs comprehensive validation before you send any emails:

  • DNS Resolution: Verifies SMTP hostname resolves correctly
  • TCP Connectivity: Tests connection to SMTP port
  • SMTP Banner: Validates server response
  • TLS Certificate: Checks SSL/TLS configuration
$ nself email check
✓ DNS resolution: smtp.sendgrid.net → 167.89.118.51
✓ TCP connection: Port 587 open
✓ SMTP banner: 220 smtp.sendgrid.net ESMTP
✓ TLS certificate: Valid, expires 2027-03-15

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:

Transactional

  • • SendGrid
  • • Mailgun
  • • Postmark
  • • Amazon SES

Marketing

  • • Mailchimp Transactional
  • • SparkPost
  • • Mailjet
  • • Sendinblue (Brevo)

Enterprise

  • • Microsoft 365
  • • Google Workspace
  • • SMTP2GO
  • • Custom SMTP

Development

  • • MailPit (default)
  • • Mailhog
  • • Mailtrap
  • • Mailu

Manual Configuration

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

SendGrid Example

# SendGrid Configuration
AUTH_SMTP_HOST=smtp.sendgrid.net
AUTH_SMTP_PORT=587
AUTH_SMTP_USER=apikey
AUTH_SMTP_PASS=your_sendgrid_api_key
AUTH_SMTP_SECURE=true
AUTH_SMTP_SENDER=your-sender@yourdomain.com

AWS SES Example

# AWS SES Configuration
AUTH_SMTP_HOST=email-smtp.us-west-2.amazonaws.com
AUTH_SMTP_PORT=587
AUTH_SMTP_USER=your_aws_access_key
AUTH_SMTP_PASS=your_aws_secret_key
AUTH_SMTP_SECURE=true
AUTH_SMTP_SENDER=your-sender@yourdomain.com

Generic SMTP Example

# Generic SMTP Configuration
AUTH_SMTP_HOST=your-smtp-server.com
AUTH_SMTP_PORT=587
AUTH_SMTP_USER=your_username
AUTH_SMTP_PASS=your_password
AUTH_SMTP_SECURE=true
AUTH_SMTP_SENDER=your-sender@yourdomain.com

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
MAILPIT_ENABLED=true

# Production (uses configured provider)
ENV=prod
AUTH_SMTP_HOST=your-production-smtp.com
AUTH_SMTP_PORT=587
AUTH_SMTP_USER=prod_user
AUTH_SMTP_PASS=prod_password
AUTH_SMTP_SECURE=true
AUTH_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 start
  2. Running the test command: nself email test admin@example.com
  3. For MailPit, view at: https://mail.local.nself.org
  4. Triggering a password reset or user registration
  5. 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 https://mail.local.nself.org. If not, check status with nself status mailpit and 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: