> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.treem.io/treem-dao/email-system/smtp-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.