> For the complete documentation index, see [llms.txt](https://docs.treem.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.treem.io/treem-dao/email-system/smtp-configuration.md).

# SMTP Configuration

## SMTP Configuration

Configure custom email providers or use the default Resend service for sending emails from your Treem DAO platform.

### Overview

The SMTP configuration system allows you to:

* **Use Default Provider**: Resend service (recommended)
* **Add Custom SMTP**: Configure your own email providers
* **Multiple Configurations**: Set up different providers for different purposes
* **Active Configuration**: Only one SMTP config can be active at a time
* **Test Configurations**: Verify settings before making them active

### Default Provider: Resend

**Resend** is the default email service provider, offering:

* High delivery rates (99%+)
* Built-in spam and bounce handling
* Reliable infrastructure
* Easy setup with API key
* No additional configuration required

#### Resend Setup

The default Resend configuration is automatically available and requires no setup. It uses the `RESEND_API_KEY` configured in your Supabase secrets.

### Custom SMTP Configuration

#### When to Use Custom SMTP

Consider custom SMTP when you need:

* **Brand-specific sending domain**: emails from your own domain
* **Higher sending volumes**: enterprise-grade email providers
* **Compliance requirements**: specific email service providers
* **Cost optimization**: bulk sending discounts
* **Integration requirements**: existing email infrastructure

#### Adding SMTP Configuration

1. Navigate to **Admin Dashboard → Settings → Email System**
2. Click on the **Configuration** tab
3. Click **"New Configuration"**

#### Configuration Fields

**Configuration Name**: Descriptive name for this SMTP setup

* Example: "Gmail SMTP", "Company Mail Server"
* Used for identification in the admin interface

**SMTP Host**: Your email provider's SMTP server

* Gmail: `smtp.gmail.com`
* Outlook: `smtp-mail.outlook.com`
* SendGrid: `smtp.sendgrid.net`
* Custom: Your provider's SMTP hostname

**SMTP Port**: The port number for SMTP connections

* **587**: STARTTLS (recommended)
* **465**: SSL/TLS
* **25**: Unencrypted (not recommended)

**Username**: SMTP authentication username

* Usually your email address
* For some providers, it's a specific username

**Password**: SMTP authentication password

* Your email password
* For Gmail/Outlook: App-specific password
* For services like SendGrid: API key

**From Email**: The sender email address

* Must be authorized by your SMTP provider
* Example: `noreply@yourdao.com`

**From Name**: The display name for the sender

* Example: "Treem DAO", "Your DAO Name"
* What recipients see in their inbox

**Use TLS**: Enable/disable transport layer security

* **Recommended**: Always enable for security
* Required by most modern email providers

#### Provider-Specific Setup

**Gmail Configuration**

```
SMTP Host: smtp.gmail.com
SMTP Port: 587
Username: your-email@gmail.com
Password: [App Password - not your regular password]
Use TLS: Yes
```

**Important**: Enable 2-factor authentication and create an App Password:

1. Go to Google Account settings
2. Security → 2-Step Verification
3. App passwords → Generate new app password
4. Use the generated password in SMTP configuration

**Microsoft Outlook/Office 365**

```
SMTP Host: smtp-mail.outlook.com
SMTP Port: 587
Username: your-email@outlook.com
Password: [Your account password or app password]
Use TLS: Yes
```

**SendGrid**

```
SMTP Host: smtp.sendgrid.net
SMTP Port: 587
Username: apikey
Password: [Your SendGrid API Key]
Use TLS: Yes
```

**Mailgun**

```
SMTP Host: smtp.mailgun.org
SMTP Port: 587
Username: [Your Mailgun SMTP username]
Password: [Your Mailgun SMTP password]
Use TLS: Yes
```

#### Testing Configuration

Before activating an SMTP configuration:

1. Click the **Test** button on the configuration card
2. A test email will be sent to the configured "From Email" address
3. Check if the email is received successfully
4. Verify sender name and deliverability

#### Activating Configuration

To make a custom SMTP configuration active:

1. Click **"Set as Active"** on the desired configuration
2. This will deactivate all other custom configurations
3. The system will use this SMTP for all outgoing emails
4. The default Resend service will be disabled

#### Switching Back to Default

To return to using Resend:

1. Deactivate all custom SMTP configurations
2. The system automatically falls back to Resend
3. No additional configuration needed

### Managing Multiple Configurations

#### Use Cases for Multiple Configurations

* **Development vs Production**: Different providers for testing
* **Backup Configuration**: Failover to secondary provider
* **Service-Specific**: Different providers for different email types
* **Geographic Distribution**: Regional email providers

#### Best Practices

1. **Keep one active**: Only one configuration should be active at a time
2. **Test before switching**: Always test new configurations
3. **Document settings**: Keep notes on provider-specific requirements
4. **Monitor delivery**: Watch analytics after switching providers

### Security Considerations

#### Password Security

* **Never share SMTP passwords**: Keep credentials secure
* **Use app passwords**: When available, prefer app-specific passwords
* **Rotate credentials**: Regularly update SMTP passwords
* **Audit access**: Review who has access to SMTP configurations

#### Domain Authentication

For best deliverability with custom domains:

1. **SPF Record**: Add sender policy framework record
2. **DKIM**: Configure domain key identified mail
3. **DMARC**: Set up domain-based message authentication
4. **MX Record**: Ensure proper mail exchange configuration

### Troubleshooting

#### Common SMTP Errors

**Authentication Failed**

* Verify username and password
* Check if 2FA requires app password
* Ensure SMTP authentication is enabled

**Connection Refused**

* Verify SMTP host and port
* Check firewall settings
* Confirm TLS settings match provider requirements

**Sender Not Authorized**

* Verify "From Email" is authorized by provider
* Check domain verification status
* Ensure sender policy framework (SPF) is configured

#### Testing Delivery Issues

1. **Check spam folders**: Test emails might be filtered
2. **Verify recipient**: Ensure test email address is valid
3. **Review provider logs**: Check SMTP provider's sending logs
4. **Test with different recipients**: Try multiple email addresses

#### Provider-Specific Issues

**Gmail Issues**

* Enable "Less secure app access" (not recommended) OR
* Use App Passwords with 2FA (recommended)
* Check Google Account security settings

**Office 365 Issues**

* Verify SMTP authentication is enabled for the account
* Check if the account requires modern authentication
* Ensure the account isn't locked or suspended

### Performance Monitoring

#### Metrics to Track

After configuring custom SMTP:

1. **Delivery Rate**: Percentage of emails successfully delivered
2. **Bounce Rate**: Emails that couldn't be delivered
3. **Response Time**: How quickly emails are sent
4. **Error Rate**: Failed sending attempts

#### Analytics Integration

The email analytics dashboard will show performance metrics for your active SMTP configuration, helping you monitor:

* Daily sending volume
* Success/failure rates
* Response times
* Error patterns

### Migration Guide

#### From Default to Custom SMTP

1. **Prepare Configuration**: Set up your custom SMTP settings
2. **Test Thoroughly**: Verify all email types work correctly
3. **Monitor Closely**: Watch delivery rates after switching
4. **Have Rollback Plan**: Keep default provider as backup

#### Between SMTP Providers

1. **Configure New Provider**: Add new SMTP configuration
2. **Test New Configuration**: Verify functionality
3. **Switch Active Configuration**: Deactivate old, activate new
4. **Monitor Performance**: Watch for delivery issues
5. **Update DNS Records**: If changing domains, update SPF/DKIM

This comprehensive SMTP configuration system ensures reliable email delivery while providing flexibility for your specific needs.