What an agent needs before you let it near the send button

An email is the one thing software does that you cannot take back. A bad deploy can be rolled back. A bad database write can be restored. A bad email is in someone's inbox with your name on it, and the best you can do is send another one apologising.

So when we started letting coding agents call the Herald API, we watched closely. Three months and a few hundred thousand messages later, the pattern of mistakes was clear enough to design around.

The three mistakes

Retrying a send that succeeded. A request times out, the agent retries, and the person gets two copies. Humans make this mistake too, but agents make it on every timeout, forever. The fix is an idempotency key on every send, and the agent skill now insists on one. If the key matches a message we already accepted, we return that message and send nothing.

Sending to a list when a draft was wanted. An agent asked to "write the launch announcement" would, about one time in twenty, also send it. The instruction was ambiguous and the tool was available. The fix was to split the tools: draft creates a message and returns a preview link; send is a separate call that a key can be denied.

Ignoring rate limits. A new domain has a sending budget while it warms up. An agent that hits the limit would sleep for a second and try again, which is exactly the behaviour that gets a domain throttled by the receiving side. Now the API returns the time to wait, and the skill tells the agent to respect it.

What we shipped

• Scoped keys. Each key lists the tools it may call. Start an agent with draft and stats. Add send when you trust it.
• The skill file. A short document the agent reads before it writes any Herald code. It covers the key, the idempotency rule, the rate-limit header, and the cases where it should stop and ask.
• An MCP server. Six tools with tight schemas, so the agent cannot invent a parameter that does not exist.

The result is that the mistakes stopped. Not because the models got smarter, but because the tools stopped offering them the chance. That is the whole design principle: the API decides what a mistake can be, and it should decide that it cannot be a duplicate email to your entire list.

The agents page has the install commands. It takes about a minute.