Optimize a cold email

One outbound draft through the Message Optimizer with no data connected, and every part of the answer read end to end: the returned version, a kept draft and the edits it suggests, the notes worth relaying, and what the default pass does to your ask.

Level: first run. Call: messages.optimize. You need: a Customer agent key (see Quickstart), or the Amdahl MCP connector. No connected data. If the call is refused, GET /setup/status (over MCP, the connections tool with "action": "setup_status") says why; see Check your setup.

This walkthrough sends two cold emails through the Optimizer on its default setting, a style pass that needs nothing but the draft, and reads every field that comes back. The drafts, names and companies are made up. The responses are real ones from the live API, trimmed only where the text says so, with their notes in the wording the Optimizer uses now.

The call

One draft per call, sent exactly as you would send it:

bash

curl -s -X POST "https://app.amdahl.ai/api/platform/v1/messages/optimize" \
  -H "X-API-Key: $AMDAHL_KEY" \
  -H "Content-Type: application/json" \
  --max-time 180 \
  -d '{
    "message": "Hi Sam,\n\nI hope this email finds you well. I wanted to reach out because our platform helps revenue teams save time and increase efficiency with AI-powered insights across the entire sales cycle.\n\nWe work with many leading companies and I think we could add a lot of value to your team as well. Would you be open to a 30 minute call next week to learn more?\n\nBest,\nAlex",
    "channel": "email"
  }' | jq

Over MCP it is the messages tool with "action": "optimize" and the same fields. In the console it is the Message optimizer box on the API Playground page, which takes the same draft and shows the same answer.

It usually answers in under 30 seconds, on the same call: there is nothing to poll. A call can run for up to 170 seconds before it gives up, so give your client 180.

What comes back: a rewrite

The draft above is the one the console's Use a sample button fills in. Your draft:

text

Hi Sam,

I hope this email finds you well. I wanted to reach out because our platform helps revenue teams save time and increase efficiency with AI-powered insights across the entire sales cycle.

We work with many leading companies and I think we could add a lot of value to your team as well. Would you be open to a 30 minute call next week to learn more?

Best,
Alex

What came back:

text

Hi Sam,

I wanted to reach out because we help revenue teams save time and increase efficiency with AI-powered insights across the entire sales cycle.

Is that something you're running into on your side?

Best,
Alex

The full response, with three of its notes shown:

json

{
  "data": {
    "ok": true,
    "message": "Hi Sam,\n\nI wanted to reach out because we help revenue teams save time and increase efficiency with AI-powered insights across the entire sales cycle.\n\nIs that something you're running into on your side?\n\nBest,\nAlex",
    "summary": "Rewrote it to improve how clear the ask is and how human it sounds. This was a style pass only. Its claims were not checked against your workspace's conversations.",
    "unchanged": false,
    "run_id": "c516bbe5-...",
    "extraction": { "receiver_name": "Sam", "channel": "email" },
    "lift": null,
    "evidence": { "requested": "off", "used": false, "reason": "not_requested" },
    "on_unsupported": "flag",
    "unsupported_claims": null,
    "notes": [
      {
        "code": "rewrite-rejected-for-entity-loss",
        "audience": "sender",
        "says": "A rewrite was discarded because it dropped or changed a name, link or placeholder that must stay exactly as written, or changed or added a number, day or time the draft did not have: 15. The previous version stands. The score played no part in this: it does not matter how well the rewrite scored."
      },
      {
        "code": "rewrite_checked_yes_no",
        "audience": "sender",
        "says": "Re-checked independently (a different model from the one that picked the rewrite) on yes/no questions, each asked twice of the draft and of the rewrite: it did not consistently lose a clear ask, a human tone or concision, and it was not found to add a claim the draft did not make. This is a pass/fail check, not a before-and-after score."
      },
      {
        "code": "style_pass_only",
        "audience": "sender",
        "says": "This was a style pass only. The draft was graded on how it reads, and its claims were not checked against the workspace's conversations. A style pass does not mean that the draft passed or that it is ready to send."
      }
    ]
  }
}

Read it in this order:

Field	Here	What it tells you
`ok`	`true`	A result came back. On `false` there is no `message` at all; read `reason` and keep the draft.
`unchanged`	`false`	The version in `message` is a rewrite, not your own text.
`message`	the rewrite	The version to show as "after". Show it as returned: do not polish it with another model before a person sees it. To change it, re-run with the change as one of the `rules`, or let the person edit it.
`summary`	one line	What the rewrite aimed at, in words safe to show a person.
`evidence`	`used: false`, `not_requested`	A style pass: the draft was judged on how it reads, not on whether its claims are true.
`lift`	`null`	Normal on a style pass. No before-and-after score was measured; instead a second model re-checked the rewrite on yes/no questions for anything it made worse, which is what the `rewrite_checked_yes_no` note says.
`unsupported_claims`	`null`	Claims were not checked. That needs your conversations; see Check claims against your customers.
`extraction`	`receiver_name`, `channel`	What it read out of the draft. A key it could not find is absent rather than guessed.
`notes`	facts about the run	Below, under Which notes to relay.

What changed, and why the ask moved. The stock opener and the "many leading companies" line are gone, and the meeting request became a question the reader can answer in one line. That last change is deliberate: the default pass prefers a close that asks whether the problem is real for the reader over a request for 30 minutes of their calendar. If your process needs the meeting ask, say so in rules. A rewrite that breaks one of your rules is never returned, so the worst case is your own draft back.

What it did not touch. The claim in the second line ("save time and increase efficiency with AI-powered insights") is as generic as it was. A style pass improves how a message reads; it does not invent a better claim for you, and it is built not to. The first note shows that guard at work: one rewrite was thrown away because it added a figure (15) the draft never had.

What comes back: your draft, kept

The second draft has more wrong with it, and comes back unchanged. Your draft:

text

Hi Maria,

I hope you're having a great week! My name is Ben and I'm reaching out from Fieldnote, the leading AI-powered field service platform trusted by innovative companies across the globe.

I noticed that Cobalt Plumbing recently opened two new locations in Denver — congrats on the growth! As you scale, I imagine scheduling technicians, routing jobs and keeping customers updated gets more complex. Fieldnote helps companies like yours streamline operations, boost technician productivity and deliver exceptional customer experiences, all in one easy-to-use platform.

Our customers typically see significant improvements in efficiency and customer satisfaction. We'd love to show you how Fieldnote could help Cobalt Plumbing achieve similar results.

Would you be open to a quick 30-minute demo sometime next week? Let me know what time works best for you!

Best regards,
Ben

The response, with message (your draft, verbatim) left out and three of its notes shown:

json

{
  "data": {
    "ok": true,
    "summary": "Kept your version: the rewrite dropped or changed a name or link that has to stay exact, or changed a number, so it was discarded. This was a style pass only. Its claims were not checked against your workspace's conversations.",
    "unchanged": true,
    "run_id": "27e0f334-...",
    "extraction": {
      "receiver_name": "Maria",
      "company": "Cobalt Plumbing",
      "signal": "Cobalt Plumbing recently opened two new locations in Denver",
      "channel": "email"
    },
    "lift": null,
    "evidence": { "requested": "off", "used": false, "reason": "not_requested" },
    "on_unsupported": "flag",
    "unsupported_claims": null,
    "notes": [
      {
        "code": "rewrite-rejected-for-entity-loss",
        "audience": "sender",
        "says": "A rewrite was discarded because it dropped or changed a name, link or placeholder that must stay exactly as written, or changed or added a number, day or time the draft did not have: 20, Cobalt Plumbing. The previous version stands. The score played no part in this: it does not matter how well the rewrite scored."
      },
      {
        "code": "draft-contains-em-dash",
        "audience": "sender",
        "says": "Your draft has an em dash or en dash, which reads as machine-written. We left your text as written; replace the dash with a comma or period before sending."
      },
      {
        "code": "style_pass_only",
        "audience": "sender",
        "says": "This was a style pass only. The draft was graded on how it reads, and its claims were not checked against the workspace's conversations. A style pass does not mean that the draft passed or that it is ready to send."
      }
    ],
    "kept_suggestions": [
      {
        "kind": "clarify_ask",
        "says": "End with one clear, low-effort ask the recipient can answer in a line.",
        "dimension": "cta_clarity",
        "why": "The email closes by asking for a meeting ('Would you be open to a quick 30-minute demo sometime next week?'), not by asking a yes-or-no diagnostic question about whether the problem itself is real for the recipient."
      },
      {
        "kind": "shorten",
        "says": "Shorten to about 90 words (under 600 characters); it is 131 words (864 characters) now."
      },
      {
        "kind": "replace_generic_line",
        "span": "My name is Ben and I'm reaching out from Fieldnote, the leading AI-powered field service platform trusted by innovative companies across the globe.",
        "says": "Replace this stock line with a plain one in your own words: \"My name is Ben and I'm reaching out from Fieldnote, the leading AI-powered field service platform trusted by innovative companies across the globe.\""
      },
      {
        "kind": "replace_dash",
        "says": "Replace the dash that joins two clauses with a comma or a full stop."
      }
    ]
  }
}

Why it was kept. The rewrites that read better changed something that has to stay exact: one turned the "30-minute" demo into a 20-minute one, and one dropped the company name. Names, numbers, days, times, dates, links and merge fields such as {{first_name}} come back exactly as you wrote them, and a rewrite that changes one, or adds a day or a time you did not give, is discarded however well it graded. That is the first note. It is the guard working, not a failure.

What to do with a kept draft. unchanged: true means message is your own text. Never present it as an improvement. The work is in kept_suggestions, most useful first:

says is the edit, in wording that is safe to show a person as written.
span, when present, is the exact text in your draft the edit is about.
why, when present, is the grader's reasoning: context for the edit, never wording to put in the message.

Here that is four edits a person can make in a minute: end on a one-line question, cut to about 90 words, replace the stock introduction, and lose the dash. Make them and send the new version through again. If a detail was allowed to change (the demo could be 20 minutes), say so in the draft itself and run it again.

A suggestion is advice from the rubric, not a rule. If one conflicts with something the sender has decided, such as keeping the demo ask, the sender's decision wins: put it in rules and run the draft again. A kept draft gets no suggestion about a part of the message that a rule names, so the ask suggestion goes away.

When the draft needs details. A draft that scores too low is not rewritten at all, because a rewrite could only make up the missing details. It comes back with unchanged: true and an ask list: up to three questions that only the sender can answer, such as which account the email is for. Put them to the sender as written, add their answers to the draft and run it again. See Reading ask.

Every scored try

To show a person how their draft got there, add "include_tries": true to the same call:

json

{
  "message": "Hi Sam, ...",
  "channel": "email",
  "include_tries": true
}

The response then also carries tries: every version the run scored, your draft first (round 0), each with its Optimizer score and human_tone (1 to 5), the dimensions it aimed_at, and returned: true on the one that came back as message. Show the returned message first, exactly as it came back, then each try in order. On a kept draft, round 0 is the one returned.

Those scores come from the Optimizer's own grader during the search, so they show the path, not proof. Never quote the first try against the last as an improvement; lift is the only before-and-after to quote. See Reading tries.

Which notes to relay

notes are facts about the run, each { "code", "audience", "says" }. Branch on code, never on the wording of says. audience says who a note is for:

sender: about the draft or the version that came back, in plain words. Relay it to the person who wrote the draft, as written.
developer: how the run was graded and how to read the response. It can name fields and parameters. Act on it or log it, and do not show it to the sender.

A code has the same audience on every run, so filter on the field rather than on a list of codes. New codes appear as the Optimizer changes, and each one still says who it is for. Treat any audience other than sender as not for the sender.

The sender notes a style pass returns most often, and what to do with each:

`code`	What to do
`style_pass_only`	Do not call the draft ready to send: its claims were not checked.
`rewrite-rejected-for-entity-loss`	It names the detail a rewrite tried to change. Ask whether that detail may change, and re-run.
`draft-contains-em-dash`	It is an edit the sender can make.
`rewrite_vetoed_by_regrade`	It says why the best rewrite did not come back.

Variations

LinkedIn. Send "channel": "linkedin" for a connection note or a DM. It changes the length and format the message is judged against. Leave channel out when you are not sure; it is inferred from the draft.
Your voice and house rules. context carries the sender's rules, emails they wrote, and facts they know first-hand. See Keep your voice, rules and facts.
A whole campaign. One call per draft, from a spreadsheet. See Optimize a campaign.
Every draft your code sends. See Optimize before you send.
Claims checked against your customers. Once your conversations are connected, add "evidence": "workspace". See Check claims against your customers.

Every field and error is on Message Optimizer.