---
title: "Email Overview - DreamFactory Documentation"
source: "https://wiki.dreamfactory.com/Email_Overview"
canonical_url: "https://wiki.dreamfactory.com/Email_Overview"
converted_at: "2026-04-05T06:12:35.268Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
[]()
# Email Overview
From DreamFactory Wiki
[Jump to navigation](#mw-head)
[Jump to search](#searchInput)
## Contents
- [1 Email Services Overview](#Email_Services_Overview)
- [1.1 Supported Email Services](#Supported_Email_Services)
- [1.2 Email Use Cases](#Email_Use_Cases)
- [1.2.1 Transactional Email](#Transactional_Email)
- [1.2.2 API-Driven Email](#API-Driven_Email)
- [1.3 Choosing an Email Service](#Choosing_an_Email_Service)
- [1.3.1 SMTP vs API Providers](#SMTP_vs_API_Providers)
- [1.3.2 Provider Comparison](#Provider_Comparison)
- [1.3.3 Recommendations](#Recommendations)
- [1.4 Email Service Architecture](#Email_Service_Architecture)
- [1.4.1 Key Benefits](#Key_Benefits)
- [1.5 Common Configuration Options](#Common_Configuration_Options)
- [1.6 API Endpoints](#API_Endpoints)
- [1.7 Email Request Format](#Email_Request_Format)
- [1.7.1 Basic Email](#Basic_Email)
- [1.7.2 Full Email Options](#Full_Email_Options)
- [1.7.3 Email Fields](#Email_Fields)
- [1.8 Email Templates](#Email_Templates)
- [1.8.1 Simple Variable Replacement](#Simple_Variable_Replacement)
- [1.8.2 Provider Templates](#Provider_Templates)
- [1.9 Security Best Practices](#Security_Best_Practices)
- [1.9.1 Sender Authentication](#Sender_Authentication)
- [1.9.2 Rate Limiting](#Rate_Limiting)
- [1.9.3 Role-Based Access](#Role-Based_Access)
- [1.10 Common Errors](#Common_Errors)
- [1.11 Development and Testing](#Development_and_Testing)
- [1.11.1 Local Email Service](#Local_Email_Service)
- [1.11.2 Email Testing Services](#Email_Testing_Services)
- [1.12 Next Steps](#Next_Steps)
# Email Services Overview
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
Service
Type
Use Case
Documentation
**SMTP**
Protocol
Any SMTP server
[SMTP](/index.php?title=SMTP&action=edit&redlink=1)
**Mailgun**
API
Transactional email
Commercial license
**SendGrid**
API
Transactional email
Commercial license
**Amazon SES**
API
AWS email service
Commercial license
**Mandrill**
API
Mailchimp transactional
Commercial license
**SparkPost**
API
High-volume email
Commercial license
**Local**
File
Development/testing
Built-in
**ℹ️ Note:** SMTP is included in DreamFactory OSS. Cloud email provider connectors (Mailgun, SendGrid, SES, etc.) require a commercial license.
---
## Email Use Cases
### 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
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
### SMTP vs API Providers
Factor
SMTP
API Providers
Setup complexity
Medium
Simple
Deliverability
Depends on server reputation
Optimized
Rate limits
Server-dependent
Plan-dependent
Analytics
Basic (logs)
Detailed (opens, clicks)
Cost
Server hosting
Per-email pricing
Reliability
Self-managed
Provider SLA
### Provider Comparison
Provider
Best For
Pricing Model
**SMTP (self-hosted)**
Full control, existing infrastructure
Server costs only
**Amazon SES**
AWS infrastructure, high volume, low cost
$0.10/1,000 emails
**SendGrid**
Developer-friendly, good deliverability
Free tier + paid plans
**Mailgun**
Developers, API-first approach
Pay-as-you-go
**SparkPost**
Enterprise, high-volume senders
Enterprise pricing
### Recommendations
Scenario
Recommended Service
Development/testing
Local or SMTP (Mailtrap)
Small applications
SendGrid free tier
AWS infrastructure
Amazon SES
High deliverability needs
Mailgun, SendGrid
Enterprise/high-volume
SparkPost, Amazon SES
---
## 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
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
All email services share these configuration fields:
Field
Type
Description
`name`
string
Service name (used in API URL)
`label`
string
Display name in admin console
`description`
string
Service description
`from_name`
string
Default sender name
`from_email`
string
Default sender email address
`reply_to_name`
string
Default reply-to name
`reply_to_email`
string
Default reply-to address
---
## API Endpoints
Method
Endpoint
Description
`POST`
`/api/v2/{service}`
Send an email
`GET`
`/api/v2/{service}`
Get service configuration (admin only)
---
## Email Request Format
### 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
```
{
"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
Field
Type
Required
Description
`to`
array
Yes
List of recipient objects
`subject`
string
Yes
Email subject line
`body_text`
string
No*
Plain text email body
`body_html`
string
No*
HTML email body
`from_name`
string
No
Override default sender name
`from_email`
string
No
Override default sender email
`cc`
array
No
Carbon copy recipients
`bcc`
array
No
Blind carbon copy recipients
`reply_to_name`
string
No
Reply-to name
`reply_to_email`
string
No
Reply-to email
`attachments`
array
No
File attachments
- At least one of `body_text` or `body_html` is required.
---
## Email Templates
For consistent branding, use templated emails:
### 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
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
### 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
Apply rate limits to prevent abuse:
User Type
Recommended Limit
Regular users
10 emails/hour
Power users
100 emails/hour
Service accounts
Based on needs
### 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
Error Code
Message
Cause
Solution
400
Bad Request
Invalid email format
Check recipient addresses
401
Unauthorized
Missing API key
Add API key header
403
Forbidden
Email sending not permitted
Check role permissions
422
Unprocessable Entity
Missing required fields
Include to, subject, body
500
Service Error
Email service failure
Check service configuration
503
Service Unavailable
SMTP/API unreachable
Check credentials and connectivity
---
## Development and Testing
### 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
Use these services to test without sending real emails:
Service
Description
[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
- **[SMTP](/index.php?title=SMTP&action=edit&redlink=1)**: Configure SMTP email service
- **[Role-Based Access Control](/Security/Role_Based_Access)**: Restrict email permissions
- **[Rate Limiting](/Security/Rate_Limiting)**: Prevent email abuse
Retrieved from "[https://wiki.dreamfactory.com/index.php?title=Email_Overview&oldid=839](https://wiki.dreamfactory.com/index.php?title=Email_Overview&oldid=839)"
[Category](/Special:Categories): - [API](/Category:API)