> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit Sequence Emails with AI

> Change a sequence's emails with AI in one request

Changes the emails of a sequence with AI in one request, like the Emails view in the sequence editor. Say what should change in `prompt`, in any language: "make the background cream", "remove the header", "give email 2 a new structure".

Without `emailIds`, the prompt decides which emails change: every email, unless it names some ("email 2", "the last email"). With `emailIds`, only those emails change. With `sectionIds` and exactly one email, only those top-level blocks change and everything else stays exactly as it is.

When the request asks for a new look without saying exactly what ("more premium", "bolder colors"), the first email is redesigned, then the others are restyled in its design. Every email gets exactly the same theme, and every email's headings, buttons and other blocks are styled exactly like the first one's. Kinds of blocks that email doesn't have, like a callout or a table, are styled like the first email that has them. Text that would no longer be readable on its background gets a readable color. When it asks several emails for the same new text or style, like a new footer line or a button color, the AI decides the wording and values once and puts exactly the same in each email.

A request to make emails look like one of them ("make them all look like email 1") copies that email's style exactly, with no AI: its theme, font and the style of each kind of block, while every email keeps its own words. With `emailIds`, only those emails change; listing only the email to copy returns a `400`. A request for design variations of an email ("make a few variations of email 1") returns a `400` here: use [Generate Sequence Email Variations](./email-variations-generate).

Each email succeeds or fails on its own. Changed emails are saved unless `dryRun` is `true`, and on an active sequence they go out with the next sends. An email written in HTML is edited as HTML and keeps its theme. A/B test steps and steps without an email are skipped and listed in `skipped`. To set exact values instead of asking the AI, use [Update Sequence](/api-reference/sequences/update).

The request runs synchronously and can take up to a minute. One request edits up to 12 emails; pass `emailIds` to edit a longer sequence in batches. If your client times out, read the sequence with [Get Sequence](/api-reference/sequences/get) before sending the request again: changes may already be saved, and sending it again changes them again.

When the AI can't tell which emails a request without `emailIds` is about, nothing changes and you get a `503`: send it again, or pass `emailIds`. An email saved somewhere else while the AI worked on it is not overwritten: it comes back with `saved: false` and an `error`.

## Request

<ParamField path="sequenceId" type="string" required>
  Sequence ID.
</ParamField>

<ParamField body="prompt" type="string" required>
  What should change, 1 to 2,000 characters, in any language.
</ParamField>

<ParamField body="emailIds" type="string[]">
  Only change these emails (1 to 12), using the `emailId` of each step from
  [Get Sequence](/api-reference/sequences/get). Omit to let the prompt decide.
  An ID that is not an editable email of this sequence is a `400`.
</ParamField>

<ParamField body="sectionIds" type="string[]">
  Only change these top-level blocks (up to 50). Needs exactly one `emailIds`
  entry.
</ParamField>

<ParamField body="dryRun" type="boolean" default="false">
  Return the new content without saving it.
</ParamField>

```bash theme={null}
curl -X POST "https://api.sequenzy.com/api/v1/sequences/seq_abc123/emails/edit" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "prompt": "Make the background cream and remove the header" }'
```

## Response

<ResponseField name="dryRun" type="boolean">
  Whether the changes were only returned, not saved.
</ResponseField>

<ResponseField name="emails" type="object[]">
  One entry per email the request worked on, in sending order.

  <Expandable title="properties">
    <ResponseField name="emailId" type="string">Email ID.</ResponseField>
    <ResponseField name="nodeId" type="string">The sequence step's node ID.</ResponseField>

    <ResponseField name="label" type="string">
      How the editor names the step: `Email 2`, or `Email 3a` when parallel
      branches share a step number.
    </ResponseField>

    <ResponseField name="status" type="string">
      `changed`, `unchanged` (the AI found nothing to change; `summary` says
      why) or `failed`.
    </ResponseField>

    <ResponseField name="saved" type="boolean">
      Whether the change was saved. Always `false` on a dry run and for
      unchanged or failed emails.
    </ResponseField>

    <ResponseField name="summary" type="string | null">
      What changed, or why nothing did. Null for failed emails.
    </ResponseField>

    <ResponseField name="error" type="string | null">
      Why the email failed, or why a change couldn't be saved. Send the
      request again for that email.
    </ResponseField>

    <ResponseField name="subject" type="string | null">
      The email's subject after the change. Null unless `changed`.
    </ResponseField>

    <ResponseField name="previewText" type="string | null">
      The email's preview text after the change. Null unless `changed`.
    </ResponseField>

    <ResponseField name="blocks" type="object[] | null">
      The email's blocks after the change. Null unless `changed`.
    </ResponseField>

    <ResponseField name="emailTheme" type="object | null">
      The email's theme after the change. Null when it uses the company's
      theme, or unless `changed`.
    </ResponseField>

    <ResponseField name="fontFamily" type="string | null">
      The email's body font after the change. Null when it uses the
      company's font, or unless `changed`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="skipped" type="object[]">
  Email steps the AI can't edit here, each with `nodeId`, `label`, `emailId`
  (null when there is none) and `reason`: `ab_test` (edit each variant with
  [Update A/B Test Variant](/api-reference/ab-tests/update-variant)), `no_email`, or `shared_email` (the step sends
  the same email as an earlier one, which is edited once).
</ResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "dryRun": false,
    "emails": [
      {
        "emailId": "email_1",
        "nodeId": "node_1",
        "label": "Email 1",
        "status": "changed",
        "saved": true,
        "summary": "Removed the header and made the background cream.",
        "error": null,
        "subject": "Welcome to Acme",
        "previewText": "Here's how to get started",
        "blocks": [
          { "id": "h1", "type": "heading", "content": "Welcome to Acme", "level": 1 }
        ],
        "emailTheme": { "presetId": "branded", "colors": { "background": "#fdf6e3" } },
        "fontFamily": null
      },
      {
        "emailId": "email_2",
        "nodeId": "node_3",
        "label": "Email 2",
        "status": "unchanged",
        "saved": false,
        "summary": "This email has no header to remove.",
        "error": null,
        "subject": null,
        "previewText": null,
        "blocks": null,
        "emailTheme": null,
        "fontFamily": null
      }
    ],
    "skipped": [
      { "nodeId": "node_5", "label": "Email 3", "emailId": null, "reason": "ab_test" }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": "sectionIds can only be used together with exactly one emailId."
  }
  ```
</ResponseExample>

## Errors

| Status | Meaning |
| - | - |
| `400` | `prompt` is empty, an `emailIds` entry is not an editable email of this sequence, `sectionIds` was sent without exactly one email, the prompt names only emails the sequence doesn't have, the request covers more than 12 emails, or the sequence has no emails the AI can edit. |
| `401` | Missing or invalid API key. |
| `403` | The API key lacks the `sequences:write` scope. |
| `404` | The sequence was not found. |
| `422` | The request body is invalid, for example an empty `emailIds` list. |
| `500` | The request failed before any email was changed. Send it again. |
| `503` | The AI couldn't tell which emails the request is about, and nothing changed. Send it again, or pass `emailIds`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.