Optimize a cold email
One cold email written by Amdahl with no data connected: the context to send, and every part of the answer read end to end, the returned message, 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 get_setup_status tool) says why; see Check your setup.
This walkthrough asks Amdahl for one cold email on its default setting, which needs no connected data, and reads every field that comes back. Amdahl writes the message from the context you send and evaluates it without your data. A draft is optional: see Context.
The call
One recipient per call. Send what you know about them, one fact per entry, and the ask as a rule:
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 310 \
-d '{
"channel": "email",
"context": {
"facts": [
"Sam Ortiz is Head of RevOps at Brightpath, a 200-person logistics software company.",
"Brightpath posted three SDR roles last week.",
"We sell Relay, which drafts first-touch emails from CRM notes.",
"A 150-person sales team cut SDR ramp from 90 to 45 days with Relay."
],
"rules": ["Ask for a 20-minute call next week."]
}
}' | jqOver MCP it is the optimize_message tool with the same fields. In the console it is the Outbound optimization tool on the Developers page.
It usually answers in 1 to 2 minutes, on the same call: there is nothing to poll. A call can run for up to 300 seconds before it gives up, so give your client 310.
The two responses below were recorded when Amdahl still improved every draft. Their fields read the same way today, with two differences. With no draft, extraction holds at most channel. And a run written from context, with or without a draft, never returns kept. Today a response also carries omitted: what the message left out because the context could not back it, each with why. With on_missing_input: "ask", a context that cannot support the request gives outcome: "needs_input" instead, and ask lists what to add.
What comes back: a rewrite
This run was sent a draft, the one the console's Use a sample button filled in. The draft:
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,
AlexWhat came back:
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,
AlexThe full response, with three of its notes shown:
{
"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 | The evaluation without your data: the draft was evaluated on how it reads, not on whether its claims are true. |
lift | null | Normal without your data. No before-and-after score was measured. Instead the evaluation model, a second model, re-evaluated the rewrite on yes/no questions for anything it made worse. The rewrite_checked_yes_no note says so. |
unsupported_claims | null | Claims were not evaluated. That needs your customers' own conversations; see Evaluate 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. Without your data, Amdahl improves how a message reads. It does not invent a better claim for you, and it is built not to. The first note shows this 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:
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,
BenThe response, with message (your draft, verbatim) left out and three of its notes shown:
{
"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 scored. That is the first note. It is Amdahl keeping your details exact, 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:
saysis 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 Amdahl'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 evaluation criteria, 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:
{
"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 Amdahl's 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 are Amdahl's own scoring 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 evaluated 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 Amdahl 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 run without your data 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 evaluated against your customers. |
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 of the message. - Your voice and house rules.
contextcarries the sender'srules, emails they wrote, and the facts. See Keep your voice, rules and facts. - A whole campaign. One call per recipient, from a spreadsheet. See Optimize a campaign.
- Every message your code sends. See Optimize before you send.
- What Amdahl knows about the recipient. Send
recipientand Amdahl adds the profile and the brief from your own data. See Context. - Every claim evaluated against your customers. Once your conversations are connected, add
"evidence": "workspace". Amdahl then evaluates every claim against your customers' own conversations. See Evaluate claims against your customers.
Every field and error is on Optimize a message.