Docs

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_status tool. It takes no other parameters.
  • REST: GET https://app.amdahl.ai/api/platform/v1/setup/status.
bash
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: blocker names the one thing to fix (table below).
  • quota: this month's optimizations for API and connector calls, as limit, used, remaining and resets_at. It is null when 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.blockerWhat it meansTell the user
missing_scopeThe 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_lowTheir workspace role is Viewer. Optimizing needs Editor or above.Ask a workspace admin to raise their role.
quota_exhaustedThe 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.

  1. Check whether the key is available, in the environment or in a .env file in the project folder: test -n "$AMDAHL_KEY" || grep -q '^AMDAHL_KEY=' .env 2>/dev/null && echo set. Never print its value.
  2. If it is not set, the user creates one in their terminal:
    • npx @amdahl/cli login, then npx @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 .env file so it lasts beyond this session. Tell the user to open the .env file 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 of amdhl_.... Editing the file keeps the key out of the chat and out of their shell history.
    • Make sure .env is listed in .gitignore so the key is never committed. Check it yourself, and if it is missing, ask before adding the line .env to .gitignore.
    • Nothing needs restarting: load the file before each call (set -a; [ -f .env ] && . ./.env; set +a).
  3. 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 seeWhat it meansTell 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."
401The 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_exceededThe workspace used this month's optimizations.Stop the batch. Check quota.resets_at with get_setup_status.
429, rate_limitedThe 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.codeTell the user
optimizer_timeoutIt 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_errorSomething 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_unconfiguredThe 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_batch tool with {"items": [...]}. Each item takes context (with that recipient's facts) and the optional optimize params (channel, evidence, on_unsupported, include_tries), plus an optional item_id of your own that comes back with its result. Up to 500 items. Send an idempotency_key to make a retry safe.
  • REST: POST https://app.amdahl.ai/api/platform/v1/messages/optimize/batch with the same body. It answers 202.

Both return a batch_id with counts, queue_position and eta. Then read the batch until status is completed:

  • MCP: the get_message_batch tool with {"batch_id": "..."}. Add "status": "done" to get only the finished items, and page with limit and cursor.
  • 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 eta as an estimate ("about 20 minutes, as an estimate"). eta and queue_position are estimates, never a promise.
  • Poll every 15 to 30 seconds at most. Do not call optimize for the same recipients while the batch runs.
  • Each item's result has the same fields as one optimize result, and is null until that item has run. Read it the same way: outcome, then message, ask and notes.
  • A completed batch can hold failed items: read counts.failed. A failed item has ok: false and a reason. It was not charged.
  • A batch refused with quota_exceeded queued nothing: error.details.remaining says how many items would fit this month.