Message Optimizer skill reference
The detail behind step 1 of the Message Optimizer skill: check setup with get_setup_status, fix each blocker, create an API key for a server or CI, and read every refusal and ok-false reason.
The Message Optimizer skill keeps its first step short. This page holds the detail it points to. Load it when a call is refused, when you run on a server or in CI, or when ok comes back false.
Check your setup
One read tells you whether this credential can optimize, and what to fix if it cannot. It changes nothing and works on every key and connector.
- MCP: the
get_setup_statustool. It takes no other parameters. - REST:
GET https://app.amdahl.ai/api/platform/v1/setup/status.
curl -s https://app.amdahl.ai/api/platform/v1/setup/status \
-H "X-API-Key: $AMDAHL_KEY" | jq '.data.optimize'Read optimize:
allowed: true: go ahead and optimize.allowed: false:blockernames the one thing to fix (table below).quota: this month's optimizations for API and connector calls, aslimit,used,remainingandresets_at. It isnullwhen the caller is not metered.
The same response names the workspace (its name under workspace), who is calling (email and role under caller) and how (auth_method). Use them to confirm the user connected the workspace they meant. The full response is on Connections.
Fix each blocker
optimize.blocker | What it means | Tell the user |
|---|---|---|
missing_scope | The credential does not carry messages:execute. It is a Read only key, a key older than the Message Optimizer, or a connector authorized before the Message Optimizer existed. | With a key: create a new key with Access set to Customer agent (steps below). With a connector: disconnect and reconnect Amdahl (in Claude: Settings, then Connectors) and sign in again. |
role_too_low | Their workspace role is Viewer. Optimizing needs Editor or above. | Ask a workspace admin to raise their role. |
quota_exhausted | The workspace used this month's API and connector optimizations. | Wait until quota.resets_at. |
Use an API key on a server or in CI
A server, a CI job or a terminal agent with no Amdahl connector uses the REST API with an API key in the environment variable AMDAHL_KEY.
- Check whether the key is available, in the environment or in a
.envfile in the project folder:test -n "$AMDAHL_KEY" || grep -q '^AMDAHL_KEY=' .env 2>/dev/null && echo set. Never print its value. - If it is not set, the user creates one in their terminal:
npx @amdahl/cli login, thennpx @amdahl/cli keys create --name "Optimizer" --preset agent.- The terminal shows a code and opens the console. The user types the code there and clicks Approve. The terminal prints the key once; it starts with
amdhl_. - Without a terminal, the user creates it in the console instead: console.amdahl.ai, Settings, then Developer, Create key, with Access kept at Customer agent (the default).
- Save it in a
.envfile so it lasts beyond this session. Tell the user to open the.envfile in their project folder in their editor (create it if there is none) and add one line,AMDAHL_KEY=amdhl_..., with their key in place ofamdhl_.... Editing the file keeps the key out of the chat and out of their shell history. - Make sure
.envis listed in.gitignoreso the key is never committed. Check it yourself, and if it is missing, ask before adding the line.envto.gitignore. - Nothing needs restarting: load the file before each call (
set -a; [ -f .env ] && . ./.env; set +a).
- If the user pastes a key into the chat instead, say once that a key in a chat stays in its history and suggest the environment variable. If they still want to go ahead, use it for this session only, and remind them to revoke it when done (
amdahl keys revoke <prefix>, or Settings, then Developer).
No workspace yet? Amdahl is in beta. They can try the optimizer at console.amdahl.ai/try with 25 free runs, which also puts them on the waitlist, or join the waitlist at console.amdahl.ai/new. Amdahl emails them when they are in. If their company already uses Amdahl, an admin there can add them instead.
Codex users who connect over MCP rather than a key: npx amdahl (or npx amdahl install codex for Codex alone) adds the server with required = true, so Codex waits for Amdahl before it starts. Then codex mcp login amdahl signs in.
Refusals
| What you see | What it means | Tell the user |
|---|---|---|
200 (REST), or the optimize_message tool is listed (MCP) | Connected: the key or sign-in works and the workspace answers. | "You're connected. Let's optimize your first email." |
401 | The key is missing, wrong, revoked or expired. | Create a new Customer agent key. |
403, "Missing required scope(s): messages:execute" (MCP: "optimize_message requires the messages:execute scope") | The key is Read only, or older than the Message Optimizer. Over MCP, the connector was authorized before the Message Optimizer existed. | Create a new Customer agent key, or reconnect the connector. |
403, Role "viewer" is below required "editor" | Their workspace role is Viewer. Optimizing needs Editor or above. | Ask a workspace admin to raise their role. |
429, quota_exceeded | The workspace used this month's optimizations. | Stop the batch. Check quota.resets_at with get_setup_status. |
429, rate_limited | The workspace has too many optimizes running (3 at once) or started (12 a minute). Nothing is wrong with the key. | Nothing. Wait error.details.retry_after_seconds, then send the same request again. For more than a few emails, use a batch (below). When error.details.reason is optimizer_unavailable, the Message Optimizer is down: stop the list and send one request after the wait. |
When you are not sure which one applies, run the setup check above: optimize.blocker names it.
When ok is false
Nothing was written and there is no message. Keep the context you gathered, so you can send it again.
reason or error.code | Tell the user |
|---|---|
optimizer_timeout | It did not finish in time. Stop the batch. Wait retry_after_seconds (one minute when the response gives none), then try that one recipient once more. Continue only when it succeeds. |
optimizer_error | Something went wrong on Amdahl's side, and the Message Optimizer may be down. Stop the batch: the next request would fail the same way. Wait retry_after_seconds (one minute when the response gives none), then try one request. Continue only when it succeeds. Never retry in a loop. |
optimizer_unconfigured | The Message Optimizer is not available on this workspace. Stop and tell them to contact Amdahl. |
quota_exceeded (429 over REST) | The workspace used this month's API and connector optimizations (1,000). Stop the batch. It resets next month. |
rate_limited (429 over REST) | Nothing yet: the workspace has too many optimizes running or started in the last minute. Wait error.details.retry_after_seconds, send the same request again, and run one at a time, never more than 3 at once. To run a whole list, queue a batch (below) instead of a loop. When error.details.reason is optimizer_unavailable, the Message Optimizer is down and calls to it are stopped for up to 30 seconds: stop the batch, wait error.details.retry_after_seconds, then try one request. Continue only when it succeeds. |
Many emails: use a batch
In a chat, three to five emails as a sample is the right amount, and the campaign script is the right tool for the rest. When the user wants a whole list run anyway, or you run on a server, do not loop over optimize: single optimizes are limited to 3 running at once and 12 started a minute per workspace. Queue the list as one batch. A batch is accepted at once and is never refused as busy. Its items run later, behind single calls. Each item carries its own context with that recipient's facts. An item takes every field a single optimize takes, recipient included, with the same rules.
- MCP: the
optimize_message_batchtool with{"items": [...]}. Each item takescontext(with that recipient'sfacts) and the optionaloptimizeparams (channel,evidence,on_unsupported,include_tries), plus an optionalitem_idof your own that comes back with its result. Up to 500 items. Send anidempotency_keyto make a retry safe. - REST:
POST https://app.amdahl.ai/api/platform/v1/messages/optimize/batchwith the same body. It answers202.
Both return a batch_id with counts, queue_position and eta. Then read the batch until status is completed:
- MCP: the
get_message_batchtool with{"batch_id": "..."}. Add"status": "done"to get only the finished items, and page withlimitandcursor. - REST:
GET https://app.amdahl.ai/api/platform/v1/messages/optimize/batches/<batch_id>.
Tell the user:
- The items are queued, how many, and the
etaas an estimate ("about 20 minutes, as an estimate").etaandqueue_positionare estimates, never a promise. - Poll every 15 to 30 seconds at most. Do not call
optimizefor the same recipients while the batch runs. - Each item's
resulthas the same fields as oneoptimizeresult, and isnulluntil that item has run. Read it the same way:outcome, thenmessage,askandnotes. - A
completedbatch can hold failed items: readcounts.failed. A failed item hasok: falseand areason. It was not charged. - A batch refused with
quota_exceededqueued nothing:error.details.remainingsays how many items would fit this month.