Migma Email 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.

Base URL

All API requests should be made to:

https://api.migma.ai

Authentication

All API endpoints require a bearer token. Get one with migma login, hosted MCP OAuth, or agent registration. CI sets MIGMA_API_KEY. Include it 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"
}

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 request allowances follow your account’s plan. All API keys belonging to the same account share each route group’s budget, including keys used by separate applications or agents. Creating another key does not increase that allowance.

Limit	What it counts	How it is set
General API requests	Requests within each general route group	Your plan’s API requests per minute, with any account override
Sending API requests	All requests under `/v1/sending`, including batch status and retry	At least 60 × your account’s recipients/second limit, or a higher configured plan allowance; an explicit account override takes priority
Sending throughput	Recipients dispatched per second across campaigns and direct sends	Your account and sending-domain limits, plus available provider capacity
Sending volume	Recipients sent per day or month	Your plan’s email allowance and applicable domain limits

For example, an account capped at 5 recipients/second receives at least 300 sending API requests/minute without an account-specific API override. An account capped at 300 recipients/second receives at least 18,000 requests/minute. These examples describe request allowances, not guaranteed processing speed. A configured zero allowance disables the corresponding API budget; it does not mean unlimited. Find your effective allowances in Settings → Developers → API Keys → API limits. Annual plans use their configured plan limits. Account-specific agreements can change the displayed allowance. Request budgets use a 60-second window starting with its first request. Pace requests throughout the minute: using the entire request budget at once does not bypass recipient/second limits. This limiter has no separate daily request quota or extra burst allowance. Email daily/monthly quotas still apply. Email reading, editing, and test previews under /v1/emails use the general plan allowance in a separate group, so they do not consume the /v1/sending budget. Campaign endpoints have their own general-plan group. Expensive operations such as imports can have a lower endpoint-specific cap. Requests that reach a limiter count even if later validation fails or an idempotent response is replayed. Responses that reach the request limiter include these headers. Values below are illustrative:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 295
X-RateLimit-Reset: 1609459200

X-RateLimit-Reset is a Unix timestamp in seconds. When the request budget is exhausted, the API returns HTTP 429 and Retry-After, expressed in seconds:

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later."
}

If the shared request limiter or account-limit lookup is unavailable, the API returns HTTP 503 with Retry-After: 1 before running the endpoint. Actual sending capacity is checked separately. A direct send can return 429 with code: "SENDING_CAPACITY" and data.retryAfterMs even when request budget remains. Campaign recipients wait for available capacity in the sending queue. One audience-send request can create many deliveries; every recipient still counts against throughput and volume limits.

On a request-limit response, wait for Retry-After. On a sending-capacity response, wait for data.retryAfterMs. Retry the same send with the same API key, body, and Idempotency-Key; use bounded retries with backoff and jitter.

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

POST endpoints accept an optional Idempotency-Key request header so you can safely retry a request after a network error or timeout without doing the work twice. It is opt-in: a request without the header is processed normally.

Idempotency-Key: campaign-send-camp_123

The header is a string up to 100 characters. Keys are scoped per API key, so the same key used by two different keys never collides.

Replay behavior

Within a 24 hour window, the first request with a given key runs normally and its response is cached. After that:

Same key and same body returns the original cached response, with the same status and body. The replay carries the response header Idempotent-Replayed: true, so you can tell a replay from a fresh execution.
Same key but a different body returns 409 with error code IDEMPOTENCY_CONFLICT. Mint a fresh key whenever the request genuinely changes.
A key longer than 100 characters is rejected with 400 and code IDEMPOTENCY_KEY_INVALID.

429 (rate limited) and 5xx (server) responses are not cached, so a retry with the same key runs again. This is what makes a retry after a transient failure safe.

A request still running with the same key returns 503 with code IDEMPOTENCY_IN_PROGRESS and a Retry-After header. Retry after that delay; you get the first request’s response.
Sending an email (POST /v1/sending to one recipient) is identified by the key itself, so even a retry after a 5xx never sends a second copy: it returns the original send’s outcome.

Recommended keys

Use a deterministic key derived from the logical operation, so the same retry always produces the same key:

Operation	Recommended key
Send email	`send-<emailId>-<recipientId or to>-<scheduledAt or "now">`
Send campaign	`campaign-send-<campaignId>`
Generate email	`email-gen-<projectId>-<turn or prompt hash>`
Add contact	`contact-<email>`

Anti-patterns

Never use a random value such as uuid() or a per-attempt timestamp like Date.now(). A new value on each attempt defeats deduplication across retries and process restarts, which is exactly the case the key exists for.
Don’t hash the request body and use that as the key. The body is already part of the conflict check, and a body hash makes every distinct payload its own key rather than identifying one logical operation.

The header is honored on the endpoints where a duplicate call is costly: sending an email (POST /v1/sending), sending or scheduling a campaign (POST /v1/campaigns/{id}/send and POST /v1/campaigns/{id}/schedule), and the contact write endpoints (POST /v1/contacts, POST /v1/contacts/bulk, and POST /v1/contacts/bulk-delete).

Brand / project scoping

An API key is scoped to your account, not to a single brand. Most resources (contacts, campaigns, segments, emails) live inside a project, so pass projectId on the requests that operate on them. Call GET /v1/projects first to discover the project IDs available to your key. A resource that belongs to a different project than the one you reference returns 404, the same as a resource that does not exist. The API does not reveal that a resource exists in a project you did not name.

Events & Webhooks

Use webhooks to receive supported Migma API and contact events in your own app, queue, or automation tool:

Events & Webhooks

Learn how to set up event 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

Project editing

Edit project content including knowledge base, images, and logos:

GET /v1/projects/{projectId}/knowledge-base - List knowledge base entries
POST /v1/projects/{projectId}/knowledge-base - Add knowledge base entry
PUT /v1/projects/{projectId}/knowledge-base/{entryId} - Update entry
DELETE /v1/projects/{projectId}/knowledge-base/{entryId} - Remove entry
POST /v1/projects/{projectId}/images - Add image (URL-only)
PUT /v1/projects/{projectId}/images - Update image metadata
DELETE /v1/projects/{projectId}/images - Remove image
PUT /v1/projects/{projectId}/logos - Update logos

Project editing endpoints require the project:write permission.

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 result.emails[] with emailId, HTML, screenshots, and series order
GET /v1/emails/{emailId} - Fetch one generated email by ID
POST /v1/emails/{emailId}/edit - Prompt Migma to edit one generated email

Email validation

Comprehensive email testing and quality analysis:

POST /v1/emails/validate/compatibility - Compatibility report for major webmail, desktop, and mobile 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 supported preview device IDs (web, desktop, mobile)

Email preview API

See the auto-generated preview endpoint docs in the API reference

Contacts

Manage your contacts via API:

GET /v1/contacts - List contacts
POST /v1/contacts - Add a contact
POST /v1/contacts/bulk - Bulk import contacts
POST /v1/contacts/bulk-delete - Batch delete contacts by email
POST /v1/contacts/status - Change contact status

Campaigns

Create and manage named marketing campaigns with lifecycle tracking:

GET /v1/campaigns - List campaigns
POST /v1/campaigns - Create a campaign from a generated email
GET /v1/campaigns/{id} - Get campaign details
POST /v1/campaigns/{id}/send - Send immediately
POST /v1/campaigns/{id}/schedule - Schedule for future delivery
POST /v1/campaigns/{id}/cancel - Cancel a scheduled campaign
POST /v1/campaigns/{id}/archive - Archive a campaign
POST /v1/campaigns/{id}/unarchive - Restore an archived campaign
GET /v1/campaigns/{id}/stats - Engagement stats
GET /v1/campaigns/{id}/logs - Per-recipient delivery logs

Exports

Export generated emails to files or platforms:

GET /v1/export/html/{conversationId} - Export as production HTML
GET /v1/export/png/{conversationId} - Export as PNG
GET /v1/export/pdf/{conversationId} - Export as PDF
GET /v1/export/klaviyo/{conversationId} - Export for Klaviyo
GET /v1/export/mailchimp/{conversationId} - Export for Mailchimp
POST /v1/export/hubspot - Export for HubSpot
GET /v1/export/status/{conversationId} - Poll export status

Error handling

Failed requests return the matching HTTP status code with this body:

{
  "success": false,
  "error": "Insufficient permissions"
}

The response does not include a separate machine-readable code field. Branch on the HTTP status code for programmatic handling, and treat error as a human-readable message for logging and display. For example, a missing scope returns HTTP 403 with error: "Insufficient permissions".

Environments

Use different API keys for different environments:

Production

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

Development/Testing

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

Separate keys help organize integrations. Keys belonging to the same account share its request budgets; a different key does not provide a separate quota.

SDKs & libraries

Node.js / TypeScript (available now)

npm install migma

yarn add migma

pnpm add migma

import Migma from 'migma';

const migma = new Migma(process.env.MIGMA_API_KEY);

const email = await migma.emails.generateAndWait({
  projectId: 'proj_123',
  prompt: 'Create a welcome email for new subscribers',
  languages: ['en']
});

const selectedEmail = email.data.result.emails[0];
console.log(selectedEmail.emailId);
console.log(selectedEmail.html);

SDK Documentation

Full SDK guide — configuration, error handling, polling helpers, and all 14 resources

CLI (available now)

npm install -g @migma/cli

yarn global add @migma/cli

migma login
migma generate "Create a welcome email" --wait
migma validate all --conversation conv_123
migma send --to user@example.com --email email_123

CLI Documentation

Full CLI guide — all commands, workflows, and configuration

Need help?

Quickstart

Get started in under 5 minutes

Events & Webhooks

Set up event notifications

Authentication

Learn about API keys and security

Join Discord

Connect with developers and get support

​Overview

​Base URL

​Authentication

Authentication Guide

​API structure

​Request format

​Response format

​Success response

​Error response

​HTTP status codes

​Rate limiting

​Pagination

​Idempotency

​Replay behavior

​Recommended keys

​Anti-patterns

​Brand / project scoping

​Events & Webhooks

Events & Webhooks

​API endpoints

​Projects

​Project editing

​Email generation

​Email validation

Email validation API

​Email previews

Email preview API

​Contacts

​Campaigns

​Exports

​Error handling

​Environments

​Production

​Development/Testing

​SDKs & libraries

​Node.js / TypeScript (available now)

SDK Documentation

​CLI (available now)

CLI Documentation

​Need help?

Quickstart

Events & 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

Replay behavior

Recommended keys

Anti-patterns

Brand / project scoping

Events & Webhooks

API endpoints

Projects

Project editing

Email generation

Email validation

Email previews

Contacts

Campaigns

Exports

Error handling

Environments

Production

Development/Testing

SDKs & libraries

Node.js / TypeScript (available now)

CLI (available now)

Need help?