Skip to main content

​
Endpoints

Every change to an email’s HTML — an AI iteration or a direct code save — creates a new version on the email.
AI iteration is asynchronous. Posting a message returns 202 Accepted with a generation_id, and you poll the generation to track progress. Only one generation can run per email at a time.

​
Idempotency

POST /v1/emails/{emailId}/messages and POST /v1/emails/{emailId}/save-code accept an optional Idempotency-Key header. Retrying with the same key replays the stored result instead of creating a duplicate version. If a request with the same key is still being processed, the API returns 409 Conflict with error_code: "idempotency_in_progress".

​
Iterate With AI

Returns 202 Accepted with a generation_id to poll. Starting a second generation while one is running returns 409 Conflict with error_code: "generation_in_progress".

​
Save Code Directly

Creates a new version synchronously and returns 200 OK with the new generation_id and version. Unlike an AI iteration, saving code does not unapprove an approved email. Blocked while a generation is running.

​
Clone an Email

Duplicate an email — its content, versions, and assets — as a fresh draft attributed to the API principal. The clone is never approved, regardless of the source’s state, so approve it separately before sending. Optionally send {"name": "..."}; the name defaults to "{original name} (copy)". Returns 201 Created with the new email object. Accepts an optional Idempotency-Key header.

​
Update Metadata

Accepts the same optional fields as create except prompt: name, subject, preview_text, from_name, from_address, reply_to_email. Omit a field to leave it unchanged; pass null to clear nullable fields. Updating preview_text rewrites the preheader in the current HTML in place without creating a new version.

​
Plain Text

Every completed generation carries a plain-text alternative derived from its HTML. GET returns it; PUT overrides it with your own text; DELETE reverts to the auto-derived version. All three return the same shape: 200 OK

​
PUT Request Body

PUT and DELETE require a completed generation to exist, otherwise they return 400 Bad Request. stale_after_html_iteration flips to true when the HTML is iterated after an override — a signal to review or revert your custom plain text. The generation-scoped GET /v1/emails/{emailId}/generations/{generationId}/plain-text returns the same shape without the override flags.

​
Common Errors

Next: Approve & Manage Emails

Approve the email for sending, then list, retrieve, and delete emails.