API Reference

Overview

The Migma.ai API provides programmatic access to our AI Email Engine that creates pixel-perfect, on-brand emails in 30 seconds. Build custom integrations, automate email creation workflows, track customer events, export to platforms like Mailchimp and HubSpot, and manage your entire email marketing infrastructure programmatically. Generate emails 200x faster and 95% cheaper with AI that learns your brand voice, fetches live content, and creates cross-client compatible HTML/React code.

Base URL

All API requests should be made to:

https://api.migma.ai

Authentication

All API endpoints require authentication using API keys. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Authentication Guide

Learn how to create and manage API keys

API Structure

The Migma.ai API is organized around REST principles:

Predictable resource-oriented URLs
Standard HTTP response codes
JSON request and response bodies
Bearer token authentication

Request Format

All POST, PATCH, and PUT requests should use JSON format:

Content-Type: application/json

Example request:

curl -X POST https://api.migma.ai/v1/projects/import \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://yourbrand.com"], "name": "My Brand"}'

Response Format

All API responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "metadata": {
    "timestamp": "2024-09-30T12:34:56.789Z",
    "requestId": "req_1234567890"
  }
}

Error Response

{
  "success": false,
  "error": "Error message describing what went wrong",
  "code": "ERROR_CODE",
  "metadata": {
    "timestamp": "2024-09-30T12:34:56.789Z",
    "requestId": "req_1234567890"
  }
}

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Meaning	Description
`200`	OK	Request succeeded
`201`	Created	Resource was created successfully
`400`	Bad Request	Invalid request parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key lacks required permissions
`404`	Not Found	Resource doesn’t exist
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Something went wrong on our end
`503`	Service Unavailable	Service temporarily unavailable

Rate Limiting

API requests are rate limited based on your plan:

Plan	Rate Limit
Free	10 requests/minute
Pro	100 requests/minute
Enterprise	Custom limits

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

When rate limited (429 response), wait for the time specified in X-RateLimit-Reset before retrying.

Pagination

List endpoints support pagination using limit and offset parameters:

GET /v1/projects?limit=20&offset=0

Response includes pagination metadata:

{
  "success": true,
  "data": {
    "projects": [...],
    "total": 45,
    "limit": 20,
    "offset": 0
  }
}

Idempotency

Some endpoints support idempotency to safely retry requests without duplicating operations. Include an Idempotency-Key header:

Idempotency-Key: unique-key-12345

Requests with the same idempotency key return the same response for 24 hours.

Webhooks

Instead of polling for status updates, use webhooks to receive real-time notifications:

Webhooks Guide

Learn how to set up webhooks for real-time notifications

API Endpoints

Projects

Manage brand projects and imports:

GET /v1/projects - List all projects
GET /v1/projects/{projectId} - Get project details
POST /v1/projects/import - Import a new brand

Email Generation

Generate AI-powered, on-brand emails with async processing:

POST /v1/projects/emails/generate - Generate an email (async)
GET /v1/projects/emails/{conversationId}/status - Check generation status and get HTML/React code

Email Validation

Comprehensive email testing and quality analysis:

POST /v1/emails/validate/compatibility - Test across 40+ email clients
POST /v1/emails/validate/links - Check all links for validity
POST /v1/emails/validate/spelling - AI-powered spell/grammar check
POST /v1/emails/validate/deliverability - Predict inbox placement
POST /v1/emails/validate/all - Run all validation checks

Email Validation API

Learn about email compatibility testing, link analysis, and deliverability prediction

Email Previews

Generate screenshots on real devices and email clients:

POST /v1/emails/previews - Create device previews
GET /v1/emails/previews/{previewId} - Get preview status & results
GET /v1/emails/devices/supported - List available devices (40+)

Email Preview API

Learn how to generate email previews across Gmail, Outlook, iPhone, and more

Subscribers

Manage your email audience via API:

GET /v1/subscribers - List subscribers
POST /v1/subscribers - Add a subscriber
POST /v1/subscribers/bulk - Bulk import subscribers
POST /v1/subscribers/unsubscribe - Unsubscribe a subscriber

Exports

Export emails to various platforms with one-click integrations:

POST /v1/export - Export to Mailchimp, HubSpot, Klaviyo, and more
GET /v1/export/{exportId} - Get export status

Browse Full API Reference

Explore auto-generated documentation for all endpoints

Error Codes

Common error codes and their meanings:

Code	Description
`INVALID_API_KEY`	API key is invalid or revoked
`INSUFFICIENT_PERMISSIONS`	API key lacks required permissions
`INVALID_REQUEST`	Request parameters are invalid
`RESOURCE_NOT_FOUND`	Requested resource doesn’t exist
`RATE_LIMIT_EXCEEDED`	Too many requests in time window
`GENERATION_FAILED`	Email generation encountered an error
`IMPORT_FAILED`	Brand import encountered an error

Environments

Use different API keys for different environments:

Production

Base URL: https://api.migma.ai
API Key: mgma_sk_live_...

Development/Testing

Base URL: https://api.migma.ai
API Key: mgma_sk_test_...

Test keys are separate from production keys and don’t affect your production data or rate limits.

SDKs & Libraries

Official SDKs coming soon for:

Node.js / TypeScript
Python
Ruby
PHP

In the meantime, use standard HTTP libraries to make requests.

Need Help?

Quickstart

Get started in under 5 minutes

Webhooks

Set up real-time notifications

Authentication

Learn about API keys and security

Join Discord

Connect with developers and get support

Getting Started

Integration Guides

API Endpoints

Overview

Base URL

Authentication

Authentication Guide

API Structure

Request Format

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

Idempotency

Webhooks

Webhooks Guide

API Endpoints

Projects

Email Generation

Email Validation

Email Validation API

Email Previews

Email Preview API

Subscribers

Exports

Browse Full API Reference

Error Codes

Environments

Production

Development/Testing

SDKs & Libraries

Need Help?

Quickstart

Webhooks

Authentication

Join Discord

Getting Started

Integration Guides

API Endpoints

​Overview

​Base URL

​Authentication

Authentication Guide

​API Structure

​Request Format

​Response Format

​Success Response

​Error Response

​HTTP Status Codes

​Rate Limiting

​Pagination

​Idempotency

​Webhooks

Webhooks Guide

​API Endpoints

​Projects

​Email Generation

​Email Validation

Email Validation API

​Email Previews

Email Preview API

​Subscribers

​Exports

Browse Full API Reference

​Error Codes

​Environments

​Production

​Development/Testing

​SDKs & Libraries

​Need Help?

Quickstart

Webhooks

Authentication

Join Discord

Overview

Base URL

Authentication

API Structure

Request Format

Response Format

Success Response

Error Response

HTTP Status Codes

Rate Limiting

Pagination

Idempotency

Webhooks

API Endpoints

Projects

Email Generation

Email Validation

Email Previews

Subscribers

Exports

Error Codes

Environments

Production

Development/Testing

SDKs & Libraries

Need Help?