> ## Documentation Index
> Fetch the complete documentation index at: https://docs.migma.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Migma Email Preview API
> Use the Migma Email Preview API to render HTML on real devices and clients including Gmail, Outlook, Apple Mail, iOS, and Android before sending.
## Overview
The Email Preview API generates screenshots of your email HTML on real devices and email clients. Preview Gmail, Outlook, Apple Mail, mobile apps, and other supported platforms before send.
**Credit Cost:** Each email preview request costs **2 credits**. Make sure you have sufficient credits before generating previews.
## Features
* **Many clients and devices**: Gmail, Outlook, Apple Mail, Yahoo, iOS and Android mail apps, and more
* **Real Device Rendering**: Screenshots from actual devices, not simulators
* **Mobile & Desktop**: Preview on iPhone, Android, iPad, desktop clients
* **Fast Generation**: Results typically ready in 60-90 seconds
* **High-Quality Screenshots**: Full-resolution images of your email renders
## How It Works
1. **Create Preview**: Send your email HTML to the preview endpoint
2. **Processing**: Your email is rendered on real devices (60-90 seconds)
3. **Get Results**: Retrieve high-quality screenshots for each device
## Pricing
Each preview request costs **2 credits**, regardless of how many devices you select. The default is 10 common devices; pass a `devices` array or list IDs from `/v1/emails/devices/supported`.
## Quick Start
### 1. Create a Preview
```typescript Node.js SDK theme={null}
import Migma from 'migma';
const migma = new Migma(process.env.MIGMA_API_KEY);
// createAndWait polls until all device screenshots are ready
const { data } = await migma.previews.createAndWait({
html: 'Test Email
',
subject: 'My Email Preview',
name: 'Homepage Newsletter'
});
for (const device of data.devices) {
console.log(`${device.deviceName}: ${device.screenshotUrl}`);
}
```
```bash cURL theme={null}
curl -X POST https://api.migma.ai/v1/emails/previews \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"html": "Test Email
",
"subject": "My Email Preview",
"name": "Homepage Newsletter"
}'
```
**Response:**
```json theme={null}
{
"success": true,
"data": {
"previewId": "preview_abc123",
"status": "processing",
"creditsCharged": 2
}
}
```
### 2. Check Preview Status
```bash theme={null}
curl -X GET https://api.migma.ai/v1/emails/previews/preview_abc123 \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Response (Processing):**
```json theme={null}
{
"success": true,
"data": {
"previewId": "preview_abc123",
"status": "processing",
"progress": 45
}
}
```
**Response (Complete):**
```json theme={null}
{
"success": true,
"data": {
"previewId": "preview_abc123",
"status": "completed",
"previews": [
{
"device": "gmail-chrome",
"imageUrl": "https://cdn.migma.ai/previews/...",
"platform": "desktop"
},
{
"device": "iphone-14-pro",
"imageUrl": "https://cdn.migma.ai/previews/...",
"platform": "mobile"
}
]
}
}
```
### 3. Get Supported Devices
```bash theme={null}
curl -X GET https://api.migma.ai/v1/emails/devices/supported \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Request Parameters
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `html` | string | Yes | Email HTML content to preview |
| `subject` | string | No | Email subject line (default: "Email Preview") |
| `devices` | array | No | Specific devices to render on (defaults to 10 common devices) |
| `name` | string | No | Custom name for the preview |
## Default Devices
When you don't specify devices, previews are generated on these 10 platforms:
* Gmail (Chrome Desktop)
* Gmail (Android App)
* Outlook 2016 (Windows)
* Outlook.com (Browser)
* Apple Mail (macOS)
* Apple Mail (iPhone 14)
* Yahoo Mail (Browser)
* Samsung Email (Android)
* Outlook iOS App
* Gmail iOS App
## Custom Device Selection
You can specify exactly which devices to use:
```bash theme={null}
curl -X POST https://api.migma.ai/v1/emails/previews \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"html": "...",
"devices": [
"gmail-chrome",
"outlook-2016",
"iphone-14-pro",
"gmail-android"
]
}'
```
List every supported device ID with `GET /v1/emails/devices/supported`.
## Response Statuses
| Status | Description |
| ------------ | -------------------------- |
| `processing` | Preview is being generated |
| `completed` | All screenshots are ready |
| `failed` | Preview generation failed |
## Common Use Cases
### Quality Assurance
Test emails before sending campaigns to ensure they render correctly across all platforms.
### Client Approval
Generate previews to show clients how emails will look on different devices.
### Responsive Testing
Verify that your email design is mobile-friendly and responsive.
### Cross-Platform Compatibility
Identify rendering issues specific to certain email clients.
## Best Practices
Ensure your email HTML is valid and uses email-safe CSS. Avoid modern CSS features that may not be supported in all email clients.
Focus on the email clients your audience actually uses. Check your email analytics to see which platforms are most common.
Each preview costs 2 credits. Plan your testing workflow to minimize unnecessary preview generations.
Store preview images for reference. You can reuse them for client presentations without regenerating.
## Error Handling
### Insufficient Credits
```json theme={null}
{
"success": false,
"error": "Insufficient credits. This operation requires 2 credits.",
"code": "INSUFFICIENT_CREDITS"
}
```
Check your credit balance before generating previews. You can view your balance in your account dashboard or via the API.
### Invalid HTML
```json theme={null}
{
"success": false,
"error": "Invalid HTML content provided",
"code": "INVALID_HTML"
}
```
## Limitations
* **Processing Time**: Previews typically take 60-90 seconds to generate
* **HTML Size**: Maximum HTML size is 500KB
* **Rate Limits**: Subject to your plan's rate limits
* **Image Assets**: External images must be publicly accessible
## Need Help?
View complete API documentation
Learn about API keys
Get notified when API events occur
Get help from our community