---
title: "Email Overview | DreamFactory Docs"
source: "https://docs.dreamfactory.com/api-generation-and-connections/api-types/email/email-overview"
canonical_url: "https://docs.dreamfactory.com/api-generation-and-connections/api-types/email/email-overview"
converted_at: "2026-04-05T13:18:52.896Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
DreamFactory provides email services for sending transactional emails through your APIs. Connect SMTP servers or cloud email providers to enable email functionality in your applications without exposing credentials to clients.
---
## Supported Email Services[](#supported-email-services)
ServiceTypeUse CaseDocumentation**SMTP**ProtocolAny SMTP server[SMTP Guide](/api-generation-and-connections/api-types/email/smtp)**Mailgun**APITransactional emailCommercial license**SendGrid**APITransactional emailCommercial license**Amazon SES**APIAWS email serviceCommercial license**Mandrill**APIMailchimp transactionalCommercial license**SparkPost**APIHigh-volume emailCommercial license**Local**FileDevelopment/testingBuilt-in
LicensingSMTP is included in DreamFactory OSS. Cloud email provider connectors (Mailgun, SendGrid, SES, etc.) require a commercial license.
---
## Email Use Cases[](#email-use-cases)
### Transactional Email[](#transactional-email)
Send automated emails triggered by application events:
- **User registration**: Welcome emails, email verification
- **Password reset**: Secure reset links
- **Order confirmations**: E-commerce receipts
- **Notifications**: Alerts, reminders, updates
- **Reports**: Scheduled report delivery
### API-Driven Email[](#api-driven-email)
Send emails directly through the DreamFactory API:
```
curl -X POST "https://example.com/api/v2/email" \ -H "X-DreamFactory-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": [{"email": "[email protected]", "name": "John Doe"}], "subject": "Your Order Confirmation", "body_html": "Thank you for your order!
", "body_text": "Thank you for your order!" }'
```
---
## Choosing an Email Service[](#choosing-an-email-service)
### SMTP vs API Providers[](#smtp-vs-api-providers)
FactorSMTPAPI ProvidersSetup complexityMediumSimpleDeliverabilityDepends on server reputationOptimizedRate limitsServer-dependentPlan-dependentAnalyticsBasic (logs)Detailed (opens, clicks)CostServer hostingPer-email pricingReliabilitySelf-managedProvider SLA
### Provider Comparison[](#provider-comparison)
ProviderBest ForPricing Model**SMTP (self-hosted)**Full control, existing infrastructureServer costs only**Amazon SES**AWS infrastructure, high volume, low cost$0.10/1,000 emails**SendGrid**Developer-friendly, good deliverabilityFree tier + paid plans**Mailgun**Developers, API-first approachPay-as-you-go**SparkPost**Enterprise, high-volume sendersEnterprise pricing
### Recommendations[](#recommendations)
ScenarioRecommended ServiceDevelopment/testingLocal or SMTP (Mailtrap)Small applicationsSendGrid free tierAWS infrastructureAmazon SESHigh deliverability needsMailgun, SendGridEnterprise/high-volumeSparkPost, Amazon SES
---
## Email Service Architecture[](#email-service-architecture)
```
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐│ API Client │────▶│ DreamFactory │────▶│ Email Service ││ (App/Script) │◀────│ (Email API) │ │ (SMTP/API) │└─────────────────┘ └──────────────────┘ └─────────────────┘ │ │ │ HTTP Request Send Email Deliver Email + API Key via configured to inbox service
```
### Key Benefits[](#key-benefits)
1. **Credential protection**: SMTP/API credentials never exposed to clients
2. **Unified interface**: Same API regardless of backend provider
3. **Access control**: Role-based email permissions
4. **Audit logging**: Track all sent emails
5. **Rate limiting**: Prevent email abuse
---
## Common Configuration Options[](#common-configuration-options)
All email services share these configuration fields:
FieldTypeDescription`name`stringService name (used in API URL)`label`stringDisplay name in admin console`description`stringService description`from_name`stringDefault sender name`from_email`stringDefault sender email address`reply_to_name`stringDefault reply-to name`reply_to_email`stringDefault reply-to address
---
## API Endpoints[](#api-endpoints)
MethodEndpointDescription`POST``/api/v2/{service}`Send an email`GET``/api/v2/{service}`Get service configuration (admin only)
---
## Email Request Format[](#email-request-format)
### Basic Email[](#basic-email)
```
{ "to": [ {"email": "[email protected]", "name": "Recipient Name"} ], "subject": "Email Subject", "body_text": "Plain text email body", "body_html": "HTML email body
"}
```
### Full Email Options[](#full-email-options)
```
{ "to": [ {"email": "[email protected]", "name": "Recipient"} ], "cc": [ {"email": "[email protected]", "name": "CC Recipient"} ], "bcc": [ {"email": "[email protected]", "name": "BCC Recipient"} ], "from_name": "Sender Name", "from_email": "[email protected]", "reply_to_name": "Reply Handler", "reply_to_email": "[email protected]", "subject": "Email Subject", "body_text": "Plain text version", "body_html": "HTML version
", "attachments": [ { "name": "document.pdf", "content": "base64_encoded_content", "content_type": "application/pdf" } ]}
```
### Email Fields[](#email-fields)
FieldTypeRequiredDescription`to`arrayYesList of recipient objects`subject`stringYesEmail subject line`body_text`stringNo*Plain text email body`body_html`stringNo*HTML email body`from_name`stringNoOverride default sender name`from_email`stringNoOverride default sender email`cc`arrayNoCarbon copy recipients`bcc`arrayNoBlind carbon copy recipients`reply_to_name`stringNoReply-to name`reply_to_email`stringNoReply-to email`attachments`arrayNoFile attachments
*At least one of `body_text` or `body_html` is required.
---
## Email Templates[](#email-templates)
For consistent branding, use templated emails:
### Simple Variable Replacement[](#simple-variable-replacement)
Use placeholders in your email body:
```
{ "to": [{"email": "[email protected]"}], "subject": "Welcome, {first_name}!", "body_html": "Welcome to {company_name}
Hello {first_name},
", "template_data": { "first_name": "John", "company_name": "Acme Corp" }}
```
### Provider Templates[](#provider-templates)
Some providers (SendGrid, Mailgun) support server-side templates:
```
{ "to": [{"email": "[email protected]"}], "template_id": "welcome-email-v2", "template_data": { "first_name": "John" }}
```
---
## Security Best Practices[](#security-best-practices)
### Sender Authentication[](#sender-authentication)
Configure SPF, DKIM, and DMARC for your sending domain:
1. **SPF**: Authorize sending servers
2. **DKIM**: Sign emails cryptographically
3. **DMARC**: Policy for failed authentication
### Rate Limiting[](#rate-limiting)
Apply rate limits to prevent abuse:
User TypeRecommended LimitRegular users10 emails/hourPower users100 emails/hourService accountsBased on needs
### Role-Based Access[](#role-based-access)
Restrict email sending by role:
1. Navigate to **Roles** in admin console
2. Configure email service access
3. Limit recipients or templates if needed
---
## Common Errors[](#common-errors)
Error CodeMessageCauseSolution400Bad RequestInvalid email formatCheck recipient addresses401UnauthorizedMissing API keyAdd API key header403ForbiddenEmail sending not permittedCheck role permissions422Unprocessable EntityMissing required fieldsInclude to, subject, body500Service ErrorEmail service failureCheck service configuration503Service UnavailableSMTP/API unreachableCheck credentials and connectivity
---
## Development and Testing[](#development-and-testing)
### Local Email Service[](#local-email-service)
The `local` email driver saves emails to files instead of sending:
```
MAIL_DRIVER=local
```
Emails are saved to `storage/logs/` for inspection.
### Email Testing Services[](#email-testing-services)
Use these services to test without sending real emails:
ServiceDescription[Mailtrap](https://mailtrap.io)Fake SMTP server for testing[MailHog](https://github.com/mailhog/MailHog)Self-hosted email testing[Mailcatcher](https://mailcatcher.me)Local SMTP with web UI
---
## Next Steps[](#next-steps)
- **[SMTP](/api-generation-and-connections/api-types/email/smtp)**: Configure SMTP email service
- **[Role-Based Access Control](/api-security/rbac)**: Restrict email permissions
- **[Rate Limiting](/api-security/rate-limiting)**: Prevent email abuse