# Email Deliverability Guide

When setting up email for your Buzzy app, proper configuration is crucial to ensure your emails reach recipients' inboxes rather than being filtered as spam. This guide provides detailed configuration instructions for popular email providers and essential anti-spam best practices.

## Overview

Email deliverability depends on several factors:

* **SMTP Configuration**: Proper server settings and authentication
* **Domain Authentication**: SPF, DKIM, and DMARC records
* **Sender Reputation**: Consistent sending practices and monitoring
* **Content Quality**: Professional email content and formatting

## Generic Anti-Spam Best Practices

### SPF (Sender Policy Framework)

SPF prevents email spoofing by specifying which servers can send email for your domain.

**Action**: Add a TXT record to your domain's DNS:

```
v=spf1 include:[your-provider-spf] -all
```

Replace `[your-provider-spf]` with your email provider's SPF record (see provider sections below).

### DKIM (DomainKeys Identified Mail)

DKIM digitally signs your emails to prove authenticity and prevent tampering.

**Action**:

1. Enable DKIM in your email provider's settings
2. Add the provided CNAME records to your domain's DNS
3. Verify DKIM is active before sending production emails

### DMARC (Domain-based Message Authentication, Reporting, and Conformance)

DMARC tells receiving servers what to do when SPF or DKIM fails and provides reporting.

**Action**: Add a TXT record to your domain's DNS:

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

**Policy Options**:

* `p=none`: Monitor only (recommended for testing)
* `p=quarantine`: Send suspicious emails to spam folder
* `p=reject`: Reject emails that fail authentication (strictest)

### General Best Practices

* **Use a real "From" address**: Avoid generic addresses like noreply@
* **Maintain consistent sending patterns**: Avoid sudden volume spikes
* **Monitor bounce rates**: Keep bounce rates below 5%
* **Use professional email content**: Avoid spam trigger words and excessive formatting
* **Implement proper unsubscribe mechanisms**: Honor unsubscribe requests promptly

## Provider-Specific Configurations

### Microsoft Office 365

**Recommended for**: Organizations already using Microsoft 365 for email

#### SMTP Settings

| Setting        | Value                                                                               |
| -------------- | ----------------------------------------------------------------------------------- |
| SMTP server    | `smtp.office365.com`                                                                |
| SMTP port      | `587` (STARTTLS)                                                                    |
| Encryption     | STARTTLS (sometimes called "TLS")                                                   |
| Authentication | Username + Password (user's O365 email and password or App Password if MFA enabled) |
| Username       | `user@yourdomain.com`                                                               |
| Password       | O365 password (or App Password)                                                     |

**SMTP URL Format**: `smtps://user@yourdomain.com:password@smtp.office365.com:587`

**Note**: Microsoft requires SMTP AUTH to be enabled for the mailbox. [Reference](https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission)

#### Domain Authentication Setup

**SPF Record**:

```
v=spf1 include:spf.protection.outlook.com -all
```

**DKIM Setup**:

1. Go to [Microsoft 365 Defender portal](https://security.microsoft.com/dkimv2)
2. Follow [Microsoft's DKIM instructions](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/use-dkim-to-validate-outbound-email?view=o365-worldwide)
3. Add the two CNAME records shown in the portal to your DNS

**DMARC Record**:

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

#### Office 365 Specific Notes

* **Sending Limits**: Check [Microsoft 365 sending limits](https://learn.microsoft.com/en-us/exchange/recipients-in-exchange-online/mailbox-limits#sending-limits)
* **Message Trace**: Use Microsoft 365 Message Trace to monitor email delivery
* **MFA Considerations**: If Multi-Factor Authentication is enabled, use App Passwords instead of regular passwords

### SendGrid

**Recommended for**: High-volume transactional emails and advanced analytics

#### SMTP Settings

| Setting        | Value                           |
| -------------- | ------------------------------- |
| SMTP server    | `smtp.sendgrid.net`             |
| SMTP port      | `587` (STARTTLS) or `465` (SSL) |
| Encryption     | STARTTLS or SSL                 |
| Authentication | Username + API Key              |
| Username       | `apikey`                        |
| Password       | Your SendGrid API Key           |

**SMTP URL Format**: `smtps://apikey:your_api_key@smtp.sendgrid.net:587`

#### Domain Authentication Setup

**SPF Record**:

```
v=spf1 include:sendgrid.net -all
```

**DKIM Setup**:

1. In SendGrid dashboard, go to Settings > Sender Authentication
2. Authenticate your domain
3. Add the provided CNAME records to your DNS

**DMARC Record**:

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

#### SendGrid Specific Notes

* **API Key Security**: Use API keys with minimal required permissions
* **Dedicated IP**: Consider dedicated IP for high-volume sending
* **Suppression Management**: SendGrid automatically manages bounces and unsubscribes

### Mailgun

**Recommended for**: Developers who need programmatic email control and detailed APIs

#### SMTP Settings

| Setting        | Value                                |
| -------------- | ------------------------------------ |
| SMTP server    | `smtp.mailgun.org`                   |
| SMTP port      | `587` (STARTTLS) or `465` (SSL)      |
| Encryption     | STARTTLS or SSL                      |
| Authentication | Username + Password                  |
| Username       | `postmaster@your-domain.mailgun.org` |
| Password       | Your Mailgun SMTP password           |

**SMTP URL Format**: `smtps://postmaster@your-domain.mailgun.org:password@smtp.mailgun.org:587`

#### Domain Authentication Setup

**SPF Record**:

```
v=spf1 include:mailgun.org -all
```

**DKIM Setup**:

1. In Mailgun dashboard, go to Sending > Domains
2. Add your domain and verify ownership
3. Add the provided TXT records to your DNS

**DMARC Record**:

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

#### Mailgun Specific Notes

* **Domain Verification**: Verify domain ownership before sending
* **EU Region**: Use `smtp.eu.mailgun.org` for EU region
* **Webhook Integration**: Set up webhooks for delivery tracking

### Amazon SES

**Recommended for**: AWS-integrated applications and cost-effective high-volume sending

#### SMTP Settings

| Setting        | Value                                                 |
| -------------- | ----------------------------------------------------- |
| SMTP server    | `email-smtp.us-east-1.amazonaws.com` (or your region) |
| SMTP port      | `587` (STARTTLS) or `465` (SSL)                       |
| Encryption     | STARTTLS or SSL                                       |
| Authentication | SMTP Username + SMTP Password                         |
| Username       | Your SES SMTP Username                                |
| Password       | Your SES SMTP Password                                |

**SMTP URL Format**: `smtps://smtp_username:smtp_password@email-smtp.us-east-1.amazonaws.com:587`

#### Domain Authentication Setup

**SPF Record**:

```
v=spf1 include:amazonses.com -all
```

**DKIM Setup**:

1. In AWS SES console, go to Configuration > Verified identities
2. Select your domain and enable DKIM
3. Add the provided CNAME records to your DNS

**DMARC Record**:

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

#### Amazon SES Specific Notes

* **Sandbox Mode**: New accounts start in sandbox mode with sending restrictions
* **Region Selection**: Choose the region closest to your users
* **Reputation Monitoring**: Monitor bounce and complaint rates in SES console

### HubSpot

**Recommended for**: Marketing automation and CRM integration

#### SMTP Settings

| Setting        | Value                 |
| -------------- | --------------------- |
| SMTP server    | `smtp.hubspot.com`    |
| SMTP port      | `587` (STARTTLS)      |
| Encryption     | STARTTLS              |
| Authentication | Username + Password   |
| Username       | Your HubSpot email    |
| Password       | Your HubSpot password |

**SMTP URL Format**: `smtps://your_email:password@smtp.hubspot.com:587`

#### Domain Authentication Setup

**SPF Record**:

```
v=spf1 include:_spf.hubspot.com -all
```

**DKIM Setup**:

1. In HubSpot, go to Settings > Website > Domains & URLs
2. Connect your domain
3. Add the provided CNAME records to your DNS

**DMARC Record**:

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

#### HubSpot Specific Notes

* **Connected Domain**: Domain must be connected in HubSpot settings
* **Marketing Hub**: Some features require Marketing Hub subscription
* **Contact Management**: Integrates with HubSpot CRM for contact tracking

### Generic SMTP Providers

For other SMTP providers not listed above, follow this general configuration pattern:

#### SMTP Settings Template

| Setting        | Value                           |
| -------------- | ------------------------------- |
| SMTP server    | `smtp.yourprovider.com`         |
| SMTP port      | `587` (STARTTLS) or `465` (SSL) |
| Encryption     | STARTTLS (preferred) or SSL     |
| Authentication | Username + Password or API Key  |
| Username       | Your email or username          |
| Password       | Your password or API key        |

#### Domain Authentication Template

**SPF Record**: Contact your provider for their SPF include directive **DKIM Setup**: Enable in provider settings and add required DNS records **DMARC Record**: Use the standard DMARC format shown above

## Troubleshooting & Monitoring

### Common Issues

**Authentication Failures**:

* Verify username and password are correct
* Check if two-factor authentication requires app passwords
* Ensure SMTP AUTH is enabled for the account

**Connection Issues**:

* Verify SMTP server address and port
* Check firewall settings allow outbound connections
* Test with telnet: `telnet smtp.provider.com 587`

**Delivery Issues**:

* Check SPF, DKIM, and DMARC records are properly configured
* Monitor bounce rates and spam complaints
* Verify sender reputation with tools like mail-tester.com

### Monitoring Tools

**Email Testing**:

* [mail-tester.com](https://www.mail-tester.com/): Test spam score
* [MXToolbox](https://mxtoolbox.com/): DNS and deliverability testing
* [DMARC Analyzer](https://www.dmarcanalyzer.com/): DMARC report analysis

**Provider-Specific Monitoring**:

* **Office 365**: Message Trace in admin center
* **SendGrid**: Email Activity dashboard
* **Mailgun**: Logs and analytics in dashboard
* **Amazon SES**: Sending statistics in AWS console

### Best Practices for Monitoring

* Set up DMARC reporting to monitor authentication failures
* Regularly check bounce and complaint rates
* Monitor sender reputation scores
* Test email delivery to major providers (Gmail, Outlook, Yahoo)
* Set up alerts for delivery issues

## Summary Checklist

Before going live with your email configuration:

### Technical Setup

* [ ] SMTP credentials configured in Buzzy
* [ ] SPF record includes your provider's directive
* [ ] DKIM enabled and DNS records added
* [ ] DMARC record added (start with `p=none` for testing)
* [ ] Test email delivery to major providers

### Monitoring Setup

* [ ] DMARC reporting configured
* [ ] Provider-specific monitoring enabled
* [ ] Bounce and complaint tracking set up
* [ ] Regular deliverability testing scheduled

### Content and Compliance

* [ ] Professional "From" address configured
* [ ] Unsubscribe mechanism implemented
* [ ] Email templates tested for spam triggers
* [ ] Sending volume gradually ramped up

### Documentation

* [ ] SMTP settings documented for your team
* [ ] DNS records backed up
* [ ] Provider account credentials securely stored
* [ ] Monitoring procedures documented

## Additional Resources

### Official Documentation Links

* [Microsoft: DKIM in Microsoft 365](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/use-dkim-to-validate-outbound-email?view=o365-worldwide)
* [Microsoft: SPF in Microsoft 365](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/set-up-spf-in-office-365-to-help-prevent-spoofing?view=o365-worldwide)
* [Microsoft: DMARC in Microsoft 365](https://learn.microsoft.com/en-us/microsoft-365/security/office-365-security/use-dmarc-to-validate-email?view=o365-worldwide)
* [SendGrid: Domain Authentication](https://docs.sendgrid.com/ui/account-and-settings/how-to-set-up-domain-authentication)
* [Mailgun: Domain Verification](https://documentation.mailgun.com/en/latest/user_manual.html#verifying-your-domain)
* [Amazon SES: Authenticating Email](https://docs.aws.amazon.com/ses/latest/dg/send-email-authentication.html)

### Email Deliverability Resources

* [Return Path Email Deliverability Guide](https://returnpath.com/)
* [DMARC.org](https://dmarc.org/) - Official DMARC specification
* [Email on Acid](https://www.emailonacid.com/) - Email testing platform
* [Litmus](https://www.litmus.com/) - Email testing and analytics

***

{% hint style="info" %}
Email deliverability is an ongoing process. Start with basic authentication (SPF, DKIM, DMARC) and gradually implement advanced monitoring and optimization based on your sending volume and requirements.
{% endhint %}


---

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

```
GET https://docs.buzzy.buzz/working-with-buzzy/buzzy-deployment-and-app-stores/email-deliverability-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.