authentikate/docs/config/email.md

# 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:

```bash
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

```bash
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](https://support.google.com/accounts/answer/185833), 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

```bash
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:

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```yaml
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:

```bash
# 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:

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

## Testing Email Configuration

### Send Test Email

AuthentiKate includes a command to test email sending:

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```dns
# 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.