import Migma from 'migma';
const migma = new Migma('YOUR_API_KEY');
const started = await migma.emails.startEdit('EMAIL_ID', {
prompt: 'Use a shorter headline',
label: 'Short headline'
}, { idempotencyKey: 'weekly-short-headline-v1' });
if (started.error) throw started.error;
const polled = await migma.emails.getEditStatus('EMAIL_ID', started.data.editId);
if (polled.error) throw polled.error;
console.log(polled.data.status);
// Continue polling the same editId while pending or processing.curl -X POST 'https://api.migma.ai/v1/emails/EMAIL_ID/edit' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: weekly-short-headline-v1' \
-d '{"prompt":"Use a shorter headline","label":"Short headline","async":true}'
import requests
url = "https://api.migma.ai/v1/emails/{emailId}/edit"
payload = {
"prompt": "<string>",
"label": "<string>",
"async": False
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.migma.ai/v1/emails/{emailId}/edit",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => '<string>',
'label' => '<string>',
'async' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.migma.ai/v1/emails/{emailId}/edit"
payload := strings.NewReader("{\n \"prompt\": \"<string>\",\n \"label\": \"<string>\",\n \"async\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.migma.ai/v1/emails/{emailId}/edit")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"<string>\",\n \"label\": \"<string>\",\n \"async\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.migma.ai/v1/emails/{emailId}/edit")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"<string>\",\n \"label\": \"<string>\",\n \"async\": false\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "<string>",
"emailId": "<string>",
"conversationId": "<string>",
"messageId": "<string>",
"slotIdx": 123,
"slotUuid": "<string>",
"status": "<string>",
"subject": "<string>",
"preheader": "<string>",
"html": "<string>",
"thumbnailUrl": "<string>",
"warnings": [
"<string>"
],
"updatedAt": "2023-11-07T05:31:56Z",
"screenshotUrl": "<string>"
},
"error": "<string>"
}{
"success": true,
"data": {
"editId": "<string>",
"emailId": "<string>",
"conversationId": "<string>",
"status": "pending",
"stage": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"pollAfterMs": 123,
"error": "<string>",
"changesMayHaveBeenSaved": true,
"result": {
"id": "<string>",
"emailId": "<string>",
"conversationId": "<string>",
"messageId": "<string>",
"slotIdx": 123,
"slotUuid": "<string>",
"status": "<string>",
"subject": "<string>",
"preheader": "<string>",
"html": "<string>",
"thumbnailUrl": "<string>",
"warnings": [
"<string>"
],
"updatedAt": "2023-11-07T05:31:56Z",
"screenshotUrl": "<string>"
}
},
"error": "<string>"
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}Edit Email With Prompt
Prompt Migma to edit one generated email as a canvas follow-up turn (same orchestrator path as design chat). Omit async or set it to false to wait for the edited Email response; this existing synchronous write is not idempotent and the SDK does not automatically retry it. Set async to true to durably enqueue the edit with no AI work on the request path and receive an EmailEditOperation. Async edits require email:write and email:read; credits are checked when the worker starts. Poll the edit-specific status endpoint and do not use conversation generation status, because a previous conversation turn may already be completed. Total work varies with section and image complexity, provider behavior, and retries; no fixed maximum latency is established.
import Migma from 'migma';
const migma = new Migma('YOUR_API_KEY');
const started = await migma.emails.startEdit('EMAIL_ID', {
prompt: 'Use a shorter headline',
label: 'Short headline'
}, { idempotencyKey: 'weekly-short-headline-v1' });
if (started.error) throw started.error;
const polled = await migma.emails.getEditStatus('EMAIL_ID', started.data.editId);
if (polled.error) throw polled.error;
console.log(polled.data.status);
// Continue polling the same editId while pending or processing.curl -X POST 'https://api.migma.ai/v1/emails/EMAIL_ID/edit' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: weekly-short-headline-v1' \
-d '{"prompt":"Use a shorter headline","label":"Short headline","async":true}'
import requests
url = "https://api.migma.ai/v1/emails/{emailId}/edit"
payload = {
"prompt": "<string>",
"label": "<string>",
"async": False
}
headers = {
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.migma.ai/v1/emails/{emailId}/edit",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'prompt' => '<string>',
'label' => '<string>',
'async' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.migma.ai/v1/emails/{emailId}/edit"
payload := strings.NewReader("{\n \"prompt\": \"<string>\",\n \"label\": \"<string>\",\n \"async\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.migma.ai/v1/emails/{emailId}/edit")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"prompt\": \"<string>\",\n \"label\": \"<string>\",\n \"async\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.migma.ai/v1/emails/{emailId}/edit")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"prompt\": \"<string>\",\n \"label\": \"<string>\",\n \"async\": false\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"data": {
"id": "<string>",
"emailId": "<string>",
"conversationId": "<string>",
"messageId": "<string>",
"slotIdx": 123,
"slotUuid": "<string>",
"status": "<string>",
"subject": "<string>",
"preheader": "<string>",
"html": "<string>",
"thumbnailUrl": "<string>",
"warnings": [
"<string>"
],
"updatedAt": "2023-11-07T05:31:56Z",
"screenshotUrl": "<string>"
},
"error": "<string>"
}{
"success": true,
"data": {
"editId": "<string>",
"emailId": "<string>",
"conversationId": "<string>",
"status": "pending",
"stage": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"pollAfterMs": 123,
"error": "<string>",
"changesMayHaveBeenSaved": true,
"result": {
"id": "<string>",
"emailId": "<string>",
"conversationId": "<string>",
"messageId": "<string>",
"slotIdx": 123,
"slotUuid": "<string>",
"status": "<string>",
"subject": "<string>",
"preheader": "<string>",
"html": "<string>",
"thumbnailUrl": "<string>",
"warnings": [
"<string>"
],
"updatedAt": "2023-11-07T05:31:56Z",
"screenshotUrl": "<string>"
}
},
"error": "<string>"
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}{
"success": false,
"error": "<string>",
"code": "<string>",
"data": {}
}Authorizations
API key authentication. Use 'Authorization: Bearer YOUR_API_KEY' where YOUR_API_KEY is obtained from the Migma dashboard under Settings → Developers → API Keys.
Headers
Optional key of at most 100 characters for async edits only. For the same authenticated API key and email, reusing the key with the same prompt and label returns the same job; a conflicting body returns 409 IDEMPOTENCY_CONFLICT. The receipt remains available for at least 24 hours after terminal completion under normal cleanup. Reuse the same key after an uncertain async start.
100Path Parameters
Email ID returned in generation status result.emails[].emailId.
^[0-9a-fA-F]{24}$Body
Natural-language edit request, e.g. "Make this shorter and more transactional".
1 - 20000Optional version label.
1 - 120Set true to durably enqueue the edit and return 202. Omit or set false to keep the existing synchronous 200 Email response.
Was this page helpful?