thegrind/authentikate
4
0
Fork 0
generated from thegrind/laravel-dockerized
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity
authentikate/docs/config/email.md
Javier Feliz 9db9b0f6b3
All checks were successful
linter / quality (push) Successful in 3m34s
Details
tests / ci (push) Successful in 7m10s
Details
Got claude started on the docs. Will have to update them heavily
2025-08-03 00:23:06 -04:00

7.8 KiB
Raw Blame History

Email Configuration

Email is essential for user invitations, password resets, and account verification. This guide covers how to configure email in AuthentiKate.

Why Email Matters

Email is used for:

  • User Invitations: Send registration links to new users
  • Password Resets: Allow users to reset forgotten passwords
  • Email Verification: Verify user email addresses
  • Account Notifications: Security alerts and updates

Basic SMTP Configuration

Set these environment variables for SMTP email:

MAIL_MAILER=smtp
MAIL_HOST=your-smtp-server.com
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"

Provider-Specific Configurations

Gmail

MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password  # Not your regular Gmail password!
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-email@gmail.com
MAIL_FROM_NAME="Your Name"

Important: Use an App Password, not your regular Gmail password.

Creating Gmail App Password

  1. Enable 2-Factor Authentication on your Google account
  2. Go to Google Account → Security → App passwords
  3. Generate a new app password for "Mail"
  4. Use this 16-character password in MAIL_PASSWORD

Outlook/Hotmail

MAIL_MAILER=smtp
MAIL_HOST=smtp-mail.outlook.com
MAIL_PORT=587
MAIL_USERNAME=your-email@outlook.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-email@outlook.com
MAIL_FROM_NAME="Your Name"

Custom Domain Email

If you have your own domain with email hosting:

MAIL_MAILER=smtp
MAIL_HOST=mail.yourdomain.com
MAIL_PORT=587
MAIL_USERNAME=auth@yourdomain.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"

Email Service Providers

SendGrid

MAIL_MAILER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-sendgrid-api-key
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"

Mailgun

MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=your-mailgun-username
MAIL_PASSWORD=your-mailgun-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"

Amazon SES

MAIL_MAILER=smtp
MAIL_HOST=email-smtp.us-east-1.amazonaws.com  # Change region as needed
MAIL_PORT=587
MAIL_USERNAME=your-ses-smtp-username
MAIL_PASSWORD=your-ses-smtp-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"

Postmark

MAIL_MAILER=smtp
MAIL_HOST=smtp.postmarkapp.com
MAIL_PORT=587
MAIL_USERNAME=your-postmark-token
MAIL_PASSWORD=your-postmark-token
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"

Docker Compose Configuration

Environment Variables

services:
  authentikate:
    image: authentikate/authentikate:latest
    environment:
      # Gmail example
      MAIL_MAILER: smtp
      MAIL_HOST: smtp.gmail.com
      MAIL_PORT: 587
      MAIL_USERNAME: your-email@gmail.com
      MAIL_PASSWORD: your-app-password
      MAIL_ENCRYPTION: tls
      MAIL_FROM_ADDRESS: your-email@gmail.com
      MAIL_FROM_NAME: "AuthentiKate"

Environment File

Create a .env file:

# Email configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-email@gmail.com
MAIL_FROM_NAME="AuthentiKate"

Reference it in docker-compose.yml:

services:
  authentikate:
    image: authentikate/authentikate:latest
    env_file: .env

Testing Email Configuration

Send Test Email

AuthentiKate includes a command to test email sending:

# Test email configuration
docker exec -it authentikate php artisan tinker

# In the tinker console:
Mail::raw('Test email from AuthentiKate', function($message) {
    $message->to('test@example.com')->subject('Test Email');
});

Check Logs

If emails aren't sending, check the logs:

# View container logs
docker logs authentikate

# Look for email-related errors
docker logs authentikate 2>&1 | grep -i mail

Advanced Configuration

Custom SMTP Port

Some providers use different ports:

# Standard ports
MAIL_PORT=25    # Unencrypted (not recommended)
MAIL_PORT=587   # STARTTLS (recommended)
MAIL_PORT=465   # SSL/TLS

# Custom port
MAIL_PORT=2525  # Some providers use alternate ports

SSL/TLS Configuration

# Use TLS (recommended)
MAIL_ENCRYPTION=tls

# Use SSL (older, but still secure)
MAIL_ENCRYPTION=ssl

# No encryption (not recommended)
MAIL_ENCRYPTION=null

Multiple From Addresses

Configure different senders for different email types:

# Default sender
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"

# Admin notifications (configure in application)
ADMIN_EMAIL_FROM=admin@yourdomain.com
ADMIN_EMAIL_NAME="AuthentiKate Admin"

Email Templates

AuthentiKate uses customizable email templates for different purposes:

Invitation Email

  • Subject: "You're invited to join AuthentiKate"
  • Content: Welcome message with registration link
  • Action: "Complete Registration" button

Password Reset

  • Subject: "Reset your AuthentiKate password"
  • Content: Instructions for password reset
  • Action: "Reset Password" button

Email Verification

  • Subject: "Verify your email address"
  • Content: Verification instructions
  • Action: "Verify Email" button

Troubleshooting

Common Issues

"Connection could not be established"

Swift_TransportException: Connection could not be established

Solutions:

  • Check SMTP server address and port
  • Verify firewall isn't blocking SMTP ports
  • Try different encryption settings (TLS vs SSL)

"Authentication failed"

Swift_TransportException: Expected response code 235 but got code "535"

Solutions:

  • Verify username and password
  • Use App Password for Gmail
  • Check if 2FA is enabled and requires app password

"From address not allowed"

Message: From address not allowed

Solutions:

  • Ensure MAIL_FROM_ADDRESS matches authenticated user
  • Configure your email provider to allow sending from this address
  • Use provider's verified domain

Debug Mode

Enable email debugging:

# Add to environment
LOG_LEVEL=debug
MAIL_LOG_CHANNEL=single

# Check detailed logs
docker logs authentikate | grep -i mail

Test with Different Providers

If one provider doesn't work, try another:

# Try Gmail first (easiest to set up)
MAIL_HOST=smtp.gmail.com

# Then try SendGrid (good for production)
MAIL_HOST=smtp.sendgrid.net

# Or use a transactional service
MAIL_HOST=smtp.mailgun.org

Production Recommendations

Dedicated Email Service

For production, use a dedicated email service:

  • SendGrid: Easy setup, good deliverability
  • Mailgun: Reliable, detailed analytics
  • Amazon SES: Cost-effective, AWS integration
  • Postmark: Fast delivery, great for transactional emails

Domain Authentication

Set up SPF, DKIM, and DMARC records:

# SPF record
yourdomain.com. TXT "v=spf1 include:_spf.google.com ~all"

# DKIM (provided by email service)
default._domainkey.yourdomain.com. TXT "v=DKIM1; k=rsa; p=..."

# DMARC
_dmarc.yourdomain.com. TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"

Monitoring

Monitor email delivery:

  • Track bounce rates
  • Monitor spam complaints
  • Watch delivery statistics
  • Set up alerts for failures

Your email configuration is now ready! Users will receive professional-looking emails for invitations, password resets, and other notifications.